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:
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.