Flux – Flux Schema

Flux: Flux Schema Config

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema validate and flux schema explain commands can load default flag values from a YAML configuration file. The file shape is versioned and documented by the JSON Schema in config-v1beta1.json.

Example

apiVersion: schema.plugin.fluxcd.io/v1beta1
kind: Config
validate:
 schemaLocation:
 - ecosystem
 skipKind:
 - source.toolkit.fluxcd.io/v1/ExternalArtifact
 skipJSONPath:
 - Secret:/sops
 skipFile:
 - '.*'
 - kustomization.yaml
 skipCELRules: false
 skipMissingSchemas: false
 verbose: true
 failFast: false
 concurrent: 8
 insecureSkipTLSVerify: false
 output: text
explain:
 schemaLocation:
 - ecosystem
 apiVersion: v1
 recursive: false
 insecureSkipTLSVerify: false
 output: plaintext

Usage:

flux schema validate ./manifests --config .fluxschema.yml
flux schema explain pods.spec --config .fluxschema.yml

When --config is not set, the FLUX_SCHEMA_CONFIG environment variable is used. When neither is set, validate uses the executable-adjacent config file when it exists. explain reads that same path when no --schema-location is passed, for example ~/.fluxcd/plugins/flux-schema.config.

Specification

Field	Description
`apiVersion`	Config API version. Currently `schema.plugin.fluxcd.io/v1beta1`.
`kind`	Config API kind. Currently `Config`.
`validate`	Defaults for validation options.
`explain`	Defaults for explain options.

Validation

The validate section configures defaults for the flux schema validate flags.

Field	Description
`schemaLocation[]`	Schema URLs, file paths, or templates tried in order. Aliases: `default` (built-in catalog), `ecosystem` ( schemas.fluxoperator.dev).
`skipMissingSchemas`	Skip documents for which no schema can be found.
`skipKind[]`	Kind or apiVersion/kind patterns excluded from validation.
`skipJSONPath[]`	JSON Pointers stripped before validation.
`skipFile[]`	Basename glob patterns excluded from validation.
`skipCELRules`	Disable evaluation of `x-kubernetes-validations` CEL rules.
`verbose`	Print a line for every document, including valid and skipped.
`failFast`	Exit after the first invalid document.
`concurrent`	Number of concurrent validation workers.
`insecureSkipTLSVerify`	Disable TLS certificate verification when downloading schemas.
`output`	Output format: `text`, `json`, or `yaml`.

When the output field is set to json or yaml, the result has the Report API shape.

Explain

The explain section configures defaults for the flux schema explain flags.

Field	Description
`schemaLocation[]`	Schema URLs, file paths, or templates tried in order. Aliases: `default` (built-in catalog), `ecosystem` ( schemas.fluxoperator.dev).
`apiVersion`	API group/version to explain by default.
`recursive`	Print fields of fields.
`insecureSkipTLSVerify`	Disable TLS certificate verification when downloading schemas.
`output`	Output format: `plaintext` or `plaintext-openapiv2`.

Flux: Kubernetes Manifests Validation with Flux Schema CLI

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema validate command validates Kubernetes YAML manifests from one or more files or directories against a JSON Schema resolved from each document’s apiVersion and kind.

Examples:

# Validate all YAML files in a directory tree
flux schema validate ./manifests --skip-missing-schemas

# Validate a Helm chart by piping the rendered output
helm template ./charts/app | flux schema validate --verbose

A non-zero exit code is returned when any document is invalid or errored.

Flags

Flag	Description
`-s, --schema-location`	URL or file path for schemas (repeatable, tried in order); `default` points at the built-in catalog, `ecosystem` at the CNCF ecosystem catalog.
`--skip-missing-schemas`	Skip documents for which no schema can be found.
`--skip-kind`	Skip documents matching `kind` or `apiVersion/kind` (repeatable).
`--skip-json-path`	Strip a JSON Pointer field before validation, optionally scoped: `[apiVersion/kind:]/path` (repeatable).
`--skip-file`	Glob pattern matched against files and dirs; defaults to skipping dotfiles and dot-dirs (repeatable).
`--skip-cel-rules`	Skip evaluation of `x-kubernetes-validations` CEL rules.
`--fail-fast`	Exit after the first invalid document.
`--concurrent`	Number of concurrent workers (default 8).
`--insecure-skip-tls-verify`	Disable TLS certificate verification when fetching schemas over HTTPS.
`-v, --verbose`	Print a line for every document, including valid and skipped ones.
`-o, --output`	Output format, one of `text`, `json` or `yaml` (default: `text`).
`--config`	Path to a YAML file supplying default values for validate flags (env: `FLUX_SCHEMA_CONFIG`).

Schema location

When no --schema-location is given, validate uses the Flux Schema catalog, which covers the latest Kubernetes and OpenShift APIs, the stable channel of Gateway API, and the Flux ecosystem CRDs:

flux schema validate ./manifests

To validate against your own schemas generated by flux schema extract, pass the directory as --schema-location. Bare paths and URLs are auto-expanded to the catalog layout {{.Group}}/{{.Kind}}_{{.Version}}.json:

flux schema validate ./manifests --schema-location ./my-schemas

For a different layout, pass a full Go template ending in .json:

flux schema validate ./manifests \
 --schema-location './schemas/{{.Kind}}-{{.GroupPrefix}}-{{.Version}}.json'

Template variables are .Group, .GroupPrefix, .Kind, and .Version.

The --schema-location flag is repeatable and locations are tried in order (the first match wins). Pass the literal value default to include the Flux Schema catalog alongside your own schemas:

flux schema validate ./manifests \
 --schema-location default \
 --schema-location ecosystem \
 --schema-location './schemas/{{.Kind}}-{{.GroupPrefix}}-{{.Version}}.json'

The literal value ecosystem resolves to the CNCF ecosystem catalog served from https://schemas.fluxoperator.dev/catalog/, covering CRDs of hundreds of CNCF projects and rebuilt daily from upstream releases.

See custom catalogs for guidance on building and hosting your own schema catalog.

Skipping documents and fields

Manifests can be piped in and certain documents skipped with --skip-kind:

kustomize build . | flux schema validate \
 --skip-kind 'Service' \ # matches any Service kind regardless of apiVersion
 --skip-kind 'source.toolkit.fluxcd.io/v1/ExternalArtifact'

Some manifests carry tooling-injected fields that are stripped at apply time by Flux (e.g. SOPS-encrypted Secrets). Use --skip-json-path to remove those fields from validation so the rest of the document is still checked:

flux schema validate ./manifests \
 --skip-json-path 'v1/Secret:/sops' \
 --skip-json-path 'Deployment:/sops'

Output

Default output (-o text) prints one line per document with its validation result, and a summary at the end. To print valid documents and skipped ones alongside invalid ones, pass --verbose:

$ flux schema validate ./manifests --verbose

