> ## Documentation Index
> Fetch the complete documentation index at: https://docs.configu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configu Configuration-as-Code Format

> The `Cfgu` format defines the characteristics of a software configuration in Configu, providing metadata and constraints for `ConfigValues`. When attached to a `ConfigKey` in a `ConfigSchema`, it enables validation of `ConfigValues`, facilitating their implementation in the code.

## Location

`.cfgu` files essentially set the boundaries of different domains in the code relative to the configuration they use. Developers are free to organize and structure their `.cfgu` files in a way that makes sense for their specific needs and workflow. There is no limit on the number of `.cfgu` files that can be created, and they can be spread across different codebases, subfolders in the same project, and different repositories.

## Format

The `.cfgu` file can be written in one of the following formats: `YAML` or `JSON`. The name suffix of this file should be `.cfgu.yaml|yml|json` according to the format used.

## \$schema

Include the `$schema` property at the beginning of the file to specify the `Cfgu` version to communicate to other readers and tooling which specification version is intended.
Also, most modern editors will use this property to provide IntelliSense and validation for the `Cfgu` file.

```yaml example.cfgu.yaml theme={null}
$schema: https://files.configu.com/schema/.cfgu.json
```

```json example.cfgu.json theme={null}
{
  "$schema": "https://files.configu.com/schema/.cfgu.json"
}
```

```yaml vscode-yaml theme={null}
# yaml-language-server: $schema=https://files.configu.com/schema/.cfgu.json
```

## Properties

**description** `String|Markdown`

Describe a `ConfigKey`'s purpose within the application.

**test** `ConfigExpression|ConfigExpression[]`

Use this property to validate a `ConfigValue`. This property receives a string or an array of strings representing an
expression that evaluates to a boolean. If an array is provided, all expressions must evaluate to `true` for the value
to be considered valid.

&#x20;

> [accordion] ConfigExpression context
>
> **\$.value** `string|number|boolean|object|array`
>
> The `ConfigValue` to be validated.
>
> **\$.storedValue** `String`
>
> The `ConfigValue` to be validated as a raw string as it is stored in the `ConfigStore`.
>
> **\$.cfgu** `Cfgu`
>
> The `Cfgu` of the evaluated config.
>
> **\$.key** `String`
>
> The `ConfigKey` of the evaluated config.
>
> **\$.origin** `String`
>
> The origin of the `ConfigValue`. One of `empty`, `default`, `store`, `override`, or `const`.
>
> **\$.labels** `String[]`
>
> An array containing all of the labels of the config. If the config has no labels, then the array will be empty. Acts
> as syntax sugar for `$.cfgu.label` for expression consistency.
>
> **context.store** `ConfigStore`
>
> The `ConfigStore` provided as input to the command.
>
> **context.set** `ConfigSet`
>
> The `ConfigSet` provided as input to the command.
>
> **context.schema** `ConfigSchema`
>
> The `ConfigSchema` provided as input to the command.
>
> **configs.\{\{key}}.cfgu** `Cfgu`
>
> Use this to access the `Cfgu` properties of another ConfigKey.
>
> **configs.\{\{key}}.value** `string|number|boolean|object|array`
>
> Use this to access the `value` of another ConfigKey.
>
> **configs.\{\{key}}.storedValue** `string`
>
> Use this to access the `storedValue` of another ConfigKey.

> [accordion] ConfigExpression examples
>
> ```yaml example.cfgu.yaml theme={null}
> $schema: https://files.configu.com/schema/.cfgu.json
> keys:
>   NODE_ENV:
>     description: Defines the environment in which the application runs
>     test: expect($.value).to.be.a('string')
>     enum:
>       - development
>       - production
>       - test
>     default: production
>   ENABLE_FEATURE:
>     description: Enables a feature flag. Needs be enabled in production
>     test:
>       - validator.isBoolean($.storedValue)
>       - '$.configs.NODE_ENV.value === "production" ? expect($.value).to.be.true : true'
>     default: false
>   ENABLE_DEBUG_MODE:
>     description: Enables a debug mode. Must not be enabled in production
>     test:
>       - validator.isBoolean($.storedValue)
>       - '$.configs.NODE_ENV.value === "production" ? expect($.value).to.be.false : true'
>     default: false
> ```
>
> ```json example.cfgu.json theme={null}
> {
>   "$schema": "https://files.configu.com/schema/.cfgu.json",
>   "keys": {
>     "NODE_ENV": {
>       "description": "Defines the environment in which the application runs",
>       "test": "expect($.value).to.be.a('string')",
>       "enum": ["development", "production", "test"],
>       "default": "production"
>     },
>     "ENABLE_FEATURE": {
>       "description": "Enables a feature flag. Needs to be enabled in production",
>       "test": [
>         "validator.isBoolean($.storedValue)",
>         "$.configs.NODE_ENV.value === \"production\" ? expect($.value).to.be.true : true"
>       ],
>       "default": false
>     },
>     "ENABLE_DEBUG_MODE": {
>       "description": "Enables a debug mode. Must not be enabled in production",
>       "test": [
>         "validator.isBoolean($.storedValue)",
>         "$.configs.NODE_ENV.value === \"production\" ? expect($.value).to.be.false : true"
>       ],
>       "default": false
>     }
>   }
> }
> ```

