Skip to main content

Schemas

Configure the paths where Atmos finds OPA and JSON Schema files to validate stack manifests and components. Schemas enable you to enforce consistency and catch configuration errors early.

Configuration​

Schemas are configured in the schemas section:

atmos.yaml

# Validation schemas (for validating atmos stacks and components)
schemas:
  # https://json-schema.org
  jsonschema:
    # Can also be set using 'ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH' ENV var, or '--schemas-jsonschema-dir' command-line argument
    # Supports both absolute and relative paths
    base_path: "stacks/schemas/jsonschema"
  # https://www.openpolicyagent.org
  opa:
    # Can also be set using 'ATMOS_SCHEMAS_OPA_BASE_PATH' ENV var, or '--schemas-opa-dir' command-line argument
    # Supports both absolute and relative paths
    base_path: "stacks/schemas/opa"
  # JSON Schema to validate Atmos manifests
  atmos:
    # Can also be set using 'ATMOS_SCHEMAS_ATMOS_MANIFEST' ENV var, or '--schemas-atmos-manifest' command-line argument
    # Supports both absolute and relative paths (relative to the `base_path` setting in `atmos.yaml`)
    manifest: "stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"

Configuration Options​

schemas.jsonschema.base_path

Base path to JSON Schema files for component validation. Supports both absolute and relative paths. Can also be set using ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH environment variable or --schemas-jsonschema-dir command-line argument.

schemas.opa.base_path

Base path to OPA (Open Policy Agent) policy files for component validation. Supports both absolute and relative paths. Can also be set using ATMOS_SCHEMAS_OPA_BASE_PATH environment variable or --schemas-opa-dir command-line argument.

schemas.atmos.manifest

Path to the JSON Schema used to validate Atmos stack manifests. Supports both absolute and relative paths (relative to base_path). Can also be set using ATMOS_SCHEMAS_ATMOS_MANIFEST environment variable or --schemas-atmos-manifest command-line argument.

Directory Structure​

A typical schema directory structure:

stacks/schemas/
├── jsonschema/
│   ├── vpc.json
│   ├── eks-cluster.json
│   └── rds.json
├── opa/
│   ├── vpc.rego
│   ├── security.rego
│   └── compliance.rego
└── atmos/
    └── atmos-manifest/
        └── 1.0/
            └── atmos-manifest.json

Atmos Manifest JSON Schema​

The Atmos Manifest JSON Schema validates Atmos stack manifests and provides auto-completion in supported editors.

IDE Auto-Completion and Validation​

In supported editors like JetBrains IDEs, Microsoft Visual Studio, or Visual Studio Code, the schema can offer auto-completion and validation to ensure that Atmos stack manifests are correct.

tip

A list of editors that support validation using JSON Schema can be found here.

Command-Line Validation​

Atmos can validate stack manifests on the command line using atmos validate stacks:

atmos validate stacks

You can also specify the schema path via environment variable or command-line argument:

ATMOS_SCHEMAS_ATMOS_MANIFEST=stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json atmos validate stacks
atmos validate stacks --schemas-atmos-manifest stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

If not specified, Atmos defaults to the schema corresponding to the currently installed version.

Validation Output Example​

In case of validation errors, you'll see output similar to:

atmos validate stacks

Atmos manifest JSON Schema validation error in the
file 'catalog/invalid-yaml-and-schema/invalid-import-5.yaml':
{
  "valid": false,
  "errors": [
    {
      "keywordLocation": "/properties/import/$ref/type",
      "instanceLocation": "/import",
      "error": "expected array, but got object"
    }
  ]
}

invalid stack manifest 'catalog/invalid-yaml-and-schema/invalid-yaml-1.yaml'
yaml: line 15: found unknown directive name

Environment Variables​

ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH
Base path to JSON Schema files.
ATMOS_SCHEMAS_OPA_BASE_PATH
Base path to OPA policy files.
ATMOS_SCHEMAS_ATMOS_MANIFEST
Path to Atmos manifest JSON Schema.

References​

See Also​