@adobe/design-data-spec 3.1.0 → 3.2.0

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

@@ -4,7 +4,7 @@
       "name": { "property": "accent-color" },
       "value": "#0d66d0",
       "uuid": "aaaaaaaa-0014-4000-8000-000000000001",
-      "introduced": "1.0.0",
+      "lifecycle": { "introduced": "1.0.0" },
       "lastModified": "1.2.0"
     }
   ],

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

@@ -13,7 +13,7 @@
         "property": "color"
       },
       "value": "#000000",
-      "deprecated": "1.0.0-draft"
+      "lifecycle": { "deprecatedIn": "1.0.0-draft" }
     }
   ],
   "components": [
@@ -35,7 +35,7 @@
         "documentationUrl": "https://spectrum.adobe.com/page/old-widget/"
       },
       "lifecycle": {
-        "deprecated": "1.0.0-draft",
+        "deprecatedIn": "1.0.0-draft",
         "deprecatedComment": "Superseded by new-widget."
       }
     }

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

@@ -15,7 +15,7 @@
         "property": "background-color"
       },
       "value": "#0265dc",
-      "deprecated": "1.0.0-draft"
+      "lifecycle": { "deprecatedIn": "1.0.0-draft" }
     },
     {
       "name": {
@@ -32,7 +32,7 @@
         "property": "background-color"
       },
       "value": "#cccccc",
-      "deprecated": "1.0.0-draft"
+      "lifecycle": { "deprecatedIn": "1.0.0-draft" }
     },
     {
       "name": {
@@ -49,7 +49,7 @@
         "property": "background-color"
       },
       "value": "#0265dc",
-      "deprecated": "1.0.0-draft"
+      "lifecycle": { "deprecatedIn": "1.0.0-draft" }
     }
   ],
   "components": [
@@ -68,7 +68,7 @@
         {
           "name": "handle",
           "lifecycle": {
-            "deprecated": "1.0.0-draft",
+            "deprecatedIn": "1.0.0-draft",
             "deprecatedComment": "Renamed to thumb."
           }
         }
@@ -89,7 +89,7 @@
         {
           "name": "pressed",
           "lifecycle": {
-            "deprecated": "1.0.0-draft",
+            "deprecatedIn": "1.0.0-draft",
             "deprecatedComment": "Use active instead."
           }
         }
@@ -107,7 +107,7 @@
             {
               "value": "cta",
               "lifecycle": {
-                "deprecated": "1.0.0-draft",
+                "deprecatedIn": "1.0.0-draft",
                 "deprecatedComment": "Use primary instead."
               }
             }

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

@@ -0,0 +1,42 @@
+{
+  "relationships": [
+    {
+      "scope": {
+        "component": "button",
+        "part": "label",
+        "property": "background-color",
+        "options": { "style": "fill", "state": ["hover"] }
+      },
+      "value": "#ff0000",
+      "uuid": "33333333-3333-3333-3333-333333333333",
+      "legacyKey": "button-label-background-color-fill-hover"
+    },
+    {
+      "scope": { "component": "button", "property": "border-color" },
+      "context": "informative border color",
+      "$ref": "33333333-3333-3333-3333-333333333333"
+    }
+  ],
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": { "category": "actions" },
+      "anatomy": [
+        { "name": "icon", "description": "Leading icon." },
+        { "name": "label", "description": "Button text.", "required": true }
+      ],
+      "options": {
+        "style": {
+          "type": "enum",
+          "values": [{ "value": "fill" }, { "value": "outline" }]
+        }
+      },
+      "states": [
+        { "name": "hover", "trigger": "interaction", "precedence": 50 },
+        { "name": "disabled", "trigger": "prop", "precedence": 100 }
+      ]
+    }
+  ]
+}

package/conformance/valid/lifecycle-with-last-modified.json

@@ -7,6 +7,6 @@
   },
   "value": "#0265dc",
   "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
