@adobe/design-data-spec 0.15.0 → 1.0.0

package/components/text-field.json

@@ -16,7 +16,14 @@
     "labelPosition": {
       "type": "string",
       "default": "top",
-      "enum": ["top", "side"]
+      "values": [
+        {
+          "value": "top"
+        },
+        {
+          "value": "side"
+        }
+      ]
     },
     "hideLabel": {
       "type": "boolean",
@@ -31,13 +38,33 @@
     },
     "size": {
       "type": "string",
-      "enum": ["s", "m", "l", "xl"],
-      "default": "m"
+      "default": "m",
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
+      ]
     },
     "necessityIndicator": {
       "type": "string",
-      "enum": ["text", "icon"],
-      "default": "icon"
+      "default": "icon",
+      "values": [
+        {
+          "value": "text"
+        },
+        {
+          "value": "icon"
+        }
+      ]
     },
     "isRequired": {
       "type": "boolean",

package/components/thumbnail.json

@@ -12,7 +12,44 @@
   "options": {
     "size": {
       "type": "number",
-      "enum": [50, 75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000]
+      "values": [
+        {
+          "value": 50
+        },
+        {
+          "value": 75
+        },
+        {
+          "value": 100
+        },
+        {
+          "value": 200
+        },
+        {
+          "value": 300
+        },
+        {
+          "value": 400
+        },
+        {
+          "value": 500
+        },
+        {
+          "value": 600
+        },
+        {
+          "value": 700
+        },
+        {
+          "value": 800
+        },
+        {
+          "value": 900
+        },
+        {
+          "value": 1000
+        }
+      ]
     }
   },
   "states": [

package/components/title.json

@@ -18,8 +18,30 @@
     },
     "size": {
       "type": "string",
-      "enum": ["xs", "s", "m", "l", "xl", "xxl", "xxxl"],
-      "default": "m"
+      "default": "m",
+      "values": [
+        {
+          "value": "xs"
+        },
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        },
+        {
+          "value": "xxl"
+        },
+        {
+          "value": "xxxl"
+        }
+      ]
     }
   },
   "lifecycle": {

package/components/toast.json

@@ -15,8 +15,21 @@
     },
     "variant": {
       "type": "string",
-      "enum": ["neutral", "informative", "positive", "negative"],
-      "default": "neutral"
+      "default": "neutral",
+      "values": [
+        {
+          "value": "neutral"
+        },
+        {
+          "value": "informative"
+        },
+        {
+          "value": "positive"
+        },
+        {
+          "value": "negative"
+        }
+      ]
     },
     "actionLabel": {
       "type": "string",

package/components/tooltip.json

@@ -15,8 +15,18 @@
     },
     "variant": {
       "type": "string",
-      "enum": ["neutral", "informative", "negative"],
-      "default": "neutral"
+      "default": "neutral",
+      "values": [
+        {
+          "value": "neutral"
+        },
+        {
+          "value": "informative"
+        },
+        {
+          "value": "negative"
+        }
+      ]
     },
     "hasIcon": {
       "type": "boolean",
@@ -30,8 +40,21 @@
     },
     "placement": {
       "type": "string",
-      "enum": ["top", "bottom", "left", "right"],
-      "default": "top"
+      "default": "top",
+      "values": [
+        {
+          "value": "top"
+        },
+        {
+          "value": "bottom"
+        },
+        {
+          "value": "left"
+        },
+        {
+          "value": "right"
+        }
+      ]
     },
     "shouldFlip": {
       "type": "boolean",

package/components/tree-view.json

@@ -12,8 +12,21 @@
   "options": {
     "size": {
       "type": "string",
-      "enum": ["s", "m", "l", "xl"],
-      "default": "m"
+      "default": "m",
+      "values": [
+        {
+          "value": "s"
+        },
+        {
+          "value": "m"
+        },
+        {
+          "value": "l"
+        },
+        {
+          "value": "xl"
+        }
+      ]
     },
     "isDetached": {
       "type": "boolean",
@@ -29,18 +42,39 @@
     },
     "selectionMode": {
       "type": "string",
-      "enum": ["single", "multiple"],
-      "default": "multiple"
+      "default": "multiple",
+      "values": [
+        {
+          "value": "single"
+        },
+        {
+          "value": "multiple"
+        }
+      ]
     },
     "selectionStyle": {
       "type": "string",
-      "enum": ["checkbox", "highlight"],
-      "default": "checkbox"
+      "default": "checkbox",
+      "values": [
+        {
+          "value": "checkbox"
+        },
+        {
+          "value": "highlight"
+        }
+      ]
     },
     "selectionBehavior": {
       "type": "string",
-      "enum": ["toggle", "replace"],
-      "default": "toggle"
+      "default": "toggle",
+      "values": [
+        {
+          "value": "toggle"
+        },
+        {
+          "value": "replace"
+        }
+      ]
     }
   },
   "states": [

package/conformance/invalid/SPEC-019/dataset.json

@@ -21,7 +21,20 @@
       "options": {
         "variant": {
           "type": "string",
-          "enum": ["accent", "negative", "primary", "secondary"]
+          "values": [
+            {
+              "value": "accent"
+            },
+            {
+              "value": "negative"
+            },
+            {
+              "value": "primary"
+            },
+            {
+              "value": "secondary"
+            }
+          ]
         }
       }
     }

package/conformance/invalid/SPEC-037/dataset.json

@@ -64,13 +64,21 @@
       "options": {
         "variant": {
           "type": "string",
-          "enum": ["primary", "secondary", "cta"],
-          "deprecatedEnumValues": {
-            "cta": {
-              "deprecated": "1.0.0-draft",
-              "deprecatedComment": "Use primary instead."
+          "values": [
+            {
+              "value": "primary"
+            },
+            {
+              "value": "secondary"
+            },
+            {
+              "value": "cta",
+              "lifecycle": {
+                "deprecated": "1.0.0-draft",
+                "deprecatedComment": "Use primary instead."
+              }
             }
-          }
+          ]
         }
       }
     }

package/conformance/invalid/SPEC-038/dataset.json

@@ -0,0 +1,20 @@
+{
+  "tokens": {},
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/badge.json",
+      "name": "badge",
+      "displayName": "Badge",
+      "meta": {
+        "category": "status",
+        "documentationUrl": "https://spectrum.adobe.com/page/badge/"
+      },
+      "options": {
+        "variant": {
+          "type": "string",
+          "enum": ["neutral", "informative", "positive", "negative"]
+        }
+      }
+    }
+  ]
+}

