From 7ce879d16f7dab7d79b9957e979316be3fdf9a93 Mon Sep 17 00:00:00 2001
From: Anthony Amador <55220361+AnthonySchool@users.noreply.github.com>
Date: Fri, 5 Dec 2025 23:37:35 -0800
Subject: [PATCH] Document x-kubernetes-list-map-keys into OpenAPI extensions

This PR adds missing OpenAPI vendor extension documentation for the following:
x-kubernetes-list-map-keys

The provided documentation includes simple additions to api/openapi-spec/README.md with similar format to present documentation.
Fixes issue #131724
---
 api/openapi-spec/README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/api/openapi-spec/README.md b/api/openapi-spec/README.md
index 3f7a1cdb9c2..fbba6ff0fa7 100644
--- a/api/openapi-spec/README.md
+++ b/api/openapi-spec/README.md
@@ -54,6 +54,34 @@ For example:
 }
 ```
 
+### `x-kubernetes-list-map-keys`
+
+Operations and Definitions may have `x-kubernetes-list-maps-keys` if they
+are associated with a [kubernetes resource](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources). `x-kubernetes-list-type` = `map` specifies field names inside each list element to serve as unique keys for the list-as-map.
+
+**For example:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "servers": {
+      "type": "array",
+      "x-kubernetes-list-type": "map",
+      "x-kubernetes-list-map-keys": ["name"],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "address": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    }
+  }
+}
+```
+
 ### `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