5.23 Kubernetes Object Schema Model

Kubernetes Object Schema Model is the OpenAPI-based description language used to define the exact shape, types, and constraints of every field within a Kubernetes object, whether built-in or custom, including a set of Kubernetes-specific schema extensions that go beyond plain OpenAPI to express concepts like list-merging strategy, embedded resources, and preservation of unknown fields.

The Foundation: OpenAPI v3 Schema

Standard JSON Schema Constructs

Kubernetes object schemas are expressed using OpenAPI v3, itself built on JSON Schema concepts, supporting standard constructs such as type, properties, required, enum, minimum, maximum, pattern, and items for describing scalar values, objects, and arrays with familiar validation semantics.

Structural Requirements for Custom Resources

For Custom Resource Definitions specifically, a schema must be structural, meaning every field reachable in the schema has an explicit type, and any field permitting arbitrary nested content does so only through explicit, intentional schema constructs rather than by simply omitting type information, a requirement enforced by the API server to guarantee predictable pruning and validation behavior.

Kubernetes-Specific Schema Extensions

x-kubernetes-preserve-unknown-fields

This extension marks a specific point in the schema, often at an object's root or within a deliberately permissive nested field, as allowed to retain properties not explicitly described in the schema, opting out of the default pruning behavior for that portion of the object while the rest of the schema remains fully structural and enforced.

x-kubernetes-list-type and x-kubernetes-list-map-keys

These extensions describe how array fields should be treated during server-side apply merging: atomic lists are replaced wholesale on any change, set lists are treated as an unordered collection of unique scalar values, and map lists, combined with x-kubernetes-list-map-keys identifying a designated key field, are merged element-by-element much like strategic merge patch does for built-in types.

x-kubernetes-embedded-resource

This extension marks a field as itself containing a full, embedded Kubernetes object, complete with its own apiVersion and kind, instructing the API server to apply the embedded object's own schema-driven pruning and validation rather than treating the field as arbitrary opaque data.

x-kubernetes-int-or-string

Certain fields, such as container port fields that accept either a literal port number or a named port, are typed using this extension, signaling that the field can validly hold either an integer or a string value, a flexibility that standard JSON Schema typing alone cannot express cleanly.

Validation Rules Beyond Basic Types

CEL Validation Rules

Modern schema definitions support x-kubernetes-validations, allowing authors to embed Common Expression Language rules directly within the schema to express cross-field validation logic, such as ensuring one field's value is always less than another's, going beyond what static type and range constraints alone can enforce.

Default Values Within the Schema

As covered by the broader defaulting model, a default keyword can be specified at any level of the schema, and the API server applies these declared defaults automatically for any field a client leaves unset, integrating defaulting directly into the same schema definition used for validation.

Schema Versioning Considerations

Per-Version Schemas

A Custom Resource Definition can define a distinct schema for each served version of its kind, allowing the shape of a resource to evolve across versions while the API server handles conversion between them, though built-in resources typically maintain much tighter structural consistency across their supported versions due to stricter compatibility guarantees.

Schema and Conversion Interplay

When multiple versions each have their own schema, validation for a given request is performed against the schema of the specific version the client submitted, while the object's ultimately stored, converted representation must still satisfy the constraints implied by the resource's designated storage version schema.

Consuming the Schema

Client-Side Tooling

Beyond server-side validation, the published schema powers client-side experiences such as kubectl explain, editor auto-completion through IDE plugins, and generated typed client code, all of which rely on the schema as the authoritative description of what a valid object of a given kind looks like.

Documentation Generation

Because the schema includes description fields for types and individual properties, it also serves as a machine-readable source for automatically generated API reference documentation, keeping documentation synchronized with the actual enforced schema rather than requiring separately maintained, potentially drifting documentation.