form.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://json.openmrs.org/form.schema.json",
  "$comment": "This schema is intended to guide authors of forms built for use in O3",
  "title": "O3 Form schema",
  "description": "This schema defines the expected values of a form schema built using the O3 Form Builder. These schemas are used to build forms for use in O3. The schema is based on the JSON Schema Draft 7 specification. For more information, see https://json-schema.org/specification.html",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The schema for this JSON document. Should point to the canonical URL for this document.",
      "default": "http://json.openmrs.org/form.schema.json"
    },
    "name": {
      "type": "string",
      "description": "Name of the form"
    },
    "uuid": {
      "type": "string",
      "description": "Unique identifier of the form. Autogenerated by the system",
      "default": "XXXX"
    },
    "encounterType": {
      "type": "string",
      "description": "The encounter type UUID that represents the encounter type that the form gets mapped to"
    },
    "pages": {
      "type": "array",
      "description": "An array of all the pages in this form. Pages are the the basic unit of a form. They are used to group related sections and questions together.",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "The label of the page"
          },
          "sections": {
            "type": "array",
            "description": "An array of all the sections of the page. Sections are used to group related questions together.",
            "items": {
              "type": "object",
              "properties": {
                "isExpanded": {
                  "oneOf": [{ "type": "boolean" }, { "type": "string" }],
                  "description": "Either a string or a boolean. \nIf a string value, 'true' means this section should always be rendered in an expanded state, whereas 'false' means it should be rendered in a collapsed state. \nIf a boolean value, true means this section should always be rendered in an expanded state, whereas false means it should be rendered in a collapsed state."
                },
                "label": {
                  "type": "string",
                  "description": "The label of the section"
                },
                "questions": {
                  "type": "array",
                  "description": "An array of all the questions in a section. Questions make up the fields of the form",
                  "items": { "$ref": "#/definitions/formField" }
                },
                "isHidden": {
                  "type": "boolean",
                  "description": "Determines if the section is hidden"
                },
                "isParentHidden": {
                  "type": "boolean",
                  "description": "Determines if the parent of the section is hidden"
                },
                "inlineRendering": {
                  "type": "string",
                  "enum": ["single-line", "multiline", "automatic"],
                  "description": "Inline rendering options"
                },
                "readonly": {
                  "oneOf": [{ "type": "string" }, { "type": "boolean" }],
                  "description": "Read-only flag"
                },
                "reference": {
                  "$ref": "#/definitions/formReference"
                },
                "hide": { "$ref": "#/definitions/hideProps" }
              }
            },
            "required": ["label", "questions"]
          },
          "isHidden": {
            "type": "boolean",
            "description": "Determines if the page is hidden"
          },
          "hide": { "$ref": "#/definitions/hideProps" },
          "isSubform": {
            "type": "boolean",
            "description": "Determines if the page is a subform"
          },
          "inlineRendering": {
            "type": "string",
            "enum": ["single-line", "multiline", "automatic"],
            "description": "Inline rendering options"
          },
          "readonly": {
            "oneOf": [{ "type": "string" }, { "type": "boolean" }],
            "description": "Read-only flag"
          },
          "subform": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the subform"
              },
              "package": {
                "type": "string",
                "description": "Package of the subform"
              },
              "behaviours": {
                "type": "array",
                "items": {}
              },
              "form": {
                "$ref": "#/definitions/formSchemaWithoutPostSubmissionActions"
              }
            },
            "description": "Subform information"
          }
        }
      },
      "required": ["label", "sections"]
    },
    "processor": {
      "type": "string",
      "description": "Determines the processor that mediates conversion of data between form data and the OpenMRS API"
    },
    "published": {
      "type": "boolean",
      "description": "Determines whether the form is published or not",
      "default": false
    },
    "retired": {
      "type": "boolean",
      "description": "Determines whether the form is retired or not"
    },
    "version": {
      "type": "string",
      "description": "Determines the version of the form"
    },
    "availableIntents": {
      "oneOf": [
        { "type": "string" },
        { "$ref": "#/definitions/availableIntents" }
      ],
      "description": "Determines the intents available for the form"
    },
    "inlineRendering": {
      "type": "string",
      "description": "Determines whether the form is rendered inline or not"
    },
    "referencedForms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "formName": {
            "type": "string",
            "description": "Name of the referenced form"
          },
          "alias": {
            "type": "string",
            "description": "Alias of the referenced form"
          }
        },
        "required": ["formName"]
      },
      "description": "Array of referenced forms"
    },
    "encounter": {
      "oneOf": [
        { "type": "string" },
        { "$ref": "#/definitions/openmrsEncounter" }
      ],
      "description": "Encounter information"
    },
    "allowUnspecifiedAll": {
      "type": "boolean",
      "description": "Determines if unspecified options are allowed for all"
    },
    "defaultPage": {
      "type": "string",
      "description": "Default page of the form"
    },
    "readonly": {
      "oneOf": [{ "type": "string" }, { "type": "boolean" }],
      "description": "Read-only flag"
    },
    "markdown": {
      "description": "Markdown content"
    },
    "postSubmissionActions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "actionId": { "type": "string" },
          "config": { "type": "object" }
        }
      },
      "description": "Post submission actions"
    },
    "formOptions": {
      "type": "object",
      "properties": {
        "usePreviousValueDisabled": { "type": "boolean" }
      },
      "description": "Form options"
    },
    "resultType": {
      "type": "string",
      "enum": ["warning", "error"],
      "description": "Type of validation result"
    },
    "errCode": {
      "type": "string",
      "description": "Error code (optional)"
    },
    "message": {
      "type": "string",
      "description": "Validation message"
    },
    "answerOptions": {
      "type": "object",
      "properties": {
        "hide": { "$ref": "#/definitions/hideProps" },
        "label": { "type": "string" },
        "concept": { "type": "string" }
      }
    },
    "repeatOptions": {
      "type": "object",
      "properties": {
        "addText": { "type": "string" },
        "limit": { "type": "string" },
        "limitExpression": { "type": "string" }
      }
    }
  },
  "required": ["name", "pages"],
  "definitions": {
    "formSchemaWithoutPostSubmissionActions": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "pages": { "type": "array", "items": {} },
        "processor": { "type": "string" },
        "uuid": { "type": "string" },
        "referencedForms": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "formName": { "type": "string" },
              "alias": { "type": "string" }
            },
            "required": ["formName"]
          }
        },
        "encounterType": { "type": "string" },
        "encounter": {
          "oneOf": [{ "type": "string" }, { "type": "object" }]
        },
        "allowUnspecifiedAll": { "type": "boolean" },
        "defaultPage": { "type": "string" },
        "readonly": { "type": ["string", "boolean"] },
        "inlineRendering": {
          "type": "string",
          "enum": ["single-line", "multiline", "automatic"]
        },
        "markdown": {},
        "formOptions": {
          "type": "object",
          "properties": {
            "usePreviousValueDisabled": { "type": "boolean" }
          }
        },
        "version": { "type": "string" }
      },
      "required": [
        "name",
        "pages",
        "processor",
        "uuid",
        "referencedForms",
        "encounterType"
      ]
    },
    "formReference": {
      "type": "object",
      "properties": {
        "form": { "type": "string" },
        "page": { "type": "string" },
        "section": { "type": "string" },
        "excludeQuestions": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["form", "page", "section"]
    },
    "hideProps": {
      "type": "object",
      "description": "An object that contains logic that determines whether a page or section or question should be hidden or not",
      "properties": {
        "hideWhenExpression": {
          "type": "string",
          "description": "JavaScript expression that determines whether a page or section or question should be hidden or not. If the expression evaluates to true, the page or section or question is hidden. If it evaluates to false, the page or section or question is shown."
        }
      }
    },
    "formField": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "description": "The label of the form field"
        },
        "type": {
          "type": "string",
          "description": "The type of the form field"
        },
        "questionOptions": {
          "$ref": "#/definitions/formQuestionOptions",
          "description": "Options specific to the question"
        },
        "id": {
          "type": "string",
          "description": "Unique identifier of the form field"
        },
        "uuid": {
          "type": "string",
          "description": "Unique identifier of the form field (optional)"
        },
        "groupId": {
          "type": "string",
          "description": "Identifier of the group this field belongs to (optional)"
        },
        "questions": {
          "type": "array",
          "items": { "$ref": "#/definitions/formField" },
          "description": "Array of sub-questions if this question is a group"
        },
        "value": {
          "description": "Value of the form field"
        },
        "hide": {
          "$ref": "#/definitions/hideProps",
          "description": "Properties to determine if the field should be hidden"
        },
        "isHidden": {
          "type": "boolean",
          "description": "Determines if the field is hidden"
        },
        "isParentHidden": {
          "type": "boolean",
          "description": "Determines if the parent of this question is hidden"
        },
        "fieldDependants": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Identifiers of fields dependent on this field"
        },
        "pageDependants": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Identifiers of pages dependent on this field"
        },
        "sectionDependants": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Identifiers of sections dependent on this field"
        },
        "required": {
          "oneOf": [
            {
              "type": "boolean"
            },
            {
              "type": "string"
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "referenceQuestionId": {
                  "type": "string"
                },
                "referenceQuestionAnswers": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "type",
                "referenceQuestionId",
                "referenceQuestionAnswers"
              ]
            }
          ]
        },
        "unspecified": {
          "type": "boolean",
          "description": "Determines if the field value is unspecified"
        },
        "disabled": {
          "type": "boolean",
          "description": "Determines if the field is disabled"
        },
        "isDisabled": {
          "type": "boolean",
          "description": "Specifies whether the field should be conditionally disabled based on a certain expression."
        },
        "readonly": {
          "oneOf": [
            { "type": "string", "description": "Readonly status as a string" },
            { "type": "boolean", "description": "Readonly status as a boolean" }
          ],
          "description": "Determines if the field is readonly"
        },
        "inlineRendering": {
          "type": "string",
          "enum": ["single-line", "multiline", "automatic"],
          "description": "Rendering type for inline display"
        },
        "validators": {
          "type": "array",
          "items": { "type": "object" },
          "description": "Array of validators for the field"
        },
        "behaviours": {
          "type": "array",
          "items": { "type": "object" },
          "description": "Array of behaviours for the field"
        },
        "questionInfo": {
          "type": "string",
          "description": "Additional information about the question"
        },
        "constrainMaxWidth": {
          "type": "boolean",
          "description": "Determines if the field should constrain its maximum width"
        },
        "meta": {
          "type": "object",
          "properties": {
            "concept": {
              "$ref": "#/definitions/openmrsResource",
              "description": "Concept related to the form field"
            }
          },
          "additionalProperties": true,
          "description": "Additional metadata for the field"
        },
        "historicalExpression": {
          "type": "string",
          "description": "JavaScript expression that resolves to a value from a previous encounter, if available. This value can be used to answer the question."
        }
      },
      "required": ["questionOptions", "id"],
      "description": "Definition of a form field"
    },
    "renderType": {
      "type": "string",
      "enum": [
        "select",
        "text",
        "date",
        "number",
        "checkbox",
        "checkbox-searchable",
        "datetime",
        "radio",
        "ui-select-extended",
        "repeating",
        "group",
        "content-switcher",
        "encounter-location",
        "encounter-provider",
        "textarea",
        "toggle",
        "fixed-value",
        "file",
        "drug",
        "multiCheckbox",
        "encounter-role",
        "problem",
        "workspace-launcher",
        "select-concept-answers",
        "markdown"
      ]
    },
    "formQuestionOptions": {
      "type": "object",
      "properties": {
        "extensionId": { "type": "string" },
        "extensionSlotName": { "type": "string" },
        "rendering": { "$ref": "#/definitions/renderType" },
        "concept": { "type": "string" },
        "max": { "type": "string" },
        "min": { "type": "string" },
        "isTransient": { "type": "boolean" },
        "maxLength": { "type": "string" },
        "minLength": { "type": "string" },
        "showDate": { "type": "string" },
        "showDateOptions": {
          "type": "object",
          "properties": {
            "validators": { "items": { "type": "object" } }
          }
        },
        "showCommentOptions": {
          "type": "object",
          "properties": {
            "validators": { "items": { "type": "object" } }
          }
        },
        "showComment": { "type": "string" },
        "answers": {
          "type": "array",
          "items": { "type": "object" }
        },
        "weeksList": {
          "oneOf": [
            { "type": "string" },
            {
              "type": "array",
              "items": { "oneOf": [{ "type": "string" }, { "type": "number" }] }
            }
          ]
        },
        "locationTag": { "type": "string" },
        "rows": { "oneOf": [{ "type": "string" }, { "type": "integer" }] },
        "toggleOptions": {
          "type": "object",
          "properties": {
            "labelTrue": { "type": "string" },
            "labelFalse": { "type": "string" }
          }
        },
        "repeatOptions": {
          "type": "object",
          "properties": {
            "addText": { "type": "string" },
            "limit": { "type": "string" },
            "limitExpression": { "type": "string" },
            "isCloned": { "type": "boolean" }
          }
        },
        "defaultValue": {},
        "calculate": {
          "type": "object",
          "properties": {
            "calculateExpression": { "type": "string" }
          }
        },
        "isDateTime": {
          "type": "object",
          "properties": {
            "labelTrue": { "type": "boolean" },
            "labelFalse": { "type": "boolean" }
          }
        },
        "usePreviousValueDisabled": { "type": "boolean" },
        "allowedFileTypes": {
          "type": "array",
          "items": { "type": "string" }
        },
        "allowMultiple": { "type": "boolean" },
        "datasource": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "config": { "type": "object" }
          }
        },
        "isSearchable": { "type": "boolean" },
        "workspaceName": { "type": "string" },
        "buttonLabel": { "type": "string" },
        "identifierType": { "type": "string" },
        "orderSettingUuid": { "type": "string" },
        "orderType": { "type": "string" },
        "programUuid": { "type": "string" },
        "workflowUuid": { "type": "string" },
        "comment": { "type": "string" },
        "selectableOrders": { "type": "array", "items": { "type": "object" } }
      }
    },
    "openmrsResource": {
      "type": "object",
      "properties": {
        "uuid": { "type": "string" },
        "display": { "type": "string" }
      },
      "additionalProperties": true
    },
    "openmrsEncounter": {
      "type": "object",
      "properties": {
        "uuid": { "type": "string" },
        "encounterDatetime": {
          "anyOf": [{ "type": "string" }, { "type": "string" }]
        },
        "patient": {
          "anyOf": [
            { "$ref": "#/definitions/openmrsResource" },
            { "type": "string" }
          ]
        },
        "location": {
          "anyOf": [
            { "$ref": "#/definitions/openmrsResource" },
            { "type": "string" }
          ]
        },
        "encounterType": {
          "anyOf": [
            { "$ref": "#/definitions/openmrsResource" },
            { "type": "string" }
          ]
        },
        "obs": {
          "type": "array",
          "items": { "$ref": "#/definitions/openmrsObs" }
        },
        "orders": {
          "type": "array",
          "items": { "$ref": "#/definitions/openmrsResource" }
        },
        "voided": { "type": "boolean" },
        "visit": {
          "anyOf": [
            { "$ref": "#/definitions/openmrsResource" },
            { "type": "string" }
          ]
        },
        "encounterProviders": {
          "type": "array",
          "items": { "type": "object" }
        },
        "form": {
          "type": "object",
          "properties": {
            "uuid": { "type": "string" }
          },
          "additionalProperties": true
        }
      }
    },
    "openmrsObs": {
      "type": "object",
      "properties": {
        "uuid": { "type": "string" },
        "display": { "type": "string" },
        "concept": { "$ref": "#/definitions/openmrsResource" },
        "obsDatetime": {
          "anyOf": [{ "type": "string" }, { "type": "string" }]
        },
        "obsGroup": { "$ref": "#/definitions/openmrsObs" },
        "groupMembers": {
          "type": "array",
          "items": { "$ref": "#/definitions/openmrsObs" }
        },
        "comment": { "type": "string" },
        "location": { "$ref": "#/definitions/openmrsResource" },
        "order": { "$ref": "#/definitions/openmrsResource" },
        "encounter": { "$ref": "#/definitions/openmrsResource" },
        "voided": { "type": "boolean" },
        "value": {},
        "formFieldPath": { "type": "string" },
        "formFieldNamespace": { "type": "string" },
        "status": { "type": "string" },
        "interpretation": { "type": "string" }
      },
      "required": [
        "concept",
        "obsDatetime",
        "location",
        "order",
        "encounter",
        "voided",
        "value",
        "formFieldPath",
        "formFieldNamespace",
        "status",
        "interpretation"
      ]
    },
    "availableIntents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "intent": { "type": "string" },
          "display": { "type": "string" }
        }
      }
    }
  }
}