-  "introduced": "1.0.0",
+  "lifecycle": { "introduced": "1.0.0" },
   "lastModified": "2.1.0"
 }

package/package.json

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

package/rules/rules.yaml

@@ -96,7 +96,7 @@ rules:
     name: replaced-by-array-requires-comment
     severity: error
     category: completeness
-    assert: When replaced_by is an array, deprecated_comment MUST be present to explain which replacement applies in which context.
+    assert: When replaced_by is an array, deprecated_comment MUST be present to explain which replacement applies in which scope.
     message: "replaced_by is an array but deprecated_comment is missing on token {token}"
     spec_ref: spec/token-format.md#lifecycle-and-metadata
     introduced_in: "1.0.0-draft"
@@ -322,7 +322,7 @@ rules:
     assert: >
       A validator MUST NOT flag a registry ID as invalid solely because that same ID appears in
       a different registry. Registry IDs are scoped to their registry; cross-registry overlap is
-      intentional when the same word is a valid term in each registry's distinct validation context.
+      intentional when the same word is a valid term in each registry's distinct validation scope.
     message: "Registry ID '{id}' appears in multiple registries — this is permitted; do not reject on cross-registry overlap alone"
     spec_ref: spec/registry.md#id-scoping
     introduced_in: "1.0.0-draft"
@@ -594,3 +594,99 @@ rules:
     message: "Token '{token}' fuses '{field}' concept '{value}' into name.property; decompose into the structured field"
     spec_ref: spec/token-format.md#name-object
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-051
+    name: ctr-component-exists
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      A Component/Token Relationship (CTR)'s `scope.component` value MUST match the
+      `name` of a declared component in the dataset. Mirrors SPEC-018
+      (component-name-exists) for the CTR scope object.
+    message: "Relationship '{relationship}' references undeclared component '{component}'"
+    spec_ref: spec/relationship-format.md#scope-fields
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-052
+    name: ctr-part-valid
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      A CTR's `scope.part` value, when present, MUST match the `name` of a declared
+      anatomy part on the referenced component. Mirrors SPEC-020
+      (component-anatomy-valid) for the CTR scope object.
+    message: "Relationship '{relationship}' references undeclared anatomy part '{part}' on component '{component}'"
+    spec_ref: spec/relationship-format.md#scope-fields
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-053
+    name: ctr-option-valid
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      A CTR's `scope.options.<key>` value MUST match a value in the declared
+      `options.<key>.values` list for the referenced component, when that list exists.
+      Combines the intent of SPEC-019 (component-variant-valid, error) and SPEC-040
+      (component-option-field-valid, warning) into a single error-severity rule for
+      CTRs, since a CTR's options are the whole of its scope rather than one field
+      among many name-object keys.
+    message: "Relationship '{relationship}' has {key} '{value}' which is not declared on component '{component}'"
+    spec_ref: spec/relationship-format.md#scope-fields
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-054
+    name: ctr-state-valid
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      Each element of a CTR's `scope.options.state` array MUST match the `name` of a
+      declared state on the referenced component, when state declarations are present.
+      Mirrors SPEC-022 (component-state-valid) for the CTR scope object.
+    message: "Relationship '{relationship}' references undeclared state '{state}' on component '{component}'"
+    spec_ref: spec/relationship-format.md#scope-fields
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-055
+    name: ctr-ref-resolves
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      A CTR's `$ref` value MUST resolve to a declared token or relationship `uuid` in
+      the dataset. Mirrors SPEC-001 (alias-target-exists) and SPEC-027
+      (token-binding-token-exists) for the CTR alias direction.
+    message: "Relationship alias target not found for $ref: {target}"
+    spec_ref: spec/relationship-format.md#value-owning-vs-relationship-only
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-056
+    name: ctr-uuid-unique
+    severity: error
+    layer: 2
+    category: reference-integrity
+    assert: >
+      CTR `uuid` values MUST be unique across all relationship entries within the same
+      cascade layer. Mirrors SPEC-004 (uuid-global-uniqueness) for relationships.
+    message: "Duplicate relationship uuid {uuid}"
+    spec_ref: spec/relationship-format.md#identity
+    introduced_in: "1.0.0-draft"
+
+  - id: SPEC-057
+    name: ctr-legacykey-present-if-legacy
+    severity: warning
+    layer: 2
+    category: naming-consistency
+    note: >
+      Advisory placeholder. Detecting "this CTR should have a legacy counterpart" is a
+      generator-side determination deferred to the legacy-migration phase; this rule
+      documents intent rather than enforcing it structurally.
+    assert: >
+      A CTR that round-trips through the legacy generator (packages/tokens/src) SHOULD
+      carry `legacyKey`. Not structurally enforced in this foundation.
+    message: "Relationship '{relationship}' may need a legacyKey to round-trip through the legacy generator"
+    spec_ref: spec/relationship-format.md#legacy-fields-interim
+    introduced_in: "1.0.0-draft"

