CRDs-catalog turns popular Kubernetes operators into JSON schemas you can validate offline

Schema validation without a cluster

The premise of the repository is one sentence in the README: it aggregates hundreds of popular Kubernetes CRDs in JSON schema format, and those schemas can be used by tools such as Datree, Kubeconform and Kubeval as an alternative to `kubectl --dry-run` to validate custom and native resources.

That alternative is the point. A dry run against a live cluster tells you whether the API server would accept your manifest, which means CI needs cluster credentials, which means the check is slow, and which means a developer running the same check locally needs access to a cluster at all. Schema validation against a downloaded file needs nothing but the file. The README frames it as the shift-left approach, applied on machines without giving them access to your cluster, locally or on CI.

The second use is editor support. With the Red Hat YAML plugin for VS Code, a YAML document can carry a `$schema` property pointing at a validation schema, and the plugin then uses it for intellisense and validation. That turns the same catalogue into autocomplete for a custom resource kind the editor knows nothing about, which is a different kind of value from the CI check.

So the repository has two audiences. Teams that want a check in their pipeline, and developers who want their editor to understand a CRD before they push. The catalogue is the shared asset for both.

One directory per API group, one file per resource

The URL layout is what makes the catalogue consumable by tools that fetch schemas on demand, and the tree at the top of the repository shows it directly. There is a directory per API group, named for the group, and the entries run from `aadpodidentity.k8s.io/` through `accesscontextmanager.cnrm.cloud.google.com/`, `acid.zalan.do/`, `acm.services.k8s.aws/`, `actions.github.com/`, `argoproj.io/` and onward into the hundreds.

Inside each group directory the file naming follows a documented pattern, which the Kubeconform invocation spells out as a template with the group, the resource kind and the resource API version.

kubeconform -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' [MANIFEST]

The `default` location is the built-in schema set that Kubeconform ships for native Kubernetes resources, and the second location adds the catalogue for custom ones. The two are complementary rather than competing, which is why the catalogue is described as covering custom and native resources, and why the native kinds do not need to be duplicated here.

Kubeval is the third consumer, and the README is blunt about it. Under the kubeval heading it says only that it is supported with the CRD Extractor, meaning the bundled catalogue does not work with kubeval and the extractor is the only route there.

The pattern in the group directory names also tells you what the catalogue is not. It is organised by API group, so a resource that has no public CRD, such as one defined by an internal operator, has no place in it at all.

Running the check with Datree or Kubeconform

The usage section is short because the catalogue is data rather than a tool, and each validator has its own way of pointing at it.

For Datree, the manifest is passed to the test command.

datree test [MANIFEST]

For Kubeconform, the schema location template shown above is added to the default location, and the manifest is passed the same way.

kubeconform -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' [MANIFEST]

Both are network dependent, since the schemas are fetched from the raw GitHub URL. That is a practical point for CI, since a validation step that reaches out to the internet on every run is slower and less deterministic than one reading a vendored copy, and it is the reason the repository also carries the extractor.

For a person editing YAML, the same catalogue is used through the editor. The base URL for the schemas is the raw GitHub path, and a YAML document is annotated with a `$schema` property that the Red Hat YAML plugin picks up.

# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/cilium.io/ciliumnetworkpolicy_v2.json
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy

The README notes that a file with several resources can carry several annotations, one per document, since the annotation is per YAML document rather than per file.

There is also a helper for the tedious part. The `annotate-yaml.py` utility in the `Utilities` directory adds the `$schema` property to your YAML documents automatically based on the CRDs you are using, which turns the annotation step into a command instead of a copy and paste.

The CRD Extractor covers the resources the catalogue does not have

The repository carries a second utility for the case the catalogue cannot solve, and the README says so directly: if you encounter custom resources that are not part of the catalog, or you want to validate schemas in an air-gapped environment, use the CRD Extractor.

The utility does three things, according to the README. It checks that the prerequisites are installed, it extracts your CRDs from your cluster using kubectl, optionally from a specific Kubernetes context, and it converts those CRDs from OpenAPI to JSON schema using the `openapi2jsonschema.py` script from kubeconform.

