Atmos Schemas

Atmos JSON Schema System

Overview

Atmos uses JSON Schema (Draft 2020-12) to validate configuration files, provide IDE auto-completion, and catch configuration errors early. Two schemas cover the core file types:

1. Stack manifest schema -- Validates stack YAML manifests (stacks/**). Published at https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json and registered with SchemaStore as https://json.schemastore.org/atmos-manifest.json. Used by atmos validate stacks and by IDEs for auto-completion.

2. CLI configuration schema -- Validates atmos.yaml itself (every configuration section the CLI reads). Published at https://atmos.tools/schemas/atmos/atmos-config/1.0/atmos-config.json. Used by atmos validate schema config and by IDEs for auto-completion. This schema is generated from the Atmos configuration code, so it always matches the options the installed release actually supports -- including YAML function alternatives (like logs: !include shared.yaml) and descriptions for hover text.

Users can also validate arbitrary YAML files against arbitrary schemas via schemas.<key> entries in atmos.yaml (see "Custom Schema Validation" below), and vendor.yaml manifests are validated against a built-in vendor schema.

Floating vs. Pinned Schema URLs

Both schemas are published in two forms:

• Floating -- .../atmos-manifest/1.0/atmos-manifest.json and .../atmos-config/1.0/atmos-config.json always reflect the latest Atmos release.
• Pinned -- .../atmos-manifest/<atmos-version>/atmos-manifest.json and .../atmos-config/<atmos-version>/atmos-config.json are immutable snapshots of the schema exactly as it shipped with that release. Pin when a team upgrades the Atmos binary on its own schedule and must not silently absorb schema changes. Pinned URLs only exist for versions released after pinning shipped; earlier releases only have the floating 1.0 path.

Validating atmos.yaml (CLI Configuration)

Out of the box -- no configuration required -- atmos validate schema validates atmos.yaml (including hidden .atmos.yaml variants), atmos.d/** fragments, and project-local profile files against the built-in configuration schema:

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.

Print the schema itself (for inspection, or to commit a copy into a repository):

atmos config schema                       # print to stdout
atmos config schema schemas/atmos-config.json   # write to a file

Overriding the Built-In Entry

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

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"

Editor Integration for atmos.yaml

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

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

Validating Stack Manifests

atmos validate stacks

Validates all stack manifests against the Atmos manifest JSON Schema:

# Use default embedded schema
atmos validate stacks

# Use local schema file
atmos validate stacks --schemas-atmos-manifest schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

# Use remote schema
atmos validate stacks --schemas-atmos-manifest https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

This command checks:

• YAML syntax errors in all manifest files (template files .yaml.tmpl, .yml.tmpl are excluded)
• Import validity -- correct references, no self-imports, valid data types
• Schema validation of all manifest sections against the JSON Schema
• Component duplication -- same component in same stack defined in multiple files with different configs

Schema Configuration in atmos.yaml

schemas:
  # JSON Schema for validating component configurations
  jsonschema:
    base_path: "stacks/schemas/jsonschema"

  # OPA policies for component validation
  opa:
    base_path: "stacks/schemas/opa"

  # JSON Schema for validating Atmos stack manifests themselves
  atmos:
    manifest: "stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"
    # Also supports URLs:
    # manifest: "https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json"

Configuration precedence for the manifest schema:

1. --schemas-atmos-manifest CLI flag
2. ATMOS_SCHEMAS_ATMOS_MANIFEST environment variable
3. schemas.atmos.manifest in atmos.yaml
4. Default embedded schema (matches the installed Atmos version)