> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/configuration-reference/file-inclusion.md).

# 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).

{% hint style="warning" %}
Only files of type JSON are supported and file must contain a JSON object ("`{...}`") or array ("`[...]`").
{% endhint %}

## 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.

{% hint style="info" %}
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.
{% endhint %}

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.

{% hint style="info" %}
An empty array (`[]`) is always returned when the include expression produces no result.
{% endhint %}

## 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):

{% code title="/path/to/dir/file.json" %}

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

{% endcode %}

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.

```json
// 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`".

```json
// 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.

{% hint style="info" %}
`@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.
{% endhint %}

#### Example

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

{% code title="/path/to/dir/file.json" %}

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

{% endcode %}

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.

```json
// 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`".

```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.

```json
// 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`:

```json
// 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  | <p>"<code>@include:/path/to/</code><em><code>/file\_</code></em><code>.json</code>"<br>"<code>@include:/path/to/\*\*/file\_</code><em><code>.json</code>"</em><br><em>"<code>@include:/path/to/dir/file\_</code></em><code>.json,/path/to/other/file\_\*.json</code>"</p> | 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>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/configuration-reference/file-inclusion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.