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.

schemas.config

Overrides the built-in entry that validates atmos.yaml (plus atmos.d and project-local profile fragments) against the schema generated from the Atmos configuration code. Set schema to a path or URL and matches to the file globs to validate. When omitted, the embedded schema and default matches are used — see Atmos CLI Configuration Schema.

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.

Floating vs. Pinned Schema URLs​

The published schema is available at two kinds of URLs:

  • Floating — https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json always reflects the schema shipped by the latest Atmos release. Use this (the default) when you want validation to automatically pick up new manifest fields as you upgrade Atmos.
  • Pinned — https://atmos.tools/schemas/atmos/atmos-manifest/<atmos-version>/atmos-manifest.json (e.g. .../atmos-manifest/1.219.0/atmos-manifest.json) is an immutable snapshot of the schema exactly as it shipped with that Atmos release. Use this when you want to upgrade the atmos binary without silently absorbing new schema fields — pin schemas.atmos.manifest to the version you've reviewed, and only bump it deliberately when you're ready to adopt newer manifest fields.
atmos.yaml
schemas:
  atmos:
    # Pin to a specific Atmos release's schema instead of tracking the latest.
    manifest: "https://atmos.tools/schemas/atmos/atmos-manifest/1.219.0/atmos-manifest.json"

A pinned URL only exists for versions released after this feature shipped; earlier releases only have the floating 1.0 path.

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

Atmos CLI Configuration Schema (atmos.yaml)​

The Atmos CLI Configuration JSON Schema validates atmos.yaml itself — every configuration section the CLI reads — and provides auto-completion in supported editors.

Unlike the stack-manifest schema, this schema is generated from the Atmos configuration code: whenever a new configuration option ships, the schema already models it, including YAML function alternatives (like logs: !include shared.yaml) and descriptions sourced from the code documentation. Print it locally with atmos config schema.

Validation by Default​

Out of the box, atmos validate schema validates atmos.yaml — plus atmos.d fragments and project-local profile files — against the built-in schema, with no configuration required:

atmos validate schema           # validates atmos.yaml, atmos.d/**, profiles/** (and everything in `schemas`)
atmos validate schema config    # validates only the atmos.yaml schema entry
atmos config validate           # alias for `atmos validate schema config`

Fragments and profiles are partial configurations; the schema requires no specific fields, so they validate standalone.

Overriding the Built-In Entry​

Define your own schemas.config entry to change the schema or the matched files:

atmos.yaml
schemas:
  config:
    # Pin to a specific Atmos release's schema instead of the embedded one.
    schema: "https://atmos.tools/schemas/atmos/atmos-config/1.219.0/atmos-config.json"
    matches:
      - "atmos.yaml"
      - "atmos.d/**/*.yaml"

Floating vs. Pinned URLs​

The same floating/pinned model as the manifest schema applies:

  • Floating — https://atmos.tools/schemas/atmos/atmos-config/1.0/atmos-config.json always reflects the schema shipped by the latest Atmos release.
  • Pinned — https://atmos.tools/schemas/atmos/atmos-config/<atmos-version>/atmos-config.json is an immutable snapshot of the schema exactly as it shipped with that Atmos release. Pinned URLs only exist for versions released after this feature shipped.

Editor Integration​

Add a yaml-language-server modeline to the top of atmos.yaml for auto-completion and inline validation:

atmos.yaml
# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-config/1.0/atmos-config.json
base_path: "./"

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​