General.IncludeConfig[]

Values from one or more secondary data sources can be added to the values read from a primary configuration data source.

The JSON contents of multiple configuration files are merged into a single overall configuration. This can be used, for example, to avoid redundant configurations and/or partial configurations when content that is repetitive occurs in multiple primary configuration files.

To avoid having to maintain the same content multiple times, this content can be stored in a shared "include" file. This include file is referenced from the primary files. No more include files can be integrated into an include file.

.IncludeConfig[] is where to specify the secondary configuration files in URI syntax (see Data Format and Data Sources). The specification can be an absolute path or a relative path, relating to the path of the primary file. Each file can contain an incomplete partial configuration, because only the totality of all partial configurations composes a consistent state.

The assembly of the overall configuration from these parts is the first step before interpretation and content validation of the data. The prerequisite for this is that each part is available in valid JSON syntax. The following generic logic is used to connect JSON data:

Data is inserted from the secondary files into the primary file, in the order in which it is defined. Configuration properties that already exist in the primary file are overwritten with the values from the secondary file. However, data is overwritten only if the properties are elementary properties and the values of those properties in the secondary file are not empty. Values are considered empty if they are "null." An empty string "" does not represent an empty value in this context and thus overwrites a value in the primary file. Array elements are joined together to form a new array if the array of the same name exists in the primary and secondary files. The exception is elements with the same content, which are added just once instead of twice.

In terms of the work content handled, this handling of array elements is not always desirable. In some cases, for example, fields from a secondary file should be added to an existing field catalog in the primary file instead of adding a separate field catalog. For certain elements that are structured as an array, content-based post-processing of the configuration file therefore takes place. The order of the array elements resulting from the intermediate step is relevant for the final result. These elements contain arrays with sub-elements (e.g., field listings, which are to be combined into a common array). This combination is achieved by successively appending additional elements to the first array. The order of the elements is retained.

The global property General.DebugWriteMergedConfig can be used to output the final result of the program-internal file merge in file form for control purposes.