**const** `ConfigExpression`

Define a constant value for a `ConfigKey` through a `ConfigExpression`, these `ConfigKeys` are never queried through a
`ConfigStore`. This property cannot be set together with `lazy`, `default`, or `required`.

> [accordion] ConfigExpression context
>
> **\$.cfgu** `Cfgu`
>
> The `Cfgu` of the evaluated
> config.
>
> **\$.key** `String`
>
> The `ConfigKey` of the evaluated config.
>
> **\$.labels** `String[]`
>
> An array containing all of the labels of the config. If the config has no labels, then the array will be empty. Acts as syntax sugar for `$.cfgu.label` for expression consistency.
>
> **context.store** `ConfigStore`
>
> The `ConfigStore` provided as input to the
> command.
>
> **context.set** `ConfigSet`
>
> The `ConfigSet` provided as input to the command.
>
> **context.schema** `ConfigSchema`
>
> The `ConfigSchema`
> provided as input to the command.
>
> **configs.\{\{key}}.cfgu** `Cfgu`
>
> Use this to access the `Cfgu` properties of another ConfigKey.
>
> **configs.\{\{key}}.value** `string|number|boolean|object|array`
>
> Use this to access the `value` of another ConfigKey.
>
> **configs.\{\{key}}.storedValue** `string`
>
> Use this to access the `storedValue` of another ConfigKey.

**pattern** `String`

Define a regular expression a `ConfigValue` must match. This property must be provided if the `type` is `RegEx`.

**schema** `JSON Schema`

Specify a JSON schema a `ConfigValue` must conform to. This property must be provided if the `type` is `JSONSchema`.

**enum** `String[]`

Specify a list of allowable `ConfigValues` for a `ConfigKey`. This property cannot be an empty array or contain empty
strings. Each option must be unique.

**default** `String`

Set a default `ConfigValue` for a `ConfigKey` if not explicitly provided. \\

This property cannot be set together with `required`, `const` or `lazy` properties. \\

If `enum` is set, the default value must be one of the options.

**required** `Boolean`

Indicate whether a `ConfigKey` is essential for the application's functionality. When set to `true`, a `ConfigValue`
must be found on `EvalCommand`. This property cannot be set together with `default` or `const`.

**lazy** `Boolean`

Indicate that a `ConfigValue` is set only during `EvalCommand` execution, excluding it from `UpsertCommand`
assignments. This property cannot be set together with `const` or `default`.

**hidden** `Boolean`

Indicate that this `ConfigKey` will be omitted from `ExportCommand` results.

**label** `String|String[]`

List labels to categorize `ConfigKeys` for easier filtering on `ExportCommand`.

## Example

```yaml example.cfgu.yaml theme={null}
$schema: https://files.configu.com/schema/.cfgu.json
keys:
  NODE_ENV:
    description: Defines the environment in which the application runs
    test: validator.isString($.value)
    enum:
      - development
      - production
      - test
    default: development
  LOG_LEVEL:
    description: Defines the level of logs to be recorded
    test: validator.isString($.value)
    enum:
      - error
      - warn
      - info
      - verbose
      - debug
      - silly
    default: info
  SERVICE_ENDPOINT:
    description: Defines the endpoint for the service
    test: validator.isURL($.value)
    required: true
  AWS_REGION:
    description: Defines the AWS region for the service
    enum:
      - af-south-1
      - ap-east-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-south-1
      - ap-southeast-1
      - ap-southeast-2
      - ca-central-1
      - cn-north-1
      - cn-northwest-1
      - eu-central-1
      - eu-north-1
      - eu-south-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - me-south-1
      - sa-east-1
      - us-east-1
      - us-east-2
      - us-gov-east-1
      - us-gov-west-1
      - us-west-1
      - us-west-2
    default: us-east-1
```

```json example.cfgu.json theme={null}
{
  "$schema": "https://files.configu.com/schema/.cfgu.json",
  "keys": {
    "NODE_ENV": {
      "description": "Defines the environment in which the application runs",
      "test": "validator.isString($.value)",
      "enum": ["development", "production", "test"],
      "default": "development"
    },
    "LOG_LEVEL": {
      "description": "Defines the level of logs to be recorded",
      "test": "validator.isString($.value)",
      "enum": ["error", "warn", "info", "verbose", "debug", "silly"],
      "default": "info"
    },
    "SERVICE_ENDPOINT": {
      "description": "Defines the endpoint for the service",
      "test": "validator.isURL($.value)",
      "required": true
    },
    "AWS_REGION": {
      "description": "Defines the AWS region for the service",
      "enum": [
        "af-south-1",
        "ap-east-1",
        "ap-northeast-1",
        "ap-northeast-2",
        "ap-northeast-3",
        "ap-south-1",
        "ap-southeast-1",
        "ap-southeast-2",
        "ca-central-1",
        "cn-north-1",
        "cn-northwest-1",
        "eu-central-1",
        "eu-north-1",
        "eu-south-1",
        "eu-west-1",
        "eu-west-2",
        "eu-west-3",
        "me-south-1",
        "sa-east-1",
        "us-east-1",
        "us-east-2",
        "us-gov-east-1",
        "us-gov-west-1",
        "us-west-1",
        "us-west-2"
      ],
      "default": "us-east-1"
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.