Flux – Flux Schema

Flux: Flux Schema Config

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

The flux schema validate command 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:
 - default
 - https://raw.githubusercontent.com/datreeio/CRDs-catalog/main
 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

Usage:

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

When --config is not set, the FLUX_SCHEMA_CONFIG environment variable is used. When neither is set, Flux Schema looks for a config file at the executable path plus .config, 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.

Validation

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

Field	Description
`schemaLocation[]`	Schema URLs, file paths, or templates tried in order.
`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.

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
`--schema-location`	URL or file path for schemas (repeatable, tried in order); `default` points at the built-in 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 https://raw.githubusercontent.com/datreeio/CRDs-catalog/main \
 --schema-location './schemas/{{.Kind}}-{{.GroupPrefix}}-{{.Version}}.json'

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.
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. 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
 - https://raw.githubusercontent.com/datreeio/CRDs-catalog/main
 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: 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.

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`).
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.

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`).
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.

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`).
`--strip-description`	Drop `description` fields from the generated schemas to reduce their size.

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

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: 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"
 }
 ]
 }
}