manifests/releases.yaml - HelmRelease/apps/frontend is invalid: cel violation
 - /spec: Invalid value: either 'chart' or 'chartRef' must be set
manifests/sources.yaml - Bucket/apps/frontend-config is invalid: schema violation
 - /spec: missing property 'bucketName'
 - /spec/interval: got number, want string
 - /spec/secretRef/name: got object, want string
 - /spec: additional properties 'force' not allowed
manifests/sources.yaml - OCIRepository/apps/frontend is invalid: yaml parse error
 - line 10: key "app.kubernetes.io/name" already set in map
manifests/sources.yaml - HelmChart/apps/frontend is valid
manifests/sources.yaml - Secret/apps/auth-sops is skipped: kind skipped
Summary: 5 resources found in 2 files - Valid: 1, Invalid: 3, Skipped: 1

For CI pipelines and tooling, pass -o json (or -o yaml) to emit a machine-readable report instead of plain text:

flux schema validate ./manifests -o json

Example JSON output:

{
 "apiVersion": "schema.plugin.fluxcd.io/v1beta1",
 "kind": "Report",
 "$schema": "https://raw.githubusercontent.com/fluxcd/flux-schema/main/docs/report-v1beta1.json",
 "report": {
 "reporter": "flux-schema/v0.1.0",
 "timestamp": "2026-05-20T12:00:00Z",
 "summary": {
 "total": 3,
 "valid": 1,
 "invalid": 2,
 "skipped": 0
 },
 "results": [
 {
 "resource": {
 "apiVersion": "v1",
 "kind": "Namespace",
 "name": "apps"
 },
 "source": "manifests/apps.yaml",
 "idx": 1,
 "status": "valid"
 },
 {
 "resource": {
 "apiVersion": "helm.toolkit.fluxcd.io/v2",
 "kind": "HelmRelease",
 "name": "frontend",
 "namespace": "apps"
 },
 "source": "manifests/apps.yaml",
 "idx": 2,
 "status": "invalid",
 "reason": "cel-violation",
 "violations": [
 {
 "path": "/spec",
 "message": "Invalid value: either 'chart' or 'chartRef' must be set"
 }
 ]
 },
 {
 "resource": {
 "apiVersion": "source.toolkit.fluxcd.io/v1",
 "kind": "OCIRepository",
 "name": "frontend",
 "namespace": "apps"
 },
 "source": "manifests/apps.yaml",
 "idx": 3,
 "status": "invalid",
 "reason": "schema-violation",
 "violations": [
 {
 "path": "/spec",
 "message": "additional properties 'force' not allowed"
 },
 {
 "path": "/spec/interval",
 "message": "got number, want string"
 }
 ]
 }
 ]
 }
}

See the validation report reference for the full envelope shape, the reason enum, and an example covering every result type. The report is versioned by a published JSON Schema.

Validation rules

YAML documents with duplicate keys are rejected matching Flux behavior.
Documents missing both metadata.name and metadata.generateName are flagged as invalid matching Kubernetes API behavior.
metadata.name, generateName, namespace, and labels/annotations keys and values are checked against the Kubernetes API server’s ObjectMeta rules (DNS-1123, qualified names).
Schemas produced by flux schema extract crd close objects with additionalProperties: false, so undocumented fields under spec fail validation.
Kubernetes admission extensions are enforced for embedded resources and list topology: x-kubernetes-embedded-resource validates nested apiVersion, kind, and metadata, while x-kubernetes-list-type: map|set rejects duplicate list entries using x-kubernetes-list-map-keys for map lists.
String formats duration, date, datetime/date-time, and time are validated matching Kubernetes OpenAPI conventions.

CEL validation rules

By default, the validate command extracts the x-kubernetes-validations rules from the schemas and evaluates them as CEL expressions using the same engine as the Kubernetes API.

CEL evaluation runs only after JSON Schema validation passes, and any rule violations are reported with the cel-violation reason. Before evaluating rules, flux-schema applies the schema’s structural defaults in memory, matching kube-apiserver ordering. Transition rules referencing oldSelf evaluate with no prior state, matching the Kubernetes API behavior on CREATE.

The CEL validation can be disabled with the --skip-cel-rules flag.

Config file

Flag values can be pre-set in a YAML config file and referenced with--config or with the FLUX_SCHEMA_CONFIG environment variable. This keeps long invocations out of CI scripts and makes validation reproducible across environments.

flux schema validate ./manifests --config .fluxschema.yml

The file is wrapped in a Config API envelope and has a validate section for validation defaults. The shape is documented by the Config JSON Schema.

apiVersion: schema.plugin.fluxcd.io/v1beta1
kind: Config
validate:
 schemaLocation:
 - default
 - ecosystem
 skipKind:
 - source.toolkit.fluxcd.io/v1/ExternalArtifact
 skipJSONPath:
 - Secret:/sops
 skipFile:
 - '.*'
 - kustomization.yaml
 skipCELRules: false
 skipMissingSchemas: false
 verbose: true
 failFast: false
 concurrent: 8
 insecureSkipTLSVerify: false
 output: text

Rules:

CLI flags override config values. Setting --verbose=false wins over verbose: true in the file.
Setting --config overrides FLUX_SCHEMA_CONFIG. When both are set, the flag wins and the env var is ignored.
Manifest paths stay positional. The config file configures how to validate; paths are given on the command line.

Running in CI

GitHub Actions

See the validate action reference.

Docker

The ghcr.io/fluxcd/flux-schema image bakes the default catalog into /catalog/latest/, so manifests can be validated offline without fetching schemas from GitHub.

Mount the manifests directory and point --schema-location at the builtin catalog:

docker run --rm \
 -v "$PWD/manifests:/manifests:ro" \
 ghcr.io/fluxcd/flux-schema:latest validate /manifests \
 --schema-location /catalog/latest

Or pipe rendered manifests into the container over stdin (note the -i flag to keep stdin open):

kustomize build ./manifests | docker run --rm -i \
 ghcr.io/fluxcd/flux-schema:latest validate \
 --schema-location /catalog/latest \
 --skip-missing-schemas

Notes:

Use --schema-location /catalog/latest rather than default for air-gapped environments.
Pin the image to a release tag e.g. ghcr.io/fluxcd/flux-schema:v0.3.0.
Tu use your own schema catalog, repeat --schema-location with another mounted directory.

Flux: Kubernetes Schema Explain with Flux Schema CLI

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema explain command prints kubectl-style field documentation from JSON Schema catalogs, without contacting a Kubernetes API server.

Examples:

# Explain a native Kubernetes resource from a local catalog
flux schema explain pods --api-version=v1 --schema-location ./catalog

# Explain a Flux resource from a description-preserving remote catalog
flux schema explain hr.spec -s ecosystem

# Explain a nested field
flux schema explain pods.spec.containers --api-version=v1 --schema-location ./catalog