The prerequisites are python3 and kubectl, and the utility supports MacOS and Linux. Alternatively, the README points at Nix or Devbox to set up the dependencies automatically.

The usage is a shell script in the `Utilities` directory.

cd Utilities
./crd-extractor.sh

A specific cluster is selected with the `KUBECTL_CONTEXT` environment variable, either inline.

cd Utilities
KUBECTL_CONTEXT=staging ./crd-extractor.sh

Or exported first.

export KUBECTL_CONTEXT=staging
cd Utilities
./crd-extractor.sh

If the variable is not set, the utility uses your default kubectl context. Devbox users run `devbox run crd-extractor`, and Nix users with flakes enabled run `nix develop` followed by the script.

This is the piece that makes the approach hold up. The catalogue covers public operators, the extractor covers everything your cluster actually has, including private APIs, and the output can be committed to your own repository so the validation becomes a local file check with no network dependency at all.

Contributing schemas, with an automatic merge policy

The contribution section tells you two ways in. You can open an issue if the catalogue is missing public custom resources you would like to validate automatically, or you can use the CRD Extractor to add schemas yourself and open a pull request.

The second path is the interesting one, because it turns contribution into a mechanical operation. You run the extractor against a cluster that has the operator installed, the output is a JSON schema, and the pull request adds it. The catalogue then grows without a maintainer having to hand-write a schema.

The README points at a contribution guide in `CONTRIBUTING.md` for human instructions, and it describes that guide as containing a copyable agent prompt and an automatic merge policy. The mention of an agent prompt says something about how the project expects contributions to be produced now, and an automatic merge policy means schemas that pass the project's checks can be merged without a maintainer reading every line. That is a sensible design for a catalogue of mechanical conversions, and it is also a policy worth reading before you assume a submitted schema will be reviewed for correctness of content.

There is a `CODEOWNERS` file at the top of the tree, which usually means some paths require a review from a named owner, and the tree also contains a `.krew.yaml` file, the manifest format for the kubectl plugin distribution mechanism, which suggests the extractor is packaged for installation as a kubectl plugin rather than only as a downloaded zip.

The licence is MIT, so the schemas and the utility can be reused and vendored into your own repository without restriction beyond attribution.

An active tree with release tags that stopped in 2023

The maintenance picture needs reading carefully, because the two signals disagree.

The repository is not archived, and the last push was on 2026-10-18, so the catalogue is being updated on an ongoing basis. The recent release history, though, stops in 2023: v0.0.12 on 2023-07-02, v0.0.11 on 2023-04-11 and v0.0.10 on 2022-10-18.

The releases in that history are the CRD Extractor artifacts, since the README tells you to download the latest release archive for the utility, and the catalogue itself is versioned by git rather than by a tag. A project that publishes a utility as a binary has to cut a release for it, and this project has not cut one since July 2023.

The practical consequence is that the extractor is the part to be careful with. The schema catalogue is plain files in the repository and is as current as the last push, but the packaged zip you are told to download is a 2023 build, and the shell script in `Utilities/` is the current version. Anyone who needs the extractor in a pipeline should run the script from a pinned commit rather than trusting the download link, and should check that the script still works against their kubectl and Python versions.

The other maintenance consideration is the schemas themselves. A schema is generated from a particular version of an operator's CRD, and the catalogue does not carry a per-file version marker that the README describes. If your cluster runs a newer controller than the schema reflects, the validation may flag fields you legitimately use, or accept fields the server would now reject. That is a real constraint of schema-first validation, and it is where a wrong result comes from.

Editorial conclusion

CRDs-catalog fits a platform team that validates manifests in CI and wants custom resources checked with the same tooling as built-in kinds, without standing up a cluster for a dry run. Skip it if your resources are private to your own API server, since the catalog only covers public CRDs, and read the schemas with care when the operator version behind a schema is not the one you run. Verify first that the schema file for your resource exists and matches your installed controller version, and use the CRD Extractor when it does not.

Frequently asked questions

Official sources

1. datreeio/CRDs-catalog on GitHub
2. Issues
3. License: MIT
4. README
5. Releases