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

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

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

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