package/schemas/component.schema.json

@@ -179,7 +179,7 @@
         },
         "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)."
+          "description": "Version lifecycle metadata for this value. Set lifecycle.deprecatedIn to signal that tokens referencing this value should migrate (SPEC-037)."
         }
       },
       "additionalProperties": false
@@ -234,7 +234,7 @@
         },
         "lifecycle": {
           "$ref": "#/$defs/lifecycle",
-          "description": "Version lifecycle metadata for this anatomy part. Set lifecycle.deprecated to signal that tokens referencing this part should migrate."
+          "description": "Version lifecycle metadata for this anatomy part. Set lifecycle.deprecatedIn to signal that tokens referencing this part should migrate."
         }
       },
       "additionalProperties": false
@@ -284,7 +284,7 @@
         },
         "lifecycle": {
           "$ref": "#/$defs/lifecycle",
-          "description": "Version lifecycle metadata for this state. Set lifecycle.deprecated to signal that tokens referencing this state should migrate."
+          "description": "Version lifecycle metadata for this state. Set lifecycle.deprecatedIn to signal that tokens referencing this state should migrate."
         }
       },
       "additionalProperties": false
@@ -314,7 +314,7 @@
           "type": "string",
           "description": "Spec version when this component declaration was added (e.g. '1.0.0-draft')."
         },
