kubernetes/api/openapi-spec/README.md

Kubernetes's OpenAPI Specification

This folder contains an OpenAPI specification for Kubernetes API.

Vendor Extensions

Kubernetes extends OpenAPI using these extensions. Note the version that extensions have been added.

x-kubernetes-group-version-kind

Operations and Definitions may have x-kubernetes-group-version-kind if they are associated with a kubernetes resource.

For example:

"paths": {
    ...
    "/api/v1/namespaces/{namespace}/pods/{name}": {
        ...
        "get": {
        ...
            "x-kubernetes-group-version-kind": {
            "group": "",
            "version": "v1",
            "kind": "Pod"
            }
        }
    }
}

x-kubernetes-action

Operations and Definitions may have x-kubernetes-action if they are associated with a kubernetes resource. Action can be one of get, list, put, patch, post, delete, deletecollection, watch, watchlist, proxy, or connect.

For example:

"paths": {
    ...
    "/api/v1/namespaces/{namespace}/pods/{name}": {
        ...
        "get": {
        ...
            "x-kubernetes-action": "list"
        }
    }
}

x-kubernetes-patch-strategy and x-kubernetes-patch-merge-key

Some of the definitions may have these extensions. For more information about PatchStrategy and PatchMergeKey see strategic-merge-patch.

x-kubernetes-list-type

Some definitions may have x-kubernetes-list-type.
This extension specifies how lists are merged when Kubernetes objects are combined (for example, during updates or patches).
Possible values are:

• "atomic" – treat the entire list as one unit; replacing the list replaces all elements.
• "set" – treat the list as a set; merge items based on equality.
• "map" – treat the list as a map; keys come from the field defined in x-kubernetes-list-map-keys.

For example:

{
  "x-kubernetes-list-type": "map",
  "x-kubernetes-list-map-keys": ["name"]
}

See Kubernetes API conventions (lists and maps) for more.

x-kubernetes-list-map-keys

This extension sets which field(s) identify elements uniquely for x-kubernetes-list-type: map. It allows merging list entries based on those key fields.

For example:

{
  "x-kubernetes-list-type": "map",
  "x-kubernetes-list-map-keys": ["name"]
}

Here, "name" acts as the key for each map entry. See API conventions – merge strategy for details.

x-kubernetes-map-type

Some definitions may have x-kubernetes-map-type. This extension describes how maps should merge: • "atomic" – replace entire map • "granular" – merge map entries individually

For example:

{
  "x-kubernetes-map-type": "granular"
}

See Kubernetes API conventions (maps section) for details.

x-kubernetes-unions

Some definitions may have x-kubernetes-unions. This extension describes mutually exclusive fields (union-like behavior). Only one field in that union can be set.

For example:

{
  "x-kubernetes-unions": [
    {
      "discriminator": "type",
      "fields": ["intValue", "stringValue"]
    }
  ]
}

This ensures only one of "intValue" or "stringValue" is specified based on the type discriminator. See Kubernetes API conventions (union types) for more.