# Print nested fields recursively
flux schema explain pods --api-version=v1 --recursive --schema-location ./catalog

Flags

Flag	Description
`-s, --schema-location`	URL or file path for schemas (repeatable); `default` points at the built-in validation catalog, `ecosystem` at the CNCF ecosystem catalog.
`-f, --config`	YAML config file with `explain` defaults; defaults to `$FLUX_SCHEMA_CONFIG`, else `<executable>.config`.
`--api-version`	Get different explanations for a particular API version (`group/version`).
`--recursive`	Print fields of fields.
`-o, --output`	Output format, one of `plaintext` or `plaintext-openapiv2` (default: `plaintext`).
`--insecure-skip-tls-verify`	Disable TLS certificate verification when fetching schemas over HTTPS.

When --schema-location is not passed, explain reads config from --config, then $FLUX_SCHEMA_CONFIG, then a file next to the running binary named <binary>.config. That config must set explain.schemaLocation.

apiVersion: schema.plugin.fluxcd.io/v1beta1
kind: Config
explain:
 schemaLocation:
 - https://schemas.fluxoperator.dev/catalog

Resource References

explain resolves resource references in the same style as kubectl explain: kind names (OCIRepository.spec.verify), plural resource names (ocirepositories.spec.verify), full resource names (ocirepositories.source.toolkit.fluxcd.io.spec.verify), and short names (po.spec, hr.spec, ag.spec). Built-in Kubernetes short names are recognized by the command. CRD kinds, plural names, singular names, full resource names, and short names are resolved from sharded metadata under .explain/refs/ when custom catalogs provide it. For the ecosystem catalog, explain uses the hosted https://schemas.fluxoperator.dev/index.json to resolve resource references and provide shell completion without fetching thousands of per-resource metadata files. Resource completion suggests the canonical resource name (plural.group, or plural for core resources) for all indexed resources matching the typed prefix. Field completion resolves the typed resource reference, fetches that schema, and suggests matching child field paths while preserving the resource reference the user typed. Loaded schemas and not-found lookups are cached in memory for the life of the process; no disk cache is written.

When --api-version is set, dotted group suffixes are treated like kubectl: the first path segment is the resource name and the remaining segments are field names. Without --api-version, explain first tries to interpret dotted segments after the resource as an API group, then falls back to field lookup.

Catalogs

explain has two catalog modes.

Ecosystem index mode

The hosted ecosystem catalog is special. flux schema explain -s ecosystem uses https://schemas.fluxoperator.dev/index.json for resource lookup and resource-name completion. Field completion and command output fetch only the schema JSON needed for the resolved resource. Because the index already provides plural names, short names, full resource names, and resource completion candidates, the catalog does not need alias redirect files or a .explain/ tree.

Schemas used with this mode should be generated with JSON-only explain type metadata:

flux schema extract k8s --with-explain-type-metadata -d ./catalog

--with-explain-type-metadata keeps only schema-local JSON hints used after a schema has been loaded, such as named field types (Container, Quantity, IntOrString) and referenced type descriptions. It does not write alias JSON files, .explain/refs/, or .explain/completion/.

Standalone catalog mode

Use standalone mode for custom catalogs that must contain everything flux schema explain needs without the ecosystem index.

flux schema extract k8s --with-explain-metadata -d ./catalog
flux schema extract crd --with-explain-metadata -d ./catalog

--with-explain-metadata is the full explain mode. It is a superset of --with-explain-type-metadata: it keeps the schema-local JSON type hints and also writes alias redirects, .explain/refs/ lookup files, and .explain/completion/ shards used for kubectl-style resource references and type-reference shell completion.

--with-field-index is independent from both modes. It writes .fields.txt sidecars for search and agent workflows. explain does not use field indexes for resource lookup, completion, field rendering, type names, or descriptions. It can read them only as a fallback for root apiVersion and kind when JSON explain metadata is missing.

Catalogs generated with --strip-description still resolve fields, but they cannot reproduce kubectl’s descriptive output byte-for-byte because regular descriptions and explain type descriptions are removed.

Flux: GitOps Repository Discovery with Flux Schema CLI

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema discover command catalogs the Kubernetes manifests in a GitOps repository and emits a structured inventory. The inventory is designed for AI agents and automation auditing a repository: it maps the directory structure, lists every Flux resource with its defining file, and counts plain Kubernetes resources.

flux schema discover ./my-gitops-repo -o json

The scan is purely static: no kustomize builds, no Helm rendering, no cluster access. Resources are counted once, where they are defined on disk. To validate the rendered output of kustomize overlays, see the manifest validation guide.

Why AI agents should use this command

An agent exploring a GitOps repository with tree, ls and grep sees file names and string matches, not resources. Flux Schema discovery replaces the read-and-grep loop that follows with one deterministic pass:

File names reveal nothing. GitOps repos are full of sync.yaml, release.yaml and multi-document files; a file listing cannot reveal what resources a file holds, which API versions they use, or their names and namespaces. The inventory extracts all of it in one call instead of N file reads.
String matching miscounts. grep -rl "kind: HelmRelease" matches kustomize patch files and patch-target references alongside real resources. The inventory excludes patch files by resolving the kustomization patches references, so every resource is counted exactly once across base and overlays.
Every kind carries its API version. The resources census counts every resource per apiVersion/Kind, Flux and plain Kubernetes alike, so outdated API versions of any CRD are visible from the inventory alone.
The output is budgeted for context windows. Flux resources — the usual audit subjects — are enumerated per file; plain Kubernetes resources appear only as counts (2,000 Deployments cost a few lines, not thousands); Helm chart and Terraform subtrees are pruned. A typical repository inventories in a few KB.
The shape is a versioned contract. The JSON envelope is validated by a published JSON Schema, so agents can parse it programmatically instead of interpreting ad-hoc shell output.

For very large repositories (hundreds of Flux resources), the inventory grows with the Flux resource count in every output format. Scope the scan to the subtree under audit (flux schema discover ./clusters/production -o json) or exclude directories with --skip-file to keep the output small.

tree remains useful for what discover deliberately ignores: READMEs, scripts, CI configs, and other non-Kubernetes content.

Flags

Flag	Default	Description
`[path]`	`.`	Directory (or single file) to scan.
`--skip-file`	`.*`	Glob pattern matched against file and directory basenames, repeatable. The default skips dotfiles and dot-directories such as `.git`.
`-o, --output`	`text`	Output format: `text`, `json` or `yaml`.

The command always exits zero on a successful scan, even when nothing is found — discovery is informational. Reading from stdin is not supported: directory classification is path-based and meaningless for a stream.

Classification rules

Both .yaml and .yml files are scanned. Per YAML document:

Documents without both apiVersion and kind are ignored.
Documents in the kustomize.config.k8s.io group mark their directory as a kustomize overlay and are not counted as resources.
Every resource is counted per apiVersion/Kind in the resources census.
Documents whose API group contains fluxcd are Flux resources, additionally listed under flux with their defining file.