-        "deprecated": {
+        "deprecatedIn": {
           "type": "string",
           "description": "Spec version when this component was deprecated. Truthy = deprecated."
         },

package/schemas/relationship.schema.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/relationship.schema.json",
+  "title": "Component/Token Relationship (CTR) file",
+  "description": "Layer 1 — structural shape of a relationships/*.json file: a JSON array of Component/Token Relationship (CTR) entries. Graph rules (option-value validity, component/part/state existence, $ref resolution) are Layer 2. See spec/relationship-format.md.",
+  "type": "array",
+  "items": {
+    "$ref": "#/$defs/relationship"
+  },
+  "$defs": {
+    "lifecycle": {
+      "type": "object",
+      "description": "Version lifecycle metadata, mirroring the token/component lifecycle pattern (see token.schema.json).",
+      "properties": {
+        "introduced": {
+          "type": "string",
+          "description": "Spec version when this relationship was added (e.g. \"1.0.0-draft\")."
+        },
+        "deprecatedIn": {
+          "type": "string",
+          "description": "Spec version when the relationship was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
+        },
+        "deprecatedComment": {
+          "type": "string",
+          "description": "Human-readable deprecation explanation and migration guidance."
+        },
+        "replacedBy": {
+          "oneOf": [
+            { "type": "string", "format": "uuid" },
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
+          ],
+          "description": "UUID(s) of the replacement relationship(s). Array form requires deprecatedComment."
+        },
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when the relationship will be removed."
+        }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "type": "object",
+      "description": "Explicit relationship context: which component, part, and property this CTR describes, plus any option-scoped narrowing. Layer 1 only enforces shape here — that `component.<part>` exists, that `options.<key>` values validate against the referenced component's declared option values, and that `property` matches a registered property term are Layer 2 rules (see spec/relationship-format.md).",
+      "required": ["component", "property"],
+      "properties": {
+        "component": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Component name (kebab-case). MUST match a declared component name (SPEC-051)."
+        },
+        "part": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Anatomy part name within the component. MUST match a declared anatomy part when present (SPEC-052)."
+        },
+        "property": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The stylistic attribute this relationship describes (e.g. color, width, padding)."
+        },
+        "options": {
+          "type": "object",
+          "description": "Option-scoped narrowing (e.g. variant, size, style, arbitrary component option keys). Each key's value MUST validate against the referenced component's options.<key>.values (SPEC-053), except `state`, which is an ordered array of atomic state ids validated against the component's declared states (SPEC-054).",
+          "properties": {
+            "state": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]*$"
+              },
+              "minItems": 1,
+              "description": "Ordered array of atomic state ids (e.g. [\"hover\"], [\"selected\", \"hover\"])."
+            }
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ctrWithValue": {
+      "type": "object",
+      "required": ["scope", "value"],
+      "not": {
+        "required": ["$ref"]
+      },
+      "dependentRequired": {
+        "setUuid": ["legacyKey"],
+        "setSchema": ["legacyKey"]
+      },
+      "properties": {
+        "specVersion": {
+          "const": "1.0.0-draft"
+        },
+        "scope": {
+          "$ref": "#/$defs/scope"
+        },
+        "context": {
+          "type": "string",
+          "description": "Human-readable label for how this CTR is used (mirrors tokenBindings[].context; maps to a Figma Token Group label). Purely descriptive — not validated."
+        },
+        "$valueType": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "URI reference to a value-type schema under schemas/value-types/. When present, value MUST validate against the referenced schema."
+        },
+        "value": {
+          "description": "Literal value owned by this CTR; type narrowed by value-type schemas where applicable.",
+          "anyOf": [
+            { "$ref": "value-types/color.schema.json" },
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" },
+            { "type": "object" },
+            { "type": "array" }
+          ]
+        },
+        "uuid": {
+          "type": "string",
+          "format": "uuid",
+          "description": "MUST be globally unique across all relationship entries in the same layer (SPEC-056)."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle"
+        },
+        "private": {
+          "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the relationship's purpose."
+        },
+        "legacyKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interim/transitional: pins the exact flat key written to legacy output (packages/tokens/src) for CTRs that must round-trip through the legacy generator. Not required for CTRs with no legacy counterpart. See spec/relationship-format.md#legacy-fields."
+        },
+        "setUuid": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Interim/transitional: identifies the legacy color-set entry this CTR belongs to, for color-set legacy output reconstruction. Only present alongside legacyKey."
+        },
+        "setSchema": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interim/transitional: names the legacy color-set schema this CTR's set entry conforms to. Only present alongside setUuid."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ctrWithRef": {
+      "type": "object",
+      "required": ["scope", "$ref"],
+      "not": {
+        "required": ["value"]
+      },
+      "dependentRequired": {
+        "setUuid": ["legacyKey"],
+        "setSchema": ["legacyKey"]
+      },
+      "properties": {
+        "specVersion": {
+          "const": "1.0.0-draft"
+        },
+        "scope": {
+          "$ref": "#/$defs/scope"
+        },
+        "context": {
+          "type": "string",
+          "description": "Human-readable label for how this CTR is used (mirrors tokenBindings[].context; maps to a Figma Token Group label). Purely descriptive — not validated."
+        },
+        "$valueType": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "URI reference to a value-type schema under schemas/value-types/. When present, the alias resolution chain MUST terminate at a value validating against this schema."
+        },
+        "$ref": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Alias target. MUST resolve to a token or relationship UUID in the dataset (SPEC-055)."
+        },
+        "uuid": {
+          "type": "string",
+          "format": "uuid",
+          "description": "MUST be globally unique across all relationship entries in the same layer (SPEC-056)."
+        },
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle"
+        },
+        "private": {
+          "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the relationship's purpose."
+        },
+        "legacyKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interim/transitional: pins the exact flat key written to legacy output (packages/tokens/src) for CTRs that must round-trip through the legacy generator. Not required for CTRs with no legacy counterpart. See spec/relationship-format.md#legacy-fields."
+        },
+        "setUuid": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Interim/transitional: identifies the legacy color-set entry this CTR belongs to, for color-set legacy output reconstruction. Only present alongside legacyKey."
+        },
+        "setSchema": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interim/transitional: names the legacy color-set schema this CTR's set entry conforms to. Only present alongside setUuid."
+        }
+      },
+      "additionalProperties": false
+    },
+    "relationship": {
+      "type": "object",
+      "oneOf": [
+        { "$ref": "#/$defs/ctrWithValue" },
+        { "$ref": "#/$defs/ctrWithRef" }
+      ]
+    }
+  }
+}

