TemplateUpdateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/certifyos/main/json-schema/certifyos-template-update-request-schema.json",
  "title": "TemplateUpdateRequest",
  "description": "Confirmed column-to-field mappings for a template. Used as the request body of `PUT /templates/{id}` and `PUT /templates/{id}/approve`; `PUT /templates/{id}` also echoes this shape back as its response.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/certifyos-template-api-openapi.yml#/components/schemas/TemplateUpdateRequest",
  "type": "object",
  "properties": {
    "jobType": {
      "$ref": "#/$defs/RosterJobType",
      "type": "string",
      "description": "Roster type of the template (`PRACTITIONER`, `FACILITY`, or `GROUP`). Selects the system-field catalog the mappings are validated against, so it must match the template's own type. `GROUP` requires the tenant's `supportGroupRosters` configuration to be enabled. On the `PUT /templates/{id}` response this is always `null`."
    },
    "fields": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Field"
      },
      "description": "Column mappings to record. Must contain one entry for every header column of the template's stored `template.csv` (unmapped columns cause a 400); columns to ignore must be sent with the `[skipped]` sentinel as `mappedKey`. Each non-skipped entry's `mappedKey` must be a known system field unless `mappedEntity` is provided."
    }
  },
  "$defs": {
    "Field": {
      "type": "object",
      "description": "One roster column and the Certify system field it maps to.",
      "properties": {
        "name": {
          "type": "string",
          "description": "CSV column header this mapping applies to, exactly as it appears in the roster file."
        },
        "mappedKey": {
          "type": "string",
          "description": "Key of the Certify system field this column maps to, from the field catalog returned by `GET /templates/fields`. The sentinel `[skipped]` marks a column the user explicitly chose not to map: skipped columns persist in the template/mappings CSVs but are excluded from the generated validation schema."
        },
        "mappedEntity": {
          "type": "string",
          "description": "Entity that owns the mapped attribute (for example `practitioner` or `location`). When set, `mappedKey` is accepted as-is instead of being validated against the system-field catalog."
        },
        "entityGroup": {
          "type": "string",
          "description": "Group label linking columns that belong to the same repeating entity instance (a multiple-value group), so related columns are ingested together."
        },
        "isRequired": {
          "type": "boolean",
          "description": "Whether every roster row must supply a value for this column; drives the `required` constraint in the generated validation schema."
        },
        "isStaticField": {
          "type": "boolean",
          "description": "Catalog metadata: whether the mapped system field is a static (fixed-value) field rather than one populated from roster data."
        },
        "isSingleSelect": {
          "type": "boolean",
          "description": "Catalog metadata: whether the mapped system field accepts a single value from a fixed option list."
        },
        "validationRegex": {
          "type": "string",
          "description": "Regular expression applied to this column's values during roster validation. Rows whose values do not match are rejected."
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of the mapped system field, from the field catalog."
        },
        "hasPattern": {
          "type": "boolean",
          "description": "Catalog metadata (CP-40222): true when the system field schema validates values with a regular expression. The expression itself is deliberately NOT exposed here — the mapping UI shows the plain-language `message.pattern` text instead, and `validationRegex` stays reserved for user-defined per-column rules so a catalog entry posted back as a mapping cannot tighten the generated schema."
        },
        "format": {
          "type": [
            "string",
            "null"
          ],
          "description": "JSON Schema `format` of the system field (`date`, `email`, `uri`, ...) when it has one. Catalog metadata for the mapping UI (CP-40222); the accepted formats are described in `message.format`."
        },
        "message": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {
            "type": "string"
          },
          "description": "Plain-language validation texts from the system field schema, keyed by the rule they describe (`pattern`, `format`, `enum`, `type`, `minLength`, `maxLength`). The mapping UI shows these instead of raw regexes (CP-40222). Absent when the schema defines none."
        },
        "conditionallyRequired": {
          "type": [
            "object",
            "null"
          ],
          "additionalProperties": {},
          "description": "When present, the field is required only under a tenant condition: `condition` names the tenant setting, `value` the value that triggers the requirement and `message` the explanation shown to users (CP-40222)."
        },
        "minLength": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int32",
          "description": "Minimum accepted length of the value, when the schema bounds it."
        },
        "maxLength": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int32",
          "description": "Maximum accepted length of the value, when the schema bounds it."
        },
        "enum": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Allowed values for enum-type system fields; roster values outside this list fail validation. Absent for free-form fields."
        },
        "separator": {
          "type": "string",
          "description": "Literal separator character used to split a single cell value into multiple tokens for multi-value attributes. Blank or absent defaults to a comma at schema-generation time."
        },
        "notes": {
          "type": [
            "string",
            "null"
          ],
          "description": "Free-text note on this template column, such as a pre-processing instruction. Stored per template in the `Notes` column of the template's mappings CSV; not used by validation or ingestion. Blank or absent means no note."
        },
        "singleSelect": {
          "type": "boolean"
        },
        "skipped": {
          "type": "boolean"
        }
      }
    },
    "RosterJobType": {
      "type": "string",
      "enum": [
        "PRACTITIONER",
        "FACILITY",
        "GROUP"
      ]
    }
  }
}