Every directory in the inventory carries one of four types:

Type	Meaning
`kubernetes-manifests`	Plain Kubernetes YAML manifests.
`kustomize-overlay`	Contains a kustomize configuration file.
`helm-chart`	Contains a `Chart.yaml`; the directory subtree is not scanned.
`terraform-module`	Contains `.tf` files; the directory subtree is not scanned.

When a directory holds both a Chart.yaml and .tf files, the Helm chart classification wins.

Kustomize patch files

Files referenced as kustomize patches (patches, patchesStrategicMerge, patchesJson6902) are excluded from the inventory entirely. Patch files look like full manifests but only describe modifications to resources defined elsewhere, so counting them would duplicate resources across base and overlays. Inline patches need no special handling. An overlay directory whose only content is the kustomize configuration and patch files still appears in directories as kustomize-overlay.

Path handling

All source and path values in the inventory are /-separated and relative to the scanned root; resources at the root itself land in the . directory. Unlike Git-based tooling, discover does not honor .gitignore — use --skip-file to exclude generated or vendored directories by basename.

The scan is confined to the scanned root at the operating-system level, so a link pointing outside the repository can never leak content into the inventory or make the scan read arbitrary files. Symbolic links are not followed even when they stay inside the root: the walk already visits the real target, so following the link too would list the same resource twice.

Output

The default text output mirrors the envelope order — directory classifications, the per-GVK resource census, the Flux resources by defining file, and summary line:

Directories:
 apps/base: kustomize-overlay
 apps/overlays/prod: kustomize-overlay
 charts/podinfo: helm-chart
 clusters/prod: kubernetes-manifests
 infra/tf: terraform-module
 legacy: kubernetes-manifests
Resources:
 apps/v1/Deployment: 1
 fluxcd.controlplane.io/v1/FluxInstance: 1
 helm.toolkit.fluxcd.io/v2/HelmRelease: 1
 kustomize.toolkit.fluxcd.io/v1/Kustomization: 1
 source.toolkit.fluxcd.io/v1/GitRepository: 1
 v1/ConfigMap: 1
 v1/Service: 1
Flux:
 FluxInstance:
 clusters/prod/instance.yaml: flux-system/flux
 GitRepository:
 clusters/prod/flux-system.yaml: flux-system/flux-system
 HelmRelease:
 apps/base/podinfo.yaml: podinfo/podinfo
 Kustomization:
 clusters/prod/flux-system.yaml: flux-system/apps
Summary: 7 resources found in 8 files with 92 lines of YAML

With -o json or -o yaml the command emits the versioned Inventory envelope documented in the inventory reference: resources counts everything per apiVersion/Kind, and flux maps each Flux kind to its defining files and the namespace/name identities they declare (the API version is already in the census):

{
 "apiVersion": "schema.plugin.fluxcd.io/v1beta1",
 "kind": "Inventory",
 "$schema": "https://raw.githubusercontent.com/fluxcd/flux-schema/main/docs/inventory-v1beta1.json",
 "inventory": {
 "reporter": "flux-schema/0.3.0",
 "timestamp": "2026-06-11T10:30:00Z",
 "summary": {
 "files": 8,
 "resources": 7,
 "lines-of-yaml": 92
 },
 "directories": {
 "apps/base": "kustomize-overlay",
 "apps/overlays/prod": "kustomize-overlay",
 "charts/podinfo": "helm-chart",
 "clusters/prod": "kubernetes-manifests",
 "infra/tf": "terraform-module",
 "legacy": "kubernetes-manifests"
 },
 "resources": {
 "apps/v1/Deployment": 1,
 "fluxcd.controlplane.io/v1/FluxInstance": 1,
 "helm.toolkit.fluxcd.io/v2/HelmRelease": 1,
 "kustomize.toolkit.fluxcd.io/v1/Kustomization": 1,
 "source.toolkit.fluxcd.io/v1/GitRepository": 1,
 "v1/ConfigMap": 1,
 "v1/Service": 1
 },
 "flux": {
 "FluxInstance": {
 "clusters/prod/instance.yaml": ["flux-system/flux"]
 },
 "GitRepository": {
 "clusters/prod/flux-system.yaml": ["flux-system/flux-system"]
 },
 "HelmRelease": {
 "apps/base/podinfo.yaml": ["podinfo/podinfo"]
 },
 "Kustomization": {
 "clusters/prod/flux-system.yaml": ["flux-system/apps"]
 }
 }
 }
}

Reading the inventory

The inventory answers an auditing agent’s first questions without any grepping:

Repository pattern — the sorted directories map reads as a tree. GitRepository or OCIRepository resources defined in the same directories as Flux Kustomization resources (typically under clusters/) mark cluster sync entrypoints; FluxInstance resources indicate a Flux Operator managed cluster.
Navigation — every Flux kind in flux is keyed by its defining files, so an agent can open exactly the files relevant to an audit.
API currency — the resources census is keyed by apiVersion/Kind, so deprecated API versions of Flux and third-party CRDs stand out without reading a single manifest.
Scope boundaries — helm-chart and terraform-module directories exist in the map but contribute no resources, signaling that their contents are not Kubernetes manifests to lint.

Flux: Maintaining Custom Catalogs with Flux Schema CLI

Mon, 01 Jan 0001 00:00:00 +0000

A catalog is a directory tree of JSON Schemas laid out so that flux schema validate can resolve a schema from a manifest’s apiVersion and kind. The built-in Flux Schema catalog ships schemas for Kubernetes, OpenShift, Gateway API, and the Flux ecosystem; custom catalogs let you cover internal CRDs, pin specific upstream versions, or assemble a layout that fits your tooling. For third-party CRDs you don’t want to extract yourself, the hosted ecosystem catalog is available via --schema-location ecosystem.

Layout

The default resolution template is:

{{ .Group }}/{{ .Kind }}_{{ .Version }}.json

For example, apiVersion: source.toolkit.fluxcd.io/v1, kind: GitRepository resolves to source.toolkit.fluxcd.io/GitRepository_v1.json.

All template variables are lowercased at render time, so the file names on disk are lowercase even though apiVersion/kind are mixed case.

If you need a different layout (for example the kubeconform/kubeval flat form), pass a full template to --schema-location:

flux schema validate ./manifests \
 --schema-location './my-catalog/{{.Kind}}-{{.GroupPrefix}}-{{.Version}}.json'

Supported template variables:

Variable	Example
`.Group`	`source.toolkit.fluxcd.io`
`.GroupPrefix`	`source`
`.Kind`	`gitrepository`
`.Version`	`v1`

An empty .Group (Kubernetes core API, e.g. apiVersion: v1) is normalized to core, and .GroupPrefix is derived from .Group when unset. So a core Pod renders as core/pod_v1.json with the default template and resolves to the same path when validate looks up its schema.