package/schemas/token.schema.json

@@ -114,6 +114,40 @@
         "type": "string"
       }
     },
+    "lifecycle": {
+      "type": "object",
+      "description": "Version lifecycle metadata, mirroring the component lifecycle pattern (see component.schema.json).",
+      "properties": {
+        "introduced": {
+          "type": "string",
+          "description": "Spec version when this token was added (e.g. \"1.0.0-draft\")."
+        },
+        "deprecatedIn": {
+          "type": "string",
+          "description": "Spec version when the token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
+        },
+        "deprecatedComment": {
+          "type": "string",
+          "description": "Human-readable deprecation explanation and migration guidance."
+        },
+        "replacedBy": {
+          "oneOf": [
+            { "type": "string", "format": "uuid" },
+            {
+              "type": "array",
+              "items": { "type": "string", "format": "uuid" },
+              "minItems": 1
+            }
+          ],
+          "description": "UUID(s) of the replacement token(s). Array form requires deprecatedComment."
+        },
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when token will be removed."
+        }
+      },
+      "additionalProperties": false
+    },
     "tokenWithValue": {
       "type": "object",
       "required": ["name", "value"],
@@ -166,30 +200,8 @@
           "type": "string",
           "format": "uuid"
         },
-        "introduced": {
-          "type": "string"
-        },
-        "deprecated": {
-          "type": "string",
-          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
-        },
-        "deprecated_comment": {
-          "type": "string"
-        },
-        "replaced_by": {
-          "oneOf": [
-            { "type": "string", "format": "uuid" },
-            {
-              "type": "array",
-              "items": { "type": "string", "format": "uuid" },
-              "minItems": 1
-            }
-          ],
-          "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
-        },
-        "plannedRemoval": {
-          "type": "string",
-          "description": "Spec version when token will be removed."
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle"
         },
         "private": {
           "type": "boolean"
@@ -250,30 +262,8 @@
           "type": "string",
           "format": "uuid"
         },
-        "introduced": {
-          "type": "string"
-        },
-        "deprecated": {
-          "type": "string",
-          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
-        },
-        "deprecated_comment": {
-          "type": "string"
-        },
-        "replaced_by": {
-          "oneOf": [
-            { "type": "string", "format": "uuid" },
-            {
-              "type": "array",
-              "items": { "type": "string", "format": "uuid" },
-              "minItems": 1
-            }
-          ],
-          "description": "UUID(s) of the replacement token(s). Array form requires deprecated_comment."
-        },
-        "plannedRemoval": {
-          "type": "string",
-          "description": "Spec version when token will be removed."
+        "lifecycle": {
+          "$ref": "#/$defs/lifecycle"
         },
         "private": {
           "type": "boolean"