Store

Info

This is the documentation of the old store that will be removed in v4.0. For the new store that was introduced in v3.5 see Store (new). For migration instructions see Upgrades.

The store contains configuration objects.

Configuration

Option	Type	Default	Description
mode	enum	READ_WRITE	READ_WRITE or READ_ONLY. Dictates if the application may apply changes to the store.
additionalLocations	array	[]	Deprecated List of paths with additional directories.

Store structure

Each configuration object has a type, an optional sub-type, and an id unique to the type (see configuration-object-types). The path to the corresponding configuration file then looks like this:

store/entities/{type}/{id}.yml

Defaults for all configuration objects of a type or sub-type can optionally be set in such files:

store/defaults/{type}.yml
store/defaults/{type}.{sub-type}.yml

You can also create overrides for configuration objects. These have e.g. the purpose to make environment specific adjustments without having to change the main configuration files. The path to the overrides looks like this:

store/overrides/{type}/{id}.yml

Defaults, configuration objects and overrides are read and merged in this order. This means that information in the configuration object overwrites information in defaults and information in overrides overwrites both information in defaults and in the configuration object.

The merging functions also for nested structures, i.e. one does not have to repeat data in the different files, but can set e.g. in Overrides only purposefully the data, which one wants to overwrite.

The merged configuration objects must contain then all obligation data, otherwise it comes with the start to an error.

Additional directories

For fixed predefined or standardized configuration objects it may make sense to make environment specific adjustments in a separate directory. One or more such directories can be configured with additionalLocations. The paths to be specified can be either absolute or relative to the data directory, e.g.:

store:
  additionalLocations:
    - env/test

Such a directory can then again contain defaults and overrides, e.g.:

env/test/defaults/{type}.yml
env/test/overrides/{type}/{id}.yml

The merge order for all listed paths would then look like this:

store/defaults/{type}.yml
store/defaults/{type}.{sub-type}.yml
env/test/defaults/{type}.yml
store/entities/{type}/{id}.yml
store/overrides/{type}/{id}.yml
env/test/overrides/{type}/{id}.yml

Splitting of defaults and overrides

Defaults and overrides can be split into smaller files, e.g. to increase the clarity. The splitting follows the object structure in the configuration objects.

key1:
  key2:
    key3: value1

To set a default or override for this value, the files described above could be used:

store/defaults/{type}.{sub-type}.yml
store/overrides/{type}/{id}.yml

However, separate files can be created for the object key1 or the object key2, for example:

store/defaults/{type}/{sub-type}/key1.yml

key2:
  key3: value2

store/overrides/{type}/{id}/key1/key2.yml

key3: value3

So the path of the object can be moved from the YAML to the file system, so to speak.

The order of merging follows the specificity of the path. For all paths listed, it would look like this:

store/defaults/{typ}.{sub-typ}.yml
store/defaults/{typ}/{sub-typ}/key1.yml
store/entities/{typ}/{id}.yml
store/overrides/{typ}/{id}.yml
store/overrides/{typ}/{id}/key1/key2.yml

There are some special cases where splitting is not only allowed based on object paths, but also e.g. for uniquely referenceable array elements. These special cases are discussed in the description of configuration-object-types in the "special-cases" section.