The extract commands described below all share the same default template and -f, --output-format flag, so a single --schema-location resolves everything you generate.

Populating a catalog

The flux schema extract commands write one JSON Schema file per kind, using the layout above by default. Mix and match these commands to cover the Kubernetes core APIs, OpenShift resources, and any CRDs your manifests rely on.

Kubernetes CRDs

flux schema extract crd [files...]

Reads bare CRDs, a List of CRDs, or a multi-document YAML stream, and emits one schema file per CRD version.

Flag	Description
`-d, --output-dir`	Directory to write JSON Schema files to (mutually exclusive with `--output-archive`).
`-a, --output-archive`	Path to write a gzipped tar archive of JSON Schema files to.
`-f, --output-format`	Go template for output file paths (default: `{{ .Group }}/{{ .Kind }}_{{ .Version }}.json`).
`--index-source`	Source name and version recorded in field index headers, overriding auto-detection.
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.
`--with-field-index`	Also write a `.fields.txt` field index next to each schema.
`--with-explain-type-metadata`	Keep JSON-only explain type hints, without writing explain lookup files.
`--with-explain-metadata`	Include JSON type hints, alias redirects, and `.explain/` lookup shards used by standalone `flux schema explain` catalogs.

Generate schemas for every CRD installed in a cluster:

kubectl get crds -o yaml | flux schema extract crd -d ./my-catalog

Or from a kustomize build of an operator’s CRD bundle:

kustomize build ./config/crd | flux schema extract crd -d ./my-catalog

The output is also compatible with kubeconform and kubeval, making extract crd a drop-in replacement for kubeconform’s openapi2jsonschema.py script.

Kubernetes APIs

flux schema extract k8s [swagger-file]

Reads a Kubernetes OpenAPI v2 swagger document and emits one file per kind listed under x-kubernetes-group-version-kind. Helper types (e.g. PodSpec, ObjectMeta) are inlined into the kinds that reference them, not written as standalone files.

Flag	Description
`--version X.Y.Z`	Fetch the swagger from `github.com/kubernetes/kubernetes` for the given release tag (mutually exclusive with a swagger file).
`-d, --output-dir`	Directory to write JSON Schema files to.
`-f, --output-format`	Go template for output file paths (default: `{{ .Group }}/{{ .Kind }}_{{ .Version }}.json`).
`--index-source`	Source name and version recorded in field index headers, overriding auto-detection.
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.
`--with-field-index`	Also write a `.fields.txt` field index next to each schema.
`--with-explain-type-metadata`	Keep JSON-only explain type hints, without writing explain lookup files.
`--with-explain-metadata`	Include JSON type hints, alias redirects, and `.explain/` lookup shards used by standalone `flux schema explain` catalogs.

Pin the catalog to a specific Kubernetes release:

flux schema extract k8s --version 1.35.0 -d ./my-catalog

Or extract from a live cluster:

kubectl get --raw /openapi/v2 | flux schema extract k8s -d ./my-catalog

Core API kinds (apiVersion: v1) render under the core/ group directory.

OpenShift APIs

flux schema extract openshift [swagger-file]

Reads an openshift/api OpenAPI v2 swagger document and emits one file per OpenShift resource. Only definitions in the openshift namespace are emitted; embedded upstream Kubernetes types (e.g. Pod) are inlined.

Flag	Description
`--ref REF`	Fetch the swagger from `github.com/openshift/api` at the given git ref (e.g. `release-4.20`); mutually exclusive with a swagger file.
`-d, --output-dir`	Directory to write JSON Schema files to.
`-f, --output-format`	Go template for output file paths (default: `{{ .Group }}/{{ .Kind }}_{{ .Version }}.json`).
`--index-source`	Source name and version recorded in field index headers, overriding auto-detection.
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.
`--with-field-index`	Also write a `.fields.txt` field index next to each schema.
`--with-explain-type-metadata`	Keep JSON-only explain type hints, without writing explain lookup files.
`--with-explain-metadata`	Include JSON type hints, alias redirects, and `.explain/` lookup shards used by standalone `flux schema explain` catalogs.

Pin to an OpenShift release branch:

flux schema extract openshift --ref release-4.20 -d ./my-catalog

Or feed in a downloaded swagger:

curl -sL https://raw.githubusercontent.com/openshift/api/release-4.20/openapi/openapi.json | \
 flux schema extract openshift -d ./my-catalog

A typical refresh script

A single script can populate a catalog with everything you need — the default -f template means the outputs land side by side under the same root and resolve to one --schema-location:

#!/usr/bin/env bash
set -euo pipefail

CATALOG=./my-catalog
mkdir -p "$CATALOG"

# Kubernetes core + built-ins
flux schema extract k8s --version 1.35.0 --strip-description -d "$CATALOG"

# Vendor CRDs at a pinned version
kubectl kustomize \
 https://github.com/external-secrets/external-secrets/config/crds/bases?ref=v2.3.0 | \
 flux schema extract crd --strip-description -d "$CATALOG"

Pass --strip-description to every generator to keep the catalog small — the official catalog uses it everywhere and gets about a 54% size reduction on native Kubernetes schemas.

The official catalog’s generator scripts under scripts/ are a working reference: gen-k8s-schemas.sh, gen-flux-schemas.sh, gen-crd-schemas.sh, and gen-openshift-schemas.sh.

Schema output

All extract commands emit the standalone-strict JSON Schema variant, so schemas in the catalog are usable on their own and reproduce the constraints the Kubernetes API server enforces:

Every $ref is inlined, so each schema has no cross-file dependencies.
Objects with properties are closed with additionalProperties: false, except under nodes marked x-kubernetes-preserve-unknown-fields: true, which stay open so free-form maps validate correctly.
Kubernetes admission validation extensions are preserved when they affect manifest validation: x-kubernetes-embedded-resource, x-kubernetes-list-type, x-kubernetes-list-map-keys, x-kubernetes-map-type, x-kubernetes-preserve-unknown-fields, and x-kubernetes-validations. Merge/patch-only extensions are stripped.
Integer-or-string fields are rewritten to oneOf: [{type: string}, {type: integer}]. Both the legacy format: int-or-string and the structural x-kubernetes-int-or-string: true forms are recognized.
Optional fields are marked nullable (type: [<t>, "null"]), matching the API server’s behavior of accepting null for unset optional values.
apiVersion and kind are injected into every kind’s properties and required list.
x-flux-schema-* explain annotations are omitted by default. They are documentation-only and do not affect JSON Schema validation.

Explain metadata

extract can write two layers of metadata used by flux schema explain. They are opt-in so validation-only catalogs do not grow by default.

Schema-local type metadata is stored inside each JSON Schema. It preserves field render hints that are otherwise lost when OpenAPI $ref definitions are inlined, such as named nested types (Container, Quantity, IntOrString) and referenced type descriptions. Pass --with-explain-type-metadata when another index provides resource lookup and resource-name completion. This is the ecosystem catalog mode used with --schema-location ecosystem, where explain resolves resources from https://schemas.fluxoperator.dev/index.json and uses the loaded JSON schema for kubectl-style field output and field-path completion.

