Skip to main content

Schema

Unlike a generalized schema system focused on ontology, the ConfigurationSchema is specialized to the task of enabling user-friendly application configuration. To wit;

  • All configured data should be assumed to typically start out as a string.
  • All customizable fields should have a reasonable mapping from both command line options and environment variables.
  • The schema should support hierarchy, but be biased towards encapsulating subsystem configuration rather than encouraging arbitrarily nested structures.
  • The schema fields and child hierarchy implicitly define a corresponding configuration model.
  • To reduce cognitive load, the validated configuration model should look almost identical to the configuration file format, and you should be able to round-trip a config file generated from a serialized version of the configuration model.
  • Types should resolve values lazily in order to avoid instantiation if a lower-precedence field assignment is overridden.
  • Type value resolution and field validation may be asynchronous in order to offload common configuration needs away from application logic (e.g. check existence of a directory)

Schema Concepts​

Schemas contain fields and named child schemas, and hold references to dictionaries of types and validators.

Once defined, the schema can be used for two purposes:

  • process maps of field path assignments (dotted hierarchical field names with values) produced by configuration sources.
  • validate a candidate configuration object

Each concept is described separately.

For the following sections, we'll assume we've done this:

import { ConfigurationSchema } from '@versionzero/configurator';

const schema = new ConfigurationSchema();