# 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

Atmos bundles the manifest and CLI configuration schemas with the installed binary. Leave their overrides unset so validation stays aligned with your Atmos version. Configure your own component schemas and policies 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' on `atmos validate component`
    # 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' on `atmos validate component`
    # Supports both absolute and relative paths
    base_path: "stacks/schemas/opa"
```

## 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` on `atmos validate component`.
- **`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` on `atmos validate component`.
- **`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 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.

### Removing a local schema copy

Run `atmos doctor --only=local-atmos-schema` to find local overrides. Remove
`schemas.atmos.manifest` and unset `ATMOS_SCHEMAS_ATMOS_MANIFEST` to use the bundled
manifest schema. Remove a local `schemas.config` override to restore the default
CLI configuration validator. If you use custom file matches, retain them and set
`schemas.config.schema` to `atmos://schema/atmos/config/1.0`.

Doctor distinguishes an identical copy from one that differs. Differences may be
custom constraints or version differences; review them before switching. Once you
have updated remaining references, delete obsolete copies. Keep component JSON
Schemas, OPA/CUE policies, and intentional custom validators.

Editor associations are separate from CLI validation. Update editors to a published
HTTPS schema URL before deleting a referenced copy; the `atmos://` URI is for Atmos,
not for editors. Doctor does not delete files or change these associations.

### 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 for editor associations that should track the latest release. CLI validation defaults to the bundled schema for the installed version, which may differ from the latest release.
- **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