Standalone explain metadata includes the schema-local type metadata plus the lookup files needed when there is no separate ecosystem index: alias redirect JSON files, .explain/refs/, and .explain/completion/. Pass --with-explain-metadata for custom catalogs that should support flux schema explain resource references and resource-name shell completion on their own. Field-path completion is derived from the resolved JSON Schema. This flag is a superset of --with-explain-type-metadata.

--with-field-index is separate. It writes .fields.txt sidecars for search, agents, and other catalog consumers. explain does not use field indexes for resource lookup, completion, field rendering, type names, or descriptions. It can read .fields.txt only as a compatibility fallback to recover root apiVersion and kind when JSON explain metadata is absent.

Catalogs generated with --strip-description still validate resources and resolve fields, but they cannot reproduce kubectl’s descriptive output byte-for-byte because descriptions and explain type descriptions are removed.

Field indexes

Pass --with-field-index to the extract commands to write greppable, LLM-friendly field indexes alongside the extracted schemas: one .fields.txt file per schema, with one self-contained line per field. See the field index reference for the file naming, line grammar, and annotations. Field indexes are independent from explain metadata.

Hosting

A catalog is just a tree of files. The validator’s loader fetches each rendered location over http/https or from the local filesystem. Common options:

Filesystem: vendor the catalog into the same repo as your manifests, or publish it as a release artifact / OCI artifact and unpack it in CI.
HTTP(S): serve the catalog from any static host (GitHub raw, S3, GitHub Pages, etc.) and pass the base URL to --schema-location. The loader expands bare URLs with the default template.

A 404 or ENOENT for a given apiVersion/kind falls through to the next --schema-location, so you can layer your catalog on top of the built-in one:

flux schema validate ./manifests \
 --schema-location ./my-catalog \
 --schema-location default

Order matters — the first match wins, so put your overrides before default.

Refreshing

Custom catalogs go stale as upstream versions move. Schedule the refresh script in CI (cron workflow, scheduled pipeline, etc.) and commit the result back, the same way the official catalog is updated by .github/workflows/update-catalog.yaml.

Flux: Field Indexes for AI Agents

Mon, 01 Jan 0001 00:00:00 +0000

Pass --with-field-index to extract crd, extract k8s, or extract openshift to write greppable, LLM-friendly field indexes alongside the extracted schemas. Each index is a plain-text UTF-8 file with one self-contained line per field: full dotted path, type, constraints, and description when available. An agent greps a dotted path or keyword instead of reading the full JSON Schema.

The index serves agents in three roles:

Authoring manifests — the spec subtree tells the agent which fields exist, which are (required), and which values are legal (enum=, pattern=, min=/max=, default=), so generated YAML passes flux schema validate on the first attempt.
Assessing resources — the status subtree tells the agent what the controller reports, for interpreting the state of a resource and for authoring expressions against it: health check CEL (healthCheckExprs, readyExpr), monitoring queries, and troubleshooting. (immutable) markers tell the agent when a change requires recreating the resource instead of patching it.
Understanding semantics — the descriptions carry what the schema cannot express: field precedence, mutual exclusions, units, and expected values documented only in prose. For fields outside the agent’s training data — new API versions or private CRDs — the description line is its only source of meaning, grounding answers in the upstream documentation instead of guesswork.

Compared to kubectl explain, the index answers offline without a cluster or installed CRD, in one self-contained line instead of a per-path query, keeps descriptions in full-tree listings (where explain --recursive drops them), surfaces constraints systematically, and supports keyword search across all fields and kinds — the agent does not need to know a field’s path to find it.

File naming

The index path is derived from the rendered schema path. If --output-format renders a path ending in .json, that suffix is replaced with .fields.txt; otherwise .fields.txt is appended. For example, helm.toolkit.fluxcd.io/helmrelease_v2.json gets helm.toolkit.fluxcd.io/helmrelease_v2.fields.txt.

Comments

Lines beginning with # are comments: they carry metadata about the index rather than field definitions, so tools that parse the line grammar must skip them (and tolerate comment keys added in the future). When known, an index begins with # schema source: <value>; when unknown, the comment is omitted and the index starts directly with the apiVersion line.

The schema source value is composed by command: extract crd joins the CRD labels app.kubernetes.io/part-of and app.kubernetes.io/version when present, extract k8s records Kubernetes <info.version> (or Kubernetes, with --version appended when the swagger has no real version), and extract openshift records OpenShift <info.version> (or OpenShift, with --ref appended when the swagger has no version). Pass --index-source to override auto-detection for every index in an invocation.

Line grammar

Each field line has path <type>, optional annotations, then an optional description separated by one TAB and written as # description. Tokens before the description are separated by one space:

line = comment-line | field-line
comment-line = "# " text
field-line = path SPACE type [SPACE "(required)"] [SPACE enum]
 [SPACE default] [SPACE format] [SPACE pattern]
 [SPACE min] [SPACE max] [SPACE "(immutable)"]
 [SPACE "(deprecated)"] [SPACE "(cluster-scoped)"]
 [TAB "# " description]

path = segment *( "." segment )
segment = name | name "[]" | "<key>"
type = "<" typename ">"
enum = "enum=" value *( "|" value )
default = "default=" json-value
format = "format=" value
pattern = "pattern=" json-string
min = "min=" json-number
max = "max=" json-number

# schema source: is the only comment key currently emitted; parsers must tolerate other keys. (deprecated) appears only on the apiVersion header line and (cluster-scoped) only on the kind header line.

Two guarantees matter for parsing. Descriptions (including deprecation warnings) are whitespace-normalized — newlines and tabs collapse to single spaces — so a line contains at most one TAB, and splitting on the first TAB always separates the tokens from the description. Naive space-splitting of the tokens is unsafe: the type token may contain a space (<object (free-form)>), and JSON-encoded annotation values may too (pattern="^foo bar$"); parse the type as a <...>-delimited token and treat quoted annotation values as JSON strings.

Example lines from a HelmRelease index:

# schema source: flux v2.8.5
apiVersion <string> enum=helm.toolkit.fluxcd.io/v2
kind <string> enum=HelmRelease
metadata.name <string> (required)
metadata.namespace <string> (required)
spec <object> # HelmReleaseSpec defines the desired state of a Helm release.
spec.valuesFrom <[]object> # ValuesFrom holds references to resources containing Helm values for this HelmRelease, and information about how they should be merged.
spec.valuesFrom[].kind <string> (required) enum=Secret|ConfigMap # Kind of the values referent, valid values are ('Secret', 'ConfigMap').
spec.valuesFrom[].name <string> (required) min=1 max=253 # Name of the values referent. Should reside in the same namespace as the referring resource.

Path notation

