Schema development best practices

Some suggestions how to organize schemas, manage them in VCS and deploy them.

There are several possible ways how the development of schemas can be organized, but this document describes the recommended one.

File organization

Each schema is stored in its own file, with filename based on the schema name.
All schemas (for single project) are in one single directory (folder).
Optional: files are sorted by dependencies and numbered (with fixed number width) to ensure that the order is maintained.
- Using numbering with steps of 10 or 100 ensures that there is always a place to insert new one.
Each file has the following name format:
- <NNN>-<schemaname>-schema.json or <schemaname>-schema.json

Example:

TEXT

  001-media-schema.json
  010-rubric-schema.json
  020-targetgroup-schema.json
  030-person-schema.json
  032-person_group-schema.json
  040-image-schema.json
  050-video-schema.json
  060-collection-schema.json
  070-document-schema.json

Files are stored in VCS (Version Control System), usually git.
- Standard development practices can be followed (feature branches, merge requests with reviews).

This organization is recognized by both the deployment script (see lower), but also by the HCMS itself when it loads files from filesystem (optional feature) and in the "$ref" format (which strips any -schema.json and number prefix from references to get schema name).

Deployment script

To deploy schemas from local filesystem, convenience script is available:

set-schema-mass.sh

Prerequisites:

bash version 3.x or higher (part of every UNIX-like OS)
curl version 7.x or higher (either via standard distribution package, Homebrew or from the official website)

Loading from local filesystem

HCMS can also load schemas form local directory, with the same directory/file structure as described above. This is done on start and these schemas are considered "internal" or "default"; each of them can be overridden by a schema deployed via REST API. Schemas are loaded from several directories, configurable via environment variables:

HCMS_DEFAULT_SCHEMA_DIR: single absolute path
- when running inside Docker, it even has a default value: /schemas (but only if that directory actually exists)
HCMS_DEFAULT_SCHEMA_PATH: multiple absolute paths, separated by colon : (just like UNIX/Linux PATH variable)
- no default, empty paths and non-directories are simply ignored
- no escaping is available, which means that it is not possible to set paths that include the : character

Normally, these schemas are loaded only on start and restart. There is one way to trigger reload while HCMS is running: special non-standard method RELOAD at endpoint /schema.

Loading from local filesystem only

Setting environment variable HCMS_DEFAULT_SCHEMA_ONLY to value true (for example in docker commandline: -e HCMS_DEFAULT_SCHEMA_ONLY=true) completely disables the schema repository stored in assets. In this mode, only the schemas loaded from the filesystem are available and cannot be overridden. All HTTP PUT request to /schema/{name} are automatically treated as "validation only" and do not actually change anything.