File inclusion

Introduction

Configuration supports inclusion of files to enable a modular structure.

An inclusion expression has the following format:

"@include:/path/to/includable/file/or/dir"

After inclusion the property value containing the inclusion will be replaced with the content of the include file(s).

Caution

Only files of type JSON are supported and file must contain a JSON object ("{...}") or array ("[...]").

Syntax

An inclusion expression MUST:

• be a string ("...")
• start with @include:, @include_as_object:, or @include_as_array:
• end with one or more comma separated paths or globs specifying the files or directories to include
• NOT contain expansions

Both files and directories can be included.

If include is a file:

1. Load content of file
2. Parse content as JSON
3. Replace property value with included JSON (object or array)

Including an empty or non-json file is an error. Including a file that doesn't exist results in an empty array.

If include is a directory:

1. Create a JSON array ("result")
2. For each file in directory matching pattern "*.json" or "*.jsonc"
   1. Load content of file
   2. Parse content as JSON
   3. Add JSON (object or array) to result array
3. Replace property value with result array

Including a non-existing directory or an empty directory (or a directory that doesn't contain any json-files) results in an empty result array.

Note

A directory inclusion always produces an array — regardless of how many files it contains. This is intentional: a directory is a collection, and the result reflects that even when the collection has only one element.

The same rule applies to glob patterns and comma-separated paths: both always produce an array, even when only one file matches or resolves.

Only an explicit single-file inclusion (@include:file.json) returns the file's content directly (object or array). Use @include_as_object to unwrap a single-element array result into an object.

If more than one path is supplied the above process will be repeated for each path. When including multiple paths the result is always an array.

Note

An empty array ([]) is always returned when the include expression produces no result.

Paths

Paths can be absolute or relative. Relative paths are resolved against the directory of the including file.

// Absolute path
"property": "@include:/absolute/path/to/included/file.json"

// Relative path, same directory
"property": "@include:file.json"
"property": "@include:./file.json"

// Relative path, sub directory
"property": "@include:includes/dir/file.json"
"property": "@include:./includes/dir/file.json"

// Relative path, sibling directory
"property": "@include:../other/dir/file.json"

// Multiple dirs
"property": "@include:path/to/dir/,path/to/other/"

Directory paths can be specified with or without trailing path separator ("/").

Globs

Glob patterns ("globs") are supported in paths.

The result of a glob is a list of zero, one or more matching paths. A glob expression always produces an array — even when only one path matches. Think of globs as a powerful way to specify multiple files.

Globs are simplified forms of regular expressions used to match file paths and names based on certain patterns. Here's a description of the most common glob-pattern syntax elements:

Asterisk (*):

Matches any number of any characters, including none. Example: *.txt matches all files with a .txt extension (notes.txt, report.txt).

Question Mark (?):

Matches exactly one character. Example: file?.txt matches file1.txt, file2.txt, but not file10.txt.

Brackets ([]):

Matches any one of the enclosed characters. Example: file[123].txt matches file1.txt, file2.txt, or file3.txt.

Hyphen (within brackets):

Specifies a range of characters. Example: file[a-c].txt matches filea.txt, fileb.txt, or filec.txt, but not filez.txt

Braces ({}):

Matches any of the comma-separated patterns. Example: file{1,2,3}.txt matches file1.txt, file2.txt, or file3.txt, but not file4.txt.

Double Asterisk (**):

Matches directories recursively. Example: **/*.txt matches all .txt files in the current directory and all subdirectories.

// Simple glob inluding all json-files in a dir
// This is the same as including 'path/to/include/'
"property": "@include:path/to/include/*.json"

// Include all json-files having a name starting with 'test'
"property": "@include:path/to/include/test*.json"

// Include all json-files located in a dir named 'test'
"property": "@include:**/test/*.json"

Type conversion

In some situations it may be useful to change the result type of an include expression to match what is expected by the consumer.

Type conversion is enabled by using an alias directive:

• @include_as_object
• @include_as_array

Type conversion is only possible when it doesn't result in data loss.

Convert from array to object ("unwrap")

When the result is an array containing only one element that is an object, the element can be unwrapped using directive: @include_as_object

If the result is anything but a single element array, the behaviour is identical to a regular inclusion.

Example

Given the following file containing an object (no other files in dir):

/path/to/dir/file.json

{
    "description": "This is the content",
    "path": "/path/to/dir/file.json"
}

The expression "@include:/path/to/dir" will result in an array containing the contents of all json-files in the specified directory even if the directory, like in this case, only contains a single file.

// A regular "@include":
{
    "result": "@include:/path/to/dir"
}

// results in an array with file content in first element (0) since we included
// a directory
{
    "result": [
        {
            "description": "This is the content",
            "path": "/path/to/dir/file.json"
        }
    ]
}

To unwrap the single element result from the array, use "@include_as_object:/path/to/dir".

// Include as object:
{
    "result": "@include_as_object:/path/to/dir"
}

// results in content being the value of result (not an array) since
// the result array contained only one element
{
    "result": {
        "description": "This is the content",
        "path": "/path/to/dir/file.json"
    }
}

Convert from object to array ("wrap")

When the result of an include is an object it can be wrapped in an array by using directive: @include_as_array

If the result is anything but an object, the behaviour is identical to a regular inclusion.

Note

@include_as_array acts on the total result, not on each individual file. When the expression matches multiple files the result is already an array — the directive has no effect and behaves identically to @include.

Use @include_as_array when you need to guarantee an array result regardless of whether the expression matches zero or one file.

Example

Given the following file (number of files in dir does not matter in this example):

/path/to/dir/file.json

{
    "description": "This is the content",
    "path": "/path/to/dir/file.json"
}

The expression "@include:/path/to/dir/file.json" will result in an object, since a single file is included and that file contains an object.

// A regular "@include":
{
    "result": "@include:/path/to/dir/file.json"
}

// results in value being the actual content of the file (an object or array)
{
    "result": {
        "description": "This is the content",
        "path": "/path/to/dir/file.json"
    }

}

To wrap this object in an array, use "@include_as_array:/path/to/dir/file.json".

// Include as array:
{
    "result": "@include_as_array:/path/to/dir/file.json"
}

// results in the object being being wrapped in an array
{
    "result": [
        {
            "description": "This is the content",
            "path": "/path/to/dir/file.json"
        }
    ]
}

Include as element in an array

An include directive can be placed as an element inside a JSON array. When the included content is itself an array, its elements are flattened into the parent array.

// file.json contains: ["b", "c"]

{
    "items": ["a", "@include:file.json", "d"]
}

// results in a flat array
{
    "items": ["a", "b", "c", "d"]
}

To nest the included array instead of flattening it, use @include_as_array:

// file.json contains: ["b", "c"]

{
    "items": ["a", "@include_as_array:file.json", "d"]
}

// results in a nested array
{
    "items": ["a", ["b", "c"], "d"]
}

Summary

Below are the basic includes. They may be combined to create advanced includes.

To include..	Use	Result
a single file	"@include:/path/to/file.json"	Content of file — object: {"key":"value"} or array: ["a","b"]
all (json) files in a directory	"@include:/path/to/dir"	Array — one element per file: [{"name":"file1"},{"name":"file2"}]
all (json) files from multiple directories	"@include:/path/to/dir,/path/to/other"	Array — files from all dirs flattened: [{"from":"dir1a"},{"from":"dir1b"},{"from":"dir2a"}]
a subset of files in a single directory	"@include:/path/to/dir/file_*.json"	Array — always: [{"key":"value"}] (1 match) or [{"key":"v1"},{"key":"v2"}] (multiple matches)
a subset of files in multiple directories	"@include:/path/to//file_.json" "@include:/path/to/**/file_.json" "@include:/path/to/dir/file_.json,/path/to/other/file_*.json"	Array: [{"key":"v1"},{"key":"v2"}]
as element in an array	["@include:/path/to/file.json","x"]	Array elements flattened into parent — given file contains ["a","b"]: ["a","b","x"]

Troubleshooting

Included file does not contain valid JSON:

Failed to read/parse: <message>