Notation	Meaning	Example
`a.b.c`	Nested object field.	`spec.chart.spec`
`a[]`	Array of objects; child fields continue below the array.	`spec.dependsOn[]` -> `spec.dependsOn[].name`
`a.<key>.`	Object map value fields.	`spec.devices[].attributes.<key>.version <string>`

The .<key>. segment means “for each key in this map”; it is used when a map has object values with known fields.

Type notation

Type notation uses Kubernetes schema types in angle brackets:

<string>, <integer>, <number>, <boolean> — scalar fields.
<object> — object with known fields, listed below it.
<object (free-form)> — object without a defined structure.
<[]string> (or the matching scalar type) — array of scalars.
<[]object> — array of objects; child fields continue under a[]..
<map[string]string> (or the matching value type) — map with scalar values.
<map[string]object> — map with object values; child fields, when known, continue under .<key>..
<int-or-string> — accepts an integer or a string.
<any> — untyped (e.g. preserves unknown fields).

Annotations

Annotations are suffix tokens after the type. Facts that carry a value use the key=value form; boolean facts are parenthesized markers whose presence means true and whose absence means false.

Key-value annotations:

enum=a|b|c — allowed values; values containing whitespace or | are JSON-encoded, all other values stay verbatim.
default=<json> — the schema default, JSON-encoded.
format=<value> — the schema format (e.g. date-time).
pattern=<json-string> — the regex pattern, always JSON-encoded.
min=<n> / max=<n> — minimum/maximum for number and integer fields, minLength/maxLength for strings, minItems/maxItems for arrays.

Boolean markers:

(required) — the field appears in the parent schema’s required list.
(immutable) — the field carries a CEL validation rule equal to self == oldSelf (either operand order), or its description contains Cannot be updated..
(deprecated) — on the apiVersion header line only, when the CRD version is deprecated; the deprecation warning is appended as its description when present.
(cluster-scoped) — on the kind header line only, when the resource is cluster-scoped; such indexes have no metadata.namespace line.

Header lines

After the optional schema source comment, every index starts with header lines for apiVersion, kind, metadata.name, and, when applicable, metadata.namespace. apiVersion and kind use enum= values from the extracted GVK, and metadata.name is always emitted with (required). The resource scope determines the rest:

namespaced kinds: metadata.namespace <string> (required) is emitted.
cluster-scoped kinds: the metadata.namespace line is omitted and the kind line ends with (cluster-scoped).
unknown scope: metadata.namespace <string> is emitted without (required).

extract crd reads exact scope from spec.scope; extract k8s and extract openshift derive it from swagger paths (the openshift/api document carries none, so its scope comes out unknown).

The header lines replace the schema’s own apiVersion, kind, and metadata properties, which are suppressed from the body: fields like metadata.labels and metadata.annotations are standard across all kinds and deliberately not listed — their absence from an index does not mean they are unsupported.

Generation notes

Indexes are generated before --strip-description is applied, so field index descriptions are preserved even when the JSON Schemas are stripped. For extract k8s and extract openshift, schemas whose kind ends in List still write JSON Schema files but do not write .fields.txt indexes.

Grep recipes

grep '^spec\.chart\.' helmrelease_v2.fields.txt # subtree listing
grep 'valuesFrom' helmrelease_v2.fields.txt # locate a field
grep '(required)' helmrelease_v2.fields.txt # all required fields
grep '^status\.' helmrelease_v2.fields.txt # fields reported by the controller
grep -r 'certSecretRef' ./my-catalog # which kinds support custom TLS certs

Flux: Flux Schema Inventory

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema discover command can emit a structured inventory of a GitOps repository by setting --output to json or yaml. The envelope shape is versioned and documented by the JSON Schema in inventory-v1beta1.json.

Usage

flux schema discover ./my-gitops-repo -o json

See the repository discovery guide for the classification rules behind the inventory data.

Envelope

Every inventory is wrapped in a top-level envelope:

Key	Description
`apiVersion`	Inventory API version. Currently `schema.plugin.fluxcd.io/v1beta1`.
`kind`	Inventory API kind. Currently `Inventory`.
`$schema`	URL of the JSON Schema describing the envelope.
`inventory.reporter`	Identity of the producer, e.g. `flux-schema/0.3.0`.
`inventory.timestamp`	RFC 3339 UTC timestamp of the scan.
`inventory.summary`	Aggregate counts: `files`, `resources`, `lines-of-yaml`.
`inventory.directories`	Map of directory path to classification.
`inventory.resources`	Map of `apiVersion/Kind` to resource count, for all resources.
`inventory.flux`	Map of Flux resource kind to defining files and identities.

All maps serialize with sorted keys, so the output is deterministic and diff-friendly.

Directories

directories maps every directory containing scanned manifests, plus Helm chart and Terraform directories, to one of four classifications: kubernetes-manifests, kustomize-overlay, helm-chart, or terraform-module. Paths are relative to the scanned root and /-separated; the root itself is ..

"directories": {
 "apps/base": "kustomize-overlay",
 "charts/podinfo": "helm-chart"
}

Resources

resources is the complete census: every resource in the repository, counted per apiVersion/Kind. The exact API version of every kind is visible without opening any file.

"resources": {
 "apps/v1/Deployment": 12,
 "cert-manager.io/v1/ClusterIssuer": 1,
 "helm.toolkit.fluxcd.io/v2/HelmRelease": 3
}

Flux

flux locates every Flux custom resource. Keys are bare kinds — their API versions are already stated in resources. Each kind maps the defining file path (relative to the scanned root) to the resource identities declared in that file:

"flux": {
 "HelmRelease": {
 "apps/base/podinfo.yaml": ["podinfo/podinfo"]
 },
 "Kustomization": {
 "clusters/production/apps.yaml": ["flux-system/apps"],
 "clusters/staging/apps.yaml": ["flux-system/apps"]
 }
}

Identities are namespace/name; the namespace/ segment is omitted for resources without a namespace, and the name is - when the document has no metadata.name. Multi-document files list their identities in document order.

Plain Kubernetes resources are intentionally not enumerated per item: a large repository can hold thousands of them, and the census combined with the directory map locates them precisely enough.

When the same kind exists in more than one API version — typically mid-migration — its files merge under the kind key, while resources still reports each version separately.

Example

