blog

12021-08-07

SEAN K.H. LIAO

JSON Schema

JSON Schema describes what your json data looks like. Current version is draft 2020-12/

Open API

Open API describes what your (rest) api looks like. Designed as an extension to json schema, the current version is 3.1.0 which importantly is finally 100% compatible with json schema (previous versions were less (80~90%) compatible, leading to implementation headaches).

note: previously it was called swagger, now swagger just refers to a set of surrounding tooling

kubernetes crds

Kubernetes custom resources are declared to the API server with apiextentions.k8s.io/v1 CustomResourceDefinition which describes how the API server should treat such resources and also a validation strategy within the openAPIV3Schema field. Confusingly, the description for the field says "OpenAPI v3 schema to use..." while the field contents say "JSON-Schema following Specification Draft 4".

Since CRDs don't really describe apis other than the definition of the object within the openAPIV3Schema field, it's probably best to think of it as open api 3.0.0 flavored json schema.

Most controllers that make use of CRDs appear to be using controller-gen, part of kubebuilder. This means the canonical format is Go structs, which is turned into a CRD definition directly and controlled via comments. Which is a bit unfortunate as the openapi/json schema is never generated, meaning tools such as yaml-language-server need some other source than upstream.

So i think you could just extract the contents of crds openAPIV3Schema from the customary yaml into json and call it a day. The API server also serves everything it know about, via /openapi/v2, and can be called with kubectl get --raw /openapi/v2. I also learned there is openapi2jsonschema...