JSON Schema for Atmos stack manifests: IDE auto-completion, manifest validation, schema updates for new features, SchemaStore integration
Atmos uses JSON Schema (Draft 2020-12) to validate stack manifests, provide IDE auto-completion, and catch configuration errors early. The schema system has three layers:
Website manifest schema -- Published at website/static/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json,
served 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. This is the public-facing schema for IDE integration.
Embedded schemas -- Located under pkg/datafetcher/schema/, compiled into the Atmos binary via Go embed.
These are the schemas Atmos uses at runtime for validation. There are multiple embedded schemas:
pkg/datafetcher/schema/atmos/manifest/1.0.json -- Minimal manifest schema (fallback).pkg/datafetcher/schema/stacks/stack-config/1.0.json -- Stack configuration validation schema. This is
the primary schema used by .atmos validate stackspkg/datafetcher/schema/config/global/1.0.json -- Global Atmos configuration schema.pkg/datafetcher/schema/vendor/package/1.0.json -- Vendor package manifest schema.User-provided schema -- Users can override the embedded schema by specifying a path or URL in atmos.yaml
under schemas.atmos.manifest, or via --schemas-atmos-manifest flag or ATMOS_SCHEMAS_ATMOS_MANIFEST env var.
Path: website/static/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
This is deployed to https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json and is the
canonical public schema. It uses the SchemaStore $id:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://json.schemastore.org/atmos-manifest.json",
"title": "JSON Schema for Atmos Stack Manifest files. Version 1.0. https://atmos.tools"
}
Path: pkg/datafetcher/schema/
The pkg/datafetcher/atmos_fetcher.go uses //go:embed schema/* to embed all schema files into the binary.
The atmosFetcher.FetchData() method resolves atmos:// URIs to embedded schema files by stripping the prefix
and appending .json.
Directory structure:
pkg/datafetcher/schema/
atmos/manifest/1.0.json -- Minimal manifest schema
stacks/stack-config/1.0.json -- Full stack config validation schema
config/global/1.0.json -- Global atmos.yaml config schema
vendor/package/1.0.json -- Vendor manifest schema
Path: pkg/datafetcher/schema/vendor/package/1.0.json
Validates vendor.yaml files with apiVersion, kind, metadata, and spec sections:
{
"fileMatch": ["vendor.{yml,yaml}", "vendor.d/**/*.{yml,yaml}"],
"properties": {
"apiVersion": { "enum": ["atmos/v1"] },
"kind": { "enum": ["AtmosVendorConfig"] },
"metadata": { "required": ["name", "description"] },
"spec": { "required": ["sources"] }
},
"required": ["apiVersion", "kind", "metadata", "spec"]
}