routes.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://json.openmrs.org/routes.schema.json",
  "$comment": "This schema is intended to help guide authors. When parsed, the schema may support additional properties added by our tooling, e.g., the version property.",
  "title": "OpenMRS Routes Schema",
  "description": "This schema defines the expected values of routes.json files provided by OpenMRS frontend modules. These files describe the pages, extensions, and requirements of the frontend module so they can be appropriately consumed by the app shell.",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The schema for this JSON document. Should point to the canonical URL for this document.",
      "default": "https://json.openmrs.org/routes.schema.json"
    },
    "backendDependencies": {
      "type": "object",
      "description": "A list of backend modules necessary for this frontend module and the corresponding required versions.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "optionalBackendDependencies": {
      "type": "object",
      "description": "A list of backend modules that may enable optional functionality in this frontend module if available and the corresponding required versions.",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {
              "version": {
                "type": "string",
                "description": "A SemVer range specifying the allowed versions"
              },
              "feature": {
                "type": "object",
                "description": "Details of the feature flag to be registered and enabled if this optional dependency is available.",
                "properties": {
                  "flagName": {
                    "type": "string",
                    "description": "A code-friendly name for the flag, which will be used to reference it in code"
                  },
                  "label": {
                    "type": "string",
                    "description": "A human-friendly name for the flag, which will be used when it needs to be displayed"
                  },
                  "description": {
                    "type": "string",
                    "description": "An explanation of what the flag does, which will be displayed in the Implementer Tools"
                  }
                },
                "required": [
                  "flagName",
                  "label",
                  "description"
                ]
              }
            },
            "required": [
              "version"
            ]
          }
        ]
      }
    },
    "pages": {
      "type": "array",
      "description": "An array of all pages provided by this frontend module. Pages are automatically mounted based on a route.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "component": {
            "type": "string",
            "description": "The name of the component exported by this frontend module."
          },
          "route": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ],
            "description": "Either a string or a boolean.\n If a string value, this is used to indicate that this page should be rendered. For example, \"name\" will match when the current page is ${window.spaBase}/name.\n If a boolean, this either indicates that the component should always be rendered or should never be rendered."
          },
          "routeRegex": {
            "type": "string",
            "format": "regex",
            "description": "A regular expression used to match against the current route to determine whether this page should be rendered. Note that ${window.spaBase} will be removed before attempting to match, so setting this to \"^name.+\" will match any route that starts with ${window.spaBase}/name."
          },
          "privilege": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "string"
              }
            ],
            "description": "One or more privileges that a user must have in order for this page to be available."
          },
          "online": {
            "type": "boolean",
            "description": "Determines whether the component renders while the browser is connected to the internet. If false, this page will never render while online.",
            "default": true
          },
          "offline": {
            "type": "boolean",
            "description": "Determines whether the component renders while the browser is not connected to the internet. If false, this page will never render while offline.",
            "default": true
          },
          "order": {
            "type": "integer",
            "description": "Determines the order in which the DOM element rendered this page is rendered. This should be used sparingly, but is sometimes necessary to ensure the resulting mark-up is correct.",
            "minimum": 0
          },
          "featureFlag": {
            "type": "string",
            "description": "The name of a feature flag that is defined in the system"
          }
        },
        "required": [
          "component"
        ],
        "oneOf": [
          {
            "required": [
              "route"
            ]
          },
          {
            "required": [
              "routeRegex"
            ]
          }
        ]
      }
    },
    "extensions": {
      "type": "array",
      "description": "An array of all extensions provided by this frontend module. Extensions can be mounted in extension slots, either via declarations in this file or configuration.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of this extension. This is used to refer to the extension in configuration."
          },
          "component": {
            "type": "string",
            "description": "The name of the component exported by this frontend module."
          },
          "slot": {
            "type": "string",
            "description": "If supplied, the slot that this extension is rendered into by default. Note that this is overridden by the slots property if that is also specified."
          },
          "slots": {
            "type": "array",
            "description": "If supplied, the slots that this extension is rendered into by default."
          },
          "privilege": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "string"
              }
            ],
            "description": "One or more privileges that a user must have in order for this extension to be available."
          },
          "online": {
            "type": "boolean",
            "description": "Determines whether the component renders while the browser is connected to the internet. If false, this page will never render while online.",
            "default": true
          },
          "offline": {
            "type": "boolean",
            "description": "Determines whether the component renders while the browser is not connected to the internet. If false, this page will never render while offline.",
            "default": true
          },
          "order": {
            "type": "integer",
            "description": "Determines the order in which this component renders in its default extension slot. Note that this can be overridden by configuration.",
            "minimum": 0
          },
          "meta": {
            "type": "object",
            "description": "Meta describes any properties that are passed down to the extension when it is loaded"
          },
          "featureFlag": {
            "type": "string",
            "description": "The name of a feature flag that is defined in the system"
          }
        },
        "required": [
          "component",
          "name"
        ]
      }
    },
    "featureFlags": {
      "type": "array",
      "description": "An array of feature flags declared by this module.",
      "items":{
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "flagName": {
            "type": "string",
            "description": "A code-friendly name for the flag, which will be used to reference it in code"
          },
          "label": {
            "type": "string",
            "description": "A human-friendly name which will be displayed in the Implementer Tools"
          },
          "description": {
            "type": "string",
            "description": "An explanation of what the flag does, which will be displayed in the Implementer Tools"
          }
        }
      },
      "required": [
        "flagName",
        "label",
        "description"
      ]
    },
    "modals": {
      "type": "array",
      "description": "An array of all modals provided by this frontend module. Modals are launched by name using the `showModal` function.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of this modal. This is used to launch the modal."
          },
          "component": {
            "type": "string",
            "description": "The name of the component exported by this frontend module."
          }
        },
        "required": [
          "component",
          "name"
        ]
      }
    },
    "workspaces": {
      "type": "array",
      "description": "An array of all workspaces provided by this frontend module. Modals are launched by name using the `showModal` function.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of this worspace. This is used to launch the workspace."
          },
          "title": {
            "type": "string",
            "description": "The title of the workspace. This will be looked up as a key in the translations of the module defining the workspace."
          },
          "component": {
            "type": "string",
            "description": "The name of the component exported by this frontend module."
          },
          "type": {
            "type": "string",
            "description": "The type of the workspace. Only one of each \"type\" of workspace is allowed to be open at a time. The default is \"form\". If the right sidebar is in use, then the type determines which right sidebar icon corresponds to the workspace."
          },
          "canHide": {
            "type": "boolean",
            "description": "Controls whether the workspace, once opened, can be hidden into the side rail."
          },
          "canMaximize": {
            "type": "boolean",
            "description": "Controls whether the workspace can be displayed in full-screen mode on a desktop."
          },
          "width": {
            "type": "string",
            "enum": ["narrow", "wider", "extra-wide"],
            "description": "Controls the width of the workspace. The default is \"narrow\" and this should only be changed to \"wider\" if the workspace itself has internal navigation, like the form editor. The width \"extra-wide\" is for workspaces that contain their own sidebar."
          },
          "preferredWindowSize": {
            "type": "string",
            "enum": ["maximized", "hidden", "normal"],
            "description": "Controls the default \"mode\" that the workspace opens in, either \"maximized\", \"hidden\", or \"normal\"."
          },
          "hasOwnSidebar": {
            "type": "boolean",
            "description": "Controls whether the workspace has its own sidebar. If true, the sidebar will be displayed when the workspace is open."
          },
          "sidebarFamily": {
            "type": "string",
            "description": "Sidebars have icons that representing workspaces. The sidebar family is the name of the sidebar that should contain the icon for this workspace. This is generally only needed if `hasOwnSidebar` is true, in which case this is the name of that sidebar. If multiple workspaces have `hasOwnSidebar` set to true and the same family name, then the sidebar within the workspace area will have icons for each of those workspaces."
          }
        },
        "required": [
          "name",
          "title",
          "component",
          "type"
        ]
      }
    }
  },
  "additionalProperties": false,
  "additionalItems": false
}