package/conformance/invalid/SPEC-038/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-038",
+      "severity": "warning",
+      "message_pattern": ".*obsolete.*enum.*"
+    }
+  ]
+}

package/conformance/valid/SPEC-037/dataset.json

@@ -62,7 +62,9 @@
         "documentationUrl": "https://spectrum.adobe.com/page/slider/"
       },
       "anatomy": [
-        { "name": "track" },
+        {
+          "name": "track"
+        },
         {
           "name": "handle",
           "lifecycle": {
@@ -81,7 +83,9 @@
         "documentationUrl": "https://spectrum.adobe.com/page/button/"
       },
       "states": [
-        { "name": "hover" },
+        {
+          "name": "hover"
+        },
         {
           "name": "pressed",
           "lifecycle": {
@@ -93,13 +97,21 @@
       "options": {
         "variant": {
           "type": "string",
-          "enum": ["primary", "secondary", "cta"],
-          "deprecatedEnumValues": {
-            "cta": {
-              "deprecated": "1.0.0-draft",
-              "deprecatedComment": "Use primary instead."
+          "values": [
+            {
+              "value": "primary"
+            },
+            {
+              "value": "secondary"
+            },
+            {
+              "value": "cta",
+              "lifecycle": {
+                "deprecated": "1.0.0-draft",
+                "deprecatedComment": "Use primary instead."
+              }
             }
-          }
+          ]
         }
       }
     }

package/conformance/valid/SPEC-038/dataset.json

@@ -0,0 +1,29 @@
+{
+  "tokens": {},
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": {
+        "category": "actions",
+        "documentationUrl": "https://spectrum.adobe.com/page/button/"
+      },
+      "options": {
+        "variant": {
+          "type": "string",
+          "values": [
+            { "value": "primary" },
+            { "value": "secondary" },
+            { "value": "accent" }
+          ],
+          "default": "accent"
+        },
+        "isDisabled": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    }
+  ]
+}

package/conformance/valid/component-refs/dataset.json

@@ -37,26 +37,60 @@
       "options": {
         "variant": {
           "type": "string",
-          "enum": ["accent", "negative", "primary", "secondary"]
+          "values": [
+            {
+              "value": "accent"
+            },
+            {
+              "value": "negative"
+            },
+            {
+              "value": "primary"
+            },
+            {
+              "value": "secondary"
+            }
+          ]
         }
       },
       "slots": [
-        { "name": "default", "description": "Text label of the button." },
-        { "name": "icon", "description": "Leading icon." }
+        {
+          "name": "default",
+          "description": "Text label of the button."
+        },
+        {
+          "name": "icon",
+          "description": "Leading icon."
+        }
       ],
       "anatomy": [
-        { "name": "icon", "description": "Leading icon." },
-        { "name": "label", "description": "Button text.", "required": true }
+        {
+          "name": "icon",
+          "description": "Leading icon."
+        },
+        {
+          "name": "label",
+          "description": "Button text.",
+          "required": true
+        }
       ],
       "states": [
-        { "name": "hover", "trigger": "interaction", "precedence": 50 },
+        {
+          "name": "hover",
+          "trigger": "interaction",
+          "precedence": 50
+        },
         {
           "name": "focus",
           "trigger": "interaction",
           "precedence": 60,
           "layered": true
         },
-        { "name": "disabled", "trigger": "prop", "precedence": 100 }
+        {
+          "name": "disabled",
+          "trigger": "prop",
+          "precedence": 100
+        }
       ]
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "0.15.0",
+  "version": "1.0.0",
   "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
   "type": "module",
   "repository": {

package/rules/rules.yaml

@@ -168,7 +168,7 @@ rules:
     name: component-variant-valid
     severity: error
     category: reference-integrity
-    assert: Token name-object 'variant' field value MUST match a value in the declared 'variant' option enum for the referenced component, when that enum exists.
+    assert: Token name-object 'variant' field value MUST match a value in the declared 'variant' option `values` list for the referenced component, when that list exists.
     message: "Token '{token}' has variant '{variant}' which is not declared on component '{component}'"
     spec_ref: spec/component-format.md#options
     introduced_in: "1.0.0-draft"
@@ -362,11 +362,24 @@ rules:
     category: reference-integrity
     assert: >
       Tokens SHOULD NOT reference a deprecated anatomy part, deprecated component state, or
-      deprecated option-enum value via their `name` object unless the token is itself deprecated.
+      deprecated option value via their `name` object unless the token is itself deprecated.
       Non-deprecated tokens referencing deprecated sub-entities are surfaced as warnings to
       prompt authors to update the reference or mark the token deprecated.
-      Requires `lifecycle.deprecated` on anatomy parts and states, and `deprecatedEnumValues`
-      on option descriptors (introduced in this version of the schema).
+      Deprecation is declared via `lifecycle.deprecated` on anatomy parts, states, and individual
+      option values within the `values` array on option descriptors.
     message: "Token '{token}' references deprecated {kind} '{value}' on component '{component}' (deprecated since {version}); update the reference or mark the token deprecated"
     spec_ref: spec/component-format.md#lifecycle
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-038
+    name: option-enum-obsolete
+    severity: warning
+    category: component-contract
+    assert: >
+      Option descriptors SHOULD NOT use the JSON Schema `enum` keyword. The `enum` field is
+      silently accepted at Layer 1 (optionDescriptor uses additionalProperties: true) but has
+      no effect on SDK rules or lifecycle cascade. Use `values` instead so per-value lifecycle
+      metadata can be attached to individual values.
+    message: "Component '{component}' option '{option}' uses the obsolete `enum` keyword; replace with a `values` array so per-value lifecycle metadata can be expressed"
+    spec_ref: spec/component-format.md#option-descriptor
+    introduced_in: "1.0.0-draft"

package/schemas/component.schema.json

@@ -108,7 +108,8 @@
     },
     "optionDescriptor": {
       "type": "object",
-      "description": "JSON Schema-compatible descriptor for a single component option. Standard JSON Schema keywords (type, enum, default, description, pattern, minimum, maximum, items, properties, etc.) are all permitted.",
+      "description": "Descriptor for a single component option. The `type` keyword follows JSON Schema conventions. Use `values` (not `enum`) to declare permitted values — the structured array allows per-value lifecycle metadata. Other JSON Schema keywords (default, description, pattern, minimum, maximum, items, properties, $ref) are permitted as needed.",
+      "$comment": "additionalProperties: true is required to allow JSON Schema passthrough keywords (pattern, minimum, etc.). This means the legacy `enum` keyword is silently accepted at Layer 1; SPEC-038 closes the gap at Layer 2 by warning when `enum` is present.",
       "properties": {
         "type": {
           "oneOf": [
@@ -142,10 +143,12 @@
             }
           ]
         },
-        "enum": {
+        "values": {
           "type": "array",
           "minItems": 1,
-          "description": "Exhaustive list of permitted values."
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/optionValue" },
+          "description": "Exhaustive list of permitted values for this option, each with optional per-value metadata. Use this instead of the JSON Schema `enum` keyword so that lifecycle annotations can be attached to individual values. Consumed by SPEC-019 (variant validation) and SPEC-037 (deprecation cascade)."
         },
         "default": {
           "description": "Default value when the option is not specified."
@@ -158,18 +161,29 @@
           "type": "string",
           "format": "uri-reference",
           "description": "Reference to a shared type schema."
-        },
-        "deprecatedEnumValues": {
-          "type": "object",
-          "description": "Per-enum-value lifecycle metadata keyed by enum value string. Values absent from this map are not deprecated. Consumed by SPEC-037.",
-          "$comment": "Keys are not validated against sibling 'enum' — JSON Schema cannot cross-reference sibling values without unevaluatedProperties. Entries for values absent from 'enum' are silently ignored by validators. A future SPEC rule may close this gap.",
-          "additionalProperties": {
-            "$ref": "#/$defs/lifecycle"
-          }
         }
       },
       "additionalProperties": true
     },
+    "optionValue": {
+      "type": "object",
+      "required": ["value"],
+      "description": "A single permitted value for a component option, with optional per-value metadata.",
+      "properties": {
+        "value": {
+          "description": "The permitted option value. Typically a string; the schema does not constrain the type so booleans and numbers remain expressible."
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain-text description of what this value means."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle",
+          "description": "Version lifecycle metadata for this value. Set lifecycle.deprecated to signal that tokens referencing this value should migrate (SPEC-037)."
+        }
+      },
+      "additionalProperties": false
+    },
     "slotDeclaration": {
       "type": "object",
       "required": ["name"],

package/spec/agent-surface.md

@@ -96,7 +96,7 @@ The `describe_component` tool returns the component declaration object as stored
   "displayName": "Button",
   "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
   "options": {
-    "variant": { "type": "string", "enum": ["accent", "negative", "primary", "secondary"], "default": "accent" }
+    "variant": { "type": "string", "values": [{"value": "accent"}, {"value": "negative"}, {"value": "primary"}, {"value": "secondary"}], "default": "accent" }
   },
   "anatomy": [
     { "name": "icon",  "description": "Leading icon." },