{
 "apiVersion": "schema.plugin.fluxcd.io/v1beta1",
 "kind": "Inventory",
 "$schema": "https://raw.githubusercontent.com/fluxcd/flux-schema/main/docs/inventory-v1beta1.json",
 "inventory": {
 "reporter": "flux-schema/0.3.0",
 "timestamp": "2026-06-11T10:30:00Z",
 "summary": {
 "files": 8,
 "resources": 8,
 "lines-of-yaml": 99
 },
 "directories": {
 "apps/base": "kustomize-overlay",
 "apps/overlays/prod": "kustomize-overlay",
 "charts/podinfo": "helm-chart",
 "clusters/prod": "kubernetes-manifests",
 "infra/tf": "terraform-module"
 },
 "resources": {
 "apps/v1/Deployment": 1,
 "fluxcd.controlplane.io/v1/FluxInstance": 1,
 "helm.toolkit.fluxcd.io/v2/HelmRelease": 1,
 "kustomize.toolkit.fluxcd.io/v1/Kustomization": 1,
 "source.toolkit.fluxcd.io/v1/GitRepository": 1,
 "source.toolkit.fluxcd.io/v1/OCIRepository": 1,
 "v1/ConfigMap": 1,
 "v1/Service": 1
 },
 "flux": {
 "FluxInstance": {
 "clusters/prod/instance.yaml": ["flux-system/flux"]
 },
 "GitRepository": {
 "clusters/prod/flux-system.yaml": ["flux-system/flux-system"]
 },
 "HelmRelease": {
 "apps/base/podinfo.yaml": ["podinfo/podinfo"]
 },
 "Kustomization": {
 "clusters/prod/flux-system.yaml": ["flux-system/apps"]
 },
 "OCIRepository": {
 "apps/base/podinfo.yaml": ["podinfo/podinfo"]
 }
 }
 }
}

Flux: Flux Schema Report

Mon, 01 Jan 0001 00:00:00 +0000

The flux schema validate command can emit a structured report of the validation results by setting --output to json or yaml. The envelope shape is versioned and documented by the JSON Schema in report-v1beta1.json.

Usage

flux schema validate ./manifests -o json

Structured output always emits every result regardless of --verbose. Filtering belongs downstream (jq, yq). The process exit code still reflects whether any document was invalid.

Envelope

Every report is wrapped in a top-level envelope:

Key	Description
`apiVersion`	Report API version. Currently `schema.plugin.fluxcd.io/v1beta1`.
`kind`	Report API kind. Currently `Report`.
`$schema`	URL of the JSON Schema describing the envelope.
`report.reporter`	Identity of the producer, e.g. `flux-schema/0.1.0`.
`report.timestamp`	RFC 3339 UTC timestamp of the run.
`report.summary`	Aggregate counts: `total`, `valid`, `invalid`, `skipped`.
`report.results[]`	One entry per validated document, in source order.

Result fields

Key	Description
`resource`	`{apiVersion, kind, namespace?, name?}` or `null` when no Kubernetes identity could be recovered (e.g. a file that fails to open, or stdin that is not YAML).
`source`	File path or `stdin`.
`idx`	1-based position of the document within its source. `0` for source-level failures that have no document.
`status`	`"valid"`, `"invalid"`, or `"skipped"`.
`reason`	Stable kebab-case code (see below). Omitted when `status` is `"valid"`.
`violations[]`	Zero or more `{path?, message}` entries. `path` is a JSON Pointer set by schema violations; for every other reason it is absent and `message` carries the raw error text.

Reasons

Reason	Triggered by
`source-load-error`	Source-level open/read failure.
`yaml-parse-error`	Strict YAML decode fails (duplicate keys, malformed doc).
`schema-load-error`	Schema loader failure (HTTP fetch, file read, or JSON Schema compile).
`schema-not-found`	No schema applicable — either no schema file matches the GVK, or the document has no GVK to look up.
`schema-violation`	Document fails one or more schema constraints. `violations[]` carries a JSON Pointer `path` per entry.
`cel-violation`	Document fails one or more `x-kubernetes-validations` CEL rules, or the schema’s CEL evaluator could not be built. JSON Schema constraints all passed.
`kind-skipped`	Matched a `--skip-kind` pattern.

Example

{
 "apiVersion": "schema.plugin.fluxcd.io/v1beta1",
 "kind": "Report",
 "$schema": "https://raw.githubusercontent.com/fluxcd/flux-schema/main/docs/report-v1beta1.json",
 "report": {
 "reporter": "flux-schema/v0.1.0",
 "timestamp": "2026-06-01T12:00:00Z",
 "summary": {
 "total": 7,
 "valid": 1,
 "invalid": 5,
 "skipped": 1
 },
 "results": [
 {
 "resource": {
 "apiVersion": "apps/v1",
 "kind": "Deployment",
 "namespace": "default",
 "name": "web"
 },
 "source": "manifests/app.yaml",
 "idx": 1,
 "status": "valid"
 },
 {
 "resource": {
 "apiVersion": "source.toolkit.fluxcd.io/v1",
 "kind": "Bucket",
 "namespace": "apps",
 "name": "minio"
 },
 "source": "manifests/sources.yaml",
 "idx": 1,
 "status": "invalid",
 "reason": "schema-violation",
 "violations": [
 {
 "path": "/spec",
 "message": "missing property 'bucketName'"
 },
 {
 "path": "/spec/interval",
 "message": "got number, want string"
 },
 {
 "path": "/spec",
 "message": "additional properties 'force' not allowed"
 }
 ]
 },
 {
 "resource": {
 "apiVersion": "source.toolkit.fluxcd.io/v1",
 "kind": "OCIRepository",
 "namespace": "default",
 "name": "podinfo"
 },
 "source": "manifests/sources.yaml",
 "idx": 2,
 "status": "invalid",
 "reason": "yaml-parse-error",
 "violations": [
 {
 "message": "line 18: key \"app.kubernetes.io/name\" already set in map"
 }
 ]
 },
 {
 "resource": null,
 "source": "manifests/missing.yaml",
 "idx": 0,
 "status": "invalid",
 "reason": "source-load-error",
 "violations": [
 {
 "message": "open manifests/missing.yaml: no such file or directory"
 }
 ]
 },
 {
 "resource": {
 "apiVersion": "example.com/v1",
 "kind": "Widget",
 "namespace": "default",
 "name": "w1"
 },
 "source": "manifests/widgets.yaml",
 "idx": 1,
 "status": "invalid",
 "reason": "schema-load-error",
 "violations": [
 {
 "message": "Get \"https://schemas.example.com/Widget_v1.json\": dial tcp: lookup schemas.example.com: no such host"
 }
 ]
 },
 {
 "resource": {
 "apiVersion": "artifact.toolkit.fluxcd.io/v1",
 "kind": "ArtifactGenerator",
 "namespace": "apps",
 "name": "podinfo"
 },
 "source": "manifests/artifacts.yaml",
 "idx": 1,
 "status": "invalid",
 "reason": "schema-not-found",
 "violations": [
 {
 "message": "no schema for kind \"ArtifactGenerator\" in version \"artifact.toolkit.fluxcd.io/v1\""
 }
 ]
 },
 {
 "resource": {
 "apiVersion": "v1",
 "kind": "Secret",
 "namespace": "apps",
 "name": "auth-sops"
 },
 "source": "manifests/secrets.yaml",
 "idx": 1,
 "status": "skipped",
 "reason": "kind-skipped"
 }
 ]
 }
}