The Configuration Verifier Delta Format

The Configuration Verifier, CV in short, reports detected differences between the project configuration model and an existing Repository as delta definitions in YAML format.

Delta types

The CV can detect and report the following delta types:

• add-prop: a new property (defined only in the configuration model)
• upd-prop: an updated property
• del-prop: a deleted property (exists only in the Repository)
• add-node: a new node (defined only in the configuration model)
• del-node: a deleted node (exists only in the Repository)
• ord-node: a node with a different set of, and/or different ordered, child nodes

General structure of a delta definition

The general structure of a delta definition is as follows (depending on the delta type, some sections may not be applicable):

definitions:
  config:
    delta type:/path:
      repository:
        repository definition
      configuration:
        configuration model definition
        definitions:
        - config:
            module: hcm group name/hcm project name/hcm module name
            source: config yaml source file path
            definition:
              config definition
        - config:
          ...
      end-delta type: |2+

    delta type:/path:
    ...

An example delta upd-prop definition might be:

    upd-prop:/hippo:configuration/hippo:frontend/settings/locales:
      repository:
        /hippo:configuration/hippo:frontend/settings:
          locales: [en]
      configuration:
        /hippo:configuration/hippo:frontend/settings:
          locales: [en, nl]
        definitions:
        - config:
            module: hippo-cms/hippo-cms/hippo-cms-config
            source: cms-settings.yaml
            definition:
              /hippo:configuration/hippo:frontend/settings:
                locales: [en]
        - config:
            module: hippo-cms/hippo-cms-translations/hippo-cms-l10n-nl
            source: add-locale.yaml
            definition:
              /hippo:configuration/hippo:frontend/settings:
                locales:
                  operation: add
                  type: string
                  value: [nl]
      end-upd-prop: |2+

The above example shows that in the Repository the multi-value string property at delta path /hippo:configuration/hippo:frontend/settings/locales has one value [en] while the project configuration model defines two values: [en, nl], probably because the project added the Dutch (nl) localization module for the CMS UI.

As this example incorporates almost all sections of a delta definition we'll use it to explain the general structure.

delta definition path

upd-prop:/hippo:configuration/hippo:frontend/settings/locales

The path of a delta definition is prefixed with its delta type (upd-prop: in this case) followed by the path of the node or property of the detected change.

A delta definition starts with its unique delta path and is concluded with a terminating end-delta type property with only a newline as value. 

The latter is added purely to make it easier to distinguish and separate multiple delta definitions within one source file. The YAML serializer used (SnakeYaml) furthermore doesn't support emitting blank lines, and therefore the end-delta type: |2+ terminating property is used as a trick to serialize a property having only a newline value (producing the somewhat odd |2+ output, besides the following blank line).

delta repository section

Depending on the delta type, the delta repository section reports either:

• for upd-prop, del-prop, del-node: the definition of the property or node in the Repository, which can be used (added or merged with project configuration) to prevent updating or removing the property or node    
• for add-prop and add-node: the definition which can be used (added to the project configuration) to prevent the addition of the property or node (using property operation: delete or node :meta.delete: true respectively)
• for ord-node: a syntetic (fake) multi-value :meta.ordered-children string property listing the node its children (node) names in the Repository

delta configuration section

Depending on the delta type, the delta configuration section reports either:

• for add-prop, upd-prop, add-node: the effective (resulting) definition of the property or node in the project configuration model, based on one or more config definitions (see following section)
• for del-prop, del-node: nothing (not applicable)
• for ord-node: a syntetic (fake) multi-value :meta.ordered-children string property listing the node its effective children (node) names in the project configuration model 

delta configuration definitions subsection

The definitions subsection of a delta configuration section lists all the project config definitions (or fragments thereof) which contributed to the effective configuration model definition of the delta definition property or node.

These config definitions (in many/most cases there will be only one) are listed in the order they were merged in the configuration model.

For each config definition the following properties are reported:

• module: the module which provided the config definition, uniquely identified by the concatenation of the module group name, module project name and the module name itself separated by a /
• source: the config YAML source file path, relative to the module hcm-config folder
• definition:  the actual config definition (but only the relevant fragment thereof) contributing to the configuration definition of the delta property or node

The config definition path reported is always the root path of the original config definition, and thereby uniquely references (matches) the definition within the config YAML source file.
This might be a parent of the actual delta definition path, in which case only the intermediate child paths will be shown in the config definition up to the child node or property matching the delta definition path.

Exported value resources

The CV, just as with regular config (or content) definitions, exports binary property values to separate resource files, as well as property values which are explicitly defined using a resource file in the configuration model.

Because the delta definition YAML sources can contain references to such resource files for both Repository property values as well as configuration property values from multiple modules, these resource files need to be exported in separate folders to prevent resource path clashes.

The resource files for Repository property values are all exported under the subfolder repository, and use a uniquely generated resource file path as they don't have a predefined resource file path.

The resource files for configuration model properties, and for their originating config definitions are stored in a three level module folder (by module group name, module project name, and module name) under the subfolder configuration.

The property value resource path in the delta repository section and the delta configuration section will use the complete (relative) resource file path, but the originating config definitions will show the resource path from their original definition.
That means that for looking up the exported resource file for a delta configuration definitions config the actual resource file path needs to be derived from its module (full) name combined with the module relative resource path.

As an example, the following delta definition: 

    upd-prop:/hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions/documentworkflow/hipposcxml:source:
      repository:
        /hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions/documentworkflow:
          hipposcxml:source:
            type: string
            resource: repository/configuration/modules/scxmlregistry/moduleconfig/definitions/documentworkflow/source.scxml
      configuration:
        /hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions/documentworkflow:
          hipposcxml:source:
            type: string
            resource: configuration/hippo-cms/hippo-repository/hippo-repository-workflow/documentworkflow.scxml
        definitions:
        - config:
            module: hippo-cms/hippo-repository/hippo-repository-workflow
            source: scxml-definitions.yaml
            definition:
              /hippo:configuration/hippo:modules/scxmlregistry/hippo:moduleconfig/hipposcxml:definitions:
                /documentworkflow:
                  hipposcxml:source:
                    type: string
                    resource: /documentworkflow.scxml
      end-upd-prop: |2+

produces the following files within the CV output folder (assuming using the default path-prefix-source-mapping):

config-delta-modules.yaml
configuration/hippo-cms/hippo-repository/hippo-repository-workflow/source.scxml
configuration/hippo-cms/hippo-repository/hippo-repository-workflow/documentworkflow.scxml