From 3eaa8e427c95e9eb8afb03de713b45d637a92f20 Mon Sep 17 00:00:00 2001
From: Ilya Grigorik <ilya@grigorik.com>
Date: Fri, 10 Apr 2026 14:00:51 -0700
Subject: [PATCH] =?UTF-8?q?rename=20variant.selected=5Foptions=20=E2=86=92?=
 =?UTF-8?q?=20options?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

  Completes a rename decided in PR #195 (get_product operation) but never
  executed on variant.json. The get_product operation introduced three
  distinct concepts that were previously conflated:

    request.selected  — what the user chose (input parameter)
    product.selected  — what the server resolved (response, post-relaxation)
    variant.options   — what the variant IS (intrinsic, immutable)

  A variant's option values (Color: Blue, Size: Large) are intrinsic
  identity — they don't change based on user selections or server
  relaxation. The old name "selected_options" implied a relationship to
  user selection state that doesn't exist at the variant level.

  Schema: variant.selected_options → variant.options
  Docs: update variant examples in mcp.md and rest.md
---
 docs/specification/catalog/mcp.md          | 6 +++---
 docs/specification/catalog/rest.md         | 6 +++---
 source/schemas/shopping/types/variant.json | 4 ++--
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/specification/catalog/mcp.md b/docs/specification/catalog/mcp.md
index 516b9bbbd..3fa331709 100644
--- a/docs/specification/catalog/mcp.md
+++ b/docs/specification/catalog/mcp.md
@@ -214,7 +214,7 @@ Maps to the [Catalog Search](search.md) capability.
                   "description": { "plain": "Size 10 variant" },
                   "price": { "amount": 12000, "currency": "USD" },
                   "availability": { "available": true },
-                  "selected_options": [
+                  "options": [
                     { "name": "Size", "label": "10" }
                   ],
                   "tags": ["running", "road", "neutral"],
@@ -554,7 +554,7 @@ Maps to the [Catalog Lookup](lookup.md#get-product-get_product) capability. Retu
                 "description": { "plain": "Blue, Size 10" },
                 "price": { "amount": 12000, "currency": "USD" },
                 "availability": { "available": true },
-                "selected_options": [
+                "options": [
                   { "name": "Color", "label": "Blue" },
                   { "name": "Size", "label": "10" }
                 ]
@@ -566,7 +566,7 @@ Maps to the [Catalog Lookup](lookup.md#get-product-get_product) capability. Retu
                 "description": { "plain": "Blue, Size 12" },
                 "price": { "amount": 15000, "currency": "USD" },
                 "availability": { "available": true },
-                "selected_options": [
+                "options": [
                   { "name": "Color", "label": "Blue" },
                   { "name": "Size", "label": "12" }
                 ]
diff --git a/docs/specification/catalog/rest.md b/docs/specification/catalog/rest.md
index 192515125..84c792897 100644
--- a/docs/specification/catalog/rest.md
+++ b/docs/specification/catalog/rest.md
@@ -152,7 +152,7 @@ Maps to the [Catalog Search](search.md) capability.
               "description": { "plain": "Size 10 variant" },
               "price": { "amount": 12000, "currency": "USD" },
               "availability": { "available": true },
-              "selected_options": [
+              "options": [
                 { "name": "Size", "label": "10" }
               ],
               "tags": ["running", "road", "neutral"],
@@ -428,7 +428,7 @@ on option values and returns variants matching the selection.
             "description": { "plain": "Blue, Size 10" },
             "price": { "amount": 12000, "currency": "USD" },
             "availability": { "available": true },
-            "selected_options": [
+            "options": [
               { "name": "Color", "label": "Blue" },
               { "name": "Size", "label": "10" }
             ]
@@ -440,7 +440,7 @@ on option values and returns variants matching the selection.
             "description": { "plain": "Blue, Size 12" },
             "price": { "amount": 15000, "currency": "USD" },
             "availability": { "available": true },
-            "selected_options": [
+            "options": [
               { "name": "Color", "label": "Blue" },
               { "name": "Size", "label": "12" }
             ]
diff --git a/source/schemas/shopping/types/variant.json b/source/schemas/shopping/types/variant.json
index bcbf753dd..267355394 100644
--- a/source/schemas/shopping/types/variant.json
+++ b/source/schemas/shopping/types/variant.json
@@ -117,12 +117,12 @@
         }
       }
     },
-    "selected_options": {
+    "options": {
       "type": "array",
       "items": {
         "$ref": "selected_option.json"
       },
-      "description": "Option selections that define this variant."
+      "description": "Option values that define this variant (e.g., Color: Blue, Size: Large)."
     },
     "media": {
       "type": "array",