Kubernetes Object Schema Model

Kubernetes Object Schema Model is the formal, machine-readable description of a resource type's structure — its fields, their types, their constraints, and their relationships to one another — expressed using OpenAPI v3 conventions with Kubernetes-specific extensions, serving as the single source of truth that structural validation, defaulting, pruning, client code generation, and documentation tooling all derive their behavior from. Every object that exists in a Kubernetes cluster, whether an instance of a built-in type or a CustomResourceDefinition, is ultimately an instantiation of some registered schema, and it is that schema which determines what shape the object is allowed to take.

Schema Origin for Built-In Types

Generated From Go Type Definitions

For built-in resource types, the schema is not hand-authored separately from the implementation; it is generated directly from the Go struct definitions and their associated struct tags that make up the API server's internal type system, ensuring the schema served to clients always accurately reflects what the compiled server actually accepts and returns.

Struct Tags as Schema Metadata

Go struct tags on API type fields encode information such as JSON field names, whether a field is required or optional, and Kubernetes-specific patch merge behavior, and this metadata is what the schema generation tooling reads to produce the OpenAPI documents the discovery endpoints ultimately serve.

Structural Schemas for Custom Resources

The Structural Schema Requirement

CustomResourceDefinitions must declare a "structural" schema, meaning every field reachable from the schema's root must have its type explicitly specified (with limited, well-defined exceptions), a requirement introduced specifically because non-structural schemas made certain server-side features — including pruning, defaulting, and Server-Side Apply's field-level merging — impossible to implement reliably.

x-kubernetes Extensions

Because standard OpenAPI v3 alone cannot express every semantic Kubernetes schemas need, CRD schemas support a family of x-kubernetes-* extension keywords — such as x-kubernetes-preserve-unknown-fields, x-kubernetes-list-type, and x-kubernetes-int-or-string — that layer Kubernetes-specific merge, validation, and typing behavior on top of the base OpenAPI vocabulary.

List Merge Semantics in Schema

x-kubernetes-list-type

Declaring a list field's x-kubernetes-list-type as atomic, set, or map tells the API server how Server-Side Apply and strategic merge behavior should treat that list — whether it must always be replaced wholesale, treated as a set of unique scalar values, or merged element-by-element keyed on a specified field — directly determining whether concurrent applies from different field managers can safely modify different elements of the same list without conflict.

x-kubernetes-list-map-keys

When a list is declared as map type, x-kubernetes-list-map-keys specifies which field or fields within each list element serve as the merge key, mirroring for CRDs the same patchMergeKey capability that struct tags provide for built-in types, and making per-element merging possible for custom resource list fields.

Pruning and Unknown Field Handling

Default Pruning Behavior

By default, fields submitted in a request that are not described anywhere in the resource's structural schema are silently pruned before the object is persisted, preventing arbitrary undeclared data from accumulating in stored objects and ensuring the schema remains an accurate, complete description of what any given object can actually contain.

Opting Out With preserveUnknownFields

Setting x-kubernetes-preserve-unknown-fields: true on a schema node disables pruning for that portion of the object, allowing genuinely free-form data to be stored where a custom resource intentionally needs to accept arbitrary user-defined structure that cannot be fully described in advance.

Schema Versioning Across Served Versions

Per-Version Schemas for Custom Resources

A CustomResourceDefinition can declare a distinct schema for each version it serves, allowing a type's structure to evolve across versions in the same controlled way built-in types do, with the API server responsible for applying the correct version-specific schema during validation and for invoking conversion logic when translating an object between differently schemaed versions.