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

**File:** `atmos.yaml`

```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](#atmos-cli-configuration-schema-atmosyaml).

## 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](pathname:///schemas/atmos/atmos-manifest/1.0/atmos-manifest.json) 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.

```yaml title="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](https://www.jetbrains.com/), [Microsoft Visual Studio](https://visualstudio.microsoft.com/), or [Visual Studio Code](https://code.visualstudio.com/), 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](https://json-schema.org/) can be found [here](https://json-schema.org/implementations#editors).
:::

### Command-Line Validation

Atmos can validate stack manifests on the command line using [`atmos validate stacks`](/cli/commands/validate/stacks):

```shell
atmos validate stacks
```

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

```shell
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:

```shell
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](pathname:///schemas/atmos/atmos-config/1.0/atmos-config.json) 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`](/cli/commands/config/config-schema).

### Validation by Default

Out of the box, [`atmos validate schema`](/cli/commands/validate/schema) validates `atmos.yaml` — plus `atmos.d` fragments and project-local [profile](/cli/configuration/profiles) files — against the built-in schema, with no configuration required:

```shell
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:

```yaml title="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:

```yaml title="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

- [JSON Schema](https://json-schema.org)
- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/release-notes)
- [Schema Store](https://www.schemastore.org/json)
- [JetBrains JSON Support](https://www.jetbrains.com/help/idea/json.html#ws_json_using_schemas)
- [VS Code JSON Support](https://code.visualstudio.com/docs/languages/json)

## Related Commands

## See Also

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Component Validation](/validation/validating) — Validating components with OPA and JSON Schema
- [Configure Validation](/quick-start/advanced/configure-validation) — Quick start guide for validation