@adobe/design-data-spec 1.5.0 → 2.1.0

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

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-009",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry.*"
+      "message_pattern": ".*not in the spectrum-design-data.*"
     }
   ]
 }

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

@@ -5,5 +5,12 @@
       "value": "#ff0000"
     }
   ],
-  "components": []
+  "components": [
+    {
+      "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
+      "name": "button",
+      "displayName": "Button",
+      "meta": { "category": "actions" }
+    }
+  ]
 }

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

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-034",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry categories vocabulary.*"
+      "message_pattern": ".*not in the spectrum-design-data registry/categories vocabulary.*"
     }
   ]
 }

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

@@ -4,7 +4,7 @@
     {
       "rule_id": "SPEC-035",
       "severity": "warning",
-      "message_pattern": ".*not in the design-system-registry anatomy-terms vocabulary.*"
+      "message_pattern": ".*not in the spectrum-design-data registry/anatomy-terms vocabulary.*"
     }
   ]
 }

package/conformance/invalid/SPEC-044/empty-optional-dir/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-044",
+      "severity": "warning",
+      "message_pattern": ".*components/.*contains no.*json.*"
+    }
+  ]
+}

package/conformance/invalid/SPEC-044/empty-optional-dir/tokens/base.tokens.json

@@ -0,0 +1 @@
+{}

package/conformance/invalid/SPEC-044/missing-tokens/expected-errors.json

@@ -0,0 +1,10 @@
+{
+  "layer": 2,
+  "errors": [
+    {
+      "rule_id": "SPEC-044",
+      "severity": "error",
+      "message_pattern": ".*tokens/.*not found.*"
+    }
+  ]
+}

package/conformance/valid/SPEC-044/components/button.json

@@ -0,0 +1,9 @@
+{
+  "$id": "https://opensource.adobe.com/spectrum-design-data/conformance/valid/SPEC-044/button.json",
+  "name": "button",
+  "displayName": "Button",
+  "meta": {
+    "category": "actions",
+    "documentationUrl": "https://spectrum.adobe.com/page/button/"
+  }
+}

package/conformance/valid/SPEC-044/expected-errors.json

@@ -0,0 +1,4 @@
+{
+  "layer": 2,
+  "errors": []
+}

package/conformance/valid/SPEC-044/tokens/base.tokens.json

@@ -0,0 +1 @@
+{}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adobe/design-data-spec",
-  "version": "1.5.0",
-  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for Spectrum design data",
+  "version": "2.1.0",
+  "description": "Design Data Specification — prose, JSON Schemas, rule catalog, and conformance fixtures for the design data format",
   "type": "module",
   "repository": {
     "type": "git",
@@ -20,7 +20,6 @@
   },
   "exports": {
     "./package.json": "./package.json",
-    "./components/*.json": "./components/*.json",
     "./schemas/token.schema.json": "./schemas/token.schema.json",
     "./schemas/mode-set.schema.json": "./schemas/mode-set.schema.json",
     "./schemas/field.schema.json": "./schemas/field.schema.json",
@@ -29,12 +28,13 @@
     "./schemas/component.schema.json": "./schemas/component.schema.json",
     "./schemas/anatomy-part.schema.json": "./schemas/anatomy-part.schema.json",
     "./schemas/state-declaration.schema.json": "./schemas/state-declaration.schema.json",
-    "./rules/rules.yaml": "./rules/rules.yaml"
+    "./rules/rules.yaml": "./rules/rules.yaml",
+    "./schemas/registry-value.json": "./schemas/registry-value.json",
+    "./schemas/platform-extension.json": "./schemas/platform-extension.json",
+    "./schemas/dataset.schema.json": "./schemas/dataset.schema.json"
   },
   "files": [
-    "components",
     "conformance",
-    "fields",
     "rules",
     "schemas",
     "spec",

package/rules/rules.yaml

@@ -78,8 +78,8 @@ rules:
     name: name-field-enum-sync
     severity: warning
     category: naming-consistency
-    assert: Recognized name object fields (component, state, variant, etc.) SHOULD use values drawn from the corresponding design-system-registry enums when those enums are available.
-    message: "Token name field '{field}' value '{value}' is not in the design-system-registry enum for '{field}'"
+    assert: Recognized name object fields (component, state, variant, etc.) SHOULD use values drawn from the corresponding spectrum-design-data registry when those enums are available.
+    message: "Token name field '{field}' value '{value}' is not in the spectrum-design-data registry for '{field}'"
     spec_ref: spec/token-format.md#name-object
     introduced_in: "1.0.0-draft"
 
@@ -161,6 +161,7 @@ rules:
     category: reference-integrity
     assert: Token name-object 'component' field value MUST match the 'name' of a declared component in the dataset.
     message: "Token '{token}' references undeclared component '{component}'"
+    note: "Skipped when no component catalog is loaded (empty components list). Token-only validation runs that omit component declarations will not trigger this rule."
     spec_ref: spec/component-format.md#name
     introduced_in: "1.0.0-draft"
 
@@ -327,9 +328,9 @@ rules:
     category: naming-consistency
     assert: >
       A component's meta.category SHOULD reference an id from the categories registry in
-      @adobe/design-system-registry (categories.json). Unknown values are reported as
+      @adobe/spectrum-design-data registry/categories.json. Unknown values are reported as
       warnings; the registry is the authoritative vocabulary.
-    message: "Component '{entity}' meta.category value '{value}' is not in the design-system-registry categories vocabulary"
+    message: "Component '{entity}' meta.category value '{value}' is not in the spectrum-design-data registry/categories vocabulary"
     spec_ref: spec/registry.md#categories
     introduced_in: "1.0.0-draft"
   - id: SPEC-035
@@ -338,9 +339,9 @@ rules:
     category: naming-consistency
     assert: >
       A component anatomy part's name SHOULD reference an id from the anatomy-terms registry in
-      @adobe/design-system-registry (anatomy-terms.json). Unknown values are reported as
+      @adobe/spectrum-design-data registry/anatomy-terms.json. Unknown values are reported as
       warnings; custom names remain permitted but the registry is the authoritative vocabulary.
-    message: "Component '{entity}' anatomy part name '{value}' is not in the design-system-registry anatomy-terms vocabulary"
+    message: "Component '{entity}' anatomy part name '{value}' is not in the spectrum-design-data registry/anatomy-terms vocabulary"
     spec_ref: spec/anatomy-format.md#canonical-anatomy-vocabulary
     introduced_in: "1.0.0-draft"
 
@@ -452,7 +453,7 @@ rules:
       color-domain token. Using a color-scoped field on a typography token, or a
       typography-scoped field on a color token, is a taxonomy violation. The set of
       domain-scoped fields and their valid schema URL suffixes is declared in the field
-      catalog under `packages/design-data-spec/fields/` via the `scope` property.
+      catalog under `packages/design-data/fields/` via the `scope` property.
       Tokens without a `$schema` are skipped (domain cannot be determined).
     message: "name.{field} is a {scope}-scoped field but token schema '{effective_schema}' is not a {scope} token type"
     spec_ref: spec/taxonomy.md#token-type-taxonomies
@@ -476,3 +477,22 @@ rules:
     message: "{domain} token has a name object but no domain-identifying field — add at least one of: {required_fields}"
     spec_ref: spec/taxonomy.md#token-type-taxonomies
     introduced_in: "1.0.0-draft"
+
+  - id: SPEC-044
+    name: dataset-structure
+    severity: error
+    layer: 2
+    category: structure
+    assert: >
+      A conformant dataset MUST contain a `tokens/` directory holding at least one
+      `*.tokens.json` file. This structural pre-check fires before token- and
+      component-level rules so that downstream rules can assume the dataset structure
+      is present, and an incomplete dataset produces a clear "structure is incomplete"
+      diagnostic rather than a cascade of confusing per-file errors. A registered
+      optional directory (`components/`, `fields/`, `mode-sets/`, `registry/`) that is
+      present SHOULD contain at least one conformant `*.json` file; an empty registered
+      directory is reported as a warning. Because this rule inspects the on-disk
+      directory layout it runs as a filesystem pre-pass, not against the in-memory graph.
+    message: "Dataset structure incomplete: {detail}"
+    spec_ref: spec/dataset-layout.md#structural-validation
+    introduced_in: "1.0.0-draft"

package/schemas/component.schema.json

@@ -89,7 +89,7 @@
         "category": {
           "type": "string",
           "minLength": 1,
-          "description": "Category id from @adobe/design-system-registry categories.json. Advisory validation via SPEC-034."
+          "description": "Category id from @adobe/spectrum-design-data registry/categories.json. Advisory validation via SPEC-034."
         },
         "documentationUrl": {
           "type": "string",

package/schemas/dataset.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/dataset.schema.json",
+  "title": "Dataset root descriptor",
+  "description": "Optional root descriptor (dataset.json) a design-data dataset MAY carry to declare which optional directories are present, pin the targeted spec version, and override default discovery paths. Absence of this file is not an error; see spec/dataset-layout.md.",
+  "type": "object",
+  "properties": {
+    "specVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The spec version this dataset targets (e.g. \"1.0.0-draft\")."
+    },
+    "directories": {
+      "type": "object",
+      "description": "Declares which registered directories the dataset provides. List a directory key with the value true to declare it present and authoritative; omit the key otherwise. The value is constrained to true so the flag cannot be used to negate a directory's presence (in particular it cannot waive the required tokens/ directory).",
+      "properties": {
+        "tokens": { "const": true },
+        "components": { "const": true },
+        "fields": { "const": true },
+        "modeSets": { "const": true },
+        "registry": { "const": true }
+      },
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "description": "Optional overrides for the default discovery paths, relative to the dataset root. When omitted, tooling uses the conventional directory names defined in spec/dataset-layout.md.",
+      "properties": {
+        "tokens": { "type": "string", "minLength": 1 },
+        "components": { "type": "string", "minLength": 1 },
+        "fields": { "type": "string", "minLength": 1 },
+        "modeSets": { "type": "string", "minLength": 1 },
+        "registry": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/manifest.schema.json

@@ -94,29 +94,7 @@
             "conceptOrder": {
               "type": "array",
               "items": {
-                "type": "string",
-                "enum": [
-                  "variant",
-                  "component",
-                  "structure",
-                  "substructure",
-                  "anatomy",
-                  "object",
-                  "property",
-                  "orientation",
-                  "position",
-                  "size",
-                  "density",
-                  "shape",
-                  "state",
-                  "colorFamily",
-                  "family",
-                  "weight",
-                  "style",
-                  "motionRole",
-                  "easing",
-                  "alignment"
-                ]
+                "type": "string"
               },
               "uniqueItems": true,
               "description": "Ordered list of field names for serialization. Values must match declared field names from the design system's field catalog (field.schema.json declarations). Replaces the default serialization.position order from each field declaration."

package/schemas/mode-set.schema.json

@@ -6,6 +6,10 @@
   "type": "object",
   "required": ["name", "modes", "default"],
   "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
     "specVersion": {
       "const": "1.0.0-draft"
     },

package/schemas/platform-extension.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/platform-extension.json",
+  "title": "Platform Extension",
+  "description": "Schema for platform-specific terminology extensions",
+  "type": "object",
+  "required": ["platform", "extends", "extensions"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "platform": {
+      "type": "string",
+      "description": "The platform this extension is for (e.g., iOS, Android, Web Components, Qt)"
+    },
+    "platformVersion": {
+      "type": "string",
+      "description": "Optional platform version or framework version"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of what this extension provides"
+    },
+    "extends": {
+      "type": "string",
+      "description": "Which registry this extends (sizes, states, variants, etc.)"
+    },
+    "extensions": {
+      "type": "array",
+      "description": "Array of term extensions",
+      "items": {
+        "$ref": "#/$defs/extension"
+      }
+    }
+  },
+  "$defs": {
+    "extension": {
+      "type": "object",
+      "required": ["termId"],
+      "properties": {
+        "termId": {
+          "type": "string",
+          "description": "The ID of the term being extended (must exist in the base registry)"
+        },
+        "platformTerm": {
+          "type": "string",
+          "description": "Platform-specific term or name"
+        },
+        "platformAliases": {
+          "type": "array",
+          "description": "Platform-specific aliases",
+          "items": {
+            "type": "string"
+          }
+        },
+        "notes": {
+          "type": "string",
+          "description": "Platform-specific implementation notes"
+        },
+        "reference": {
+          "type": "string",
+          "description": "Platform documentation reference or API name"
+        },
+        "codeExample": {
+          "type": "string",
+          "description": "Code example showing platform usage"
+        },
+        "differences": {
+          "type": "array",
+          "description": "Key differences from the base term",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/registry-value.json

@@ -0,0 +1,230 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/registry-value.json",
+  "title": "Registry Value",
+  "description": "Schema for design system registry value entries",
+  "type": "object",
+  "required": ["type", "description", "values"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "type": {
+      "type": "string",
+      "description": "The type of registry (size, state, variant, etc.)"
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of what this registry contains"
+    },
+    "allowCustom": {
+      "type": "boolean",
+      "description": "Whether custom values are allowed beyond the registry"
+    },
+    "customPattern": {
+      "type": "string",
+      "description": "Regex pattern for validating custom values"
+    },
+    "values": {
+      "type": "array",
+      "description": "Array of registry values",
+      "items": {
+        "$ref": "#/$defs/value"
+      }
+    }
+  },
+  "$defs": {
+    "value": {
+      "type": "object",
+      "required": ["id", "label"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this value"
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label"
+        },
+        "aliases": {
+          "type": "array",
+          "description": "Alternative names or spellings",
+          "items": {
+            "type": "string"
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Detailed description of this value"
+        },
+        "default": {
+          "type": "boolean",
+          "description": "Whether this is the default value"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Whether this value is deprecated"
+        },
+        "usedIn": {
+          "type": "array",
+          "description": "Where this value is used (tokens, component-schemas, etc.)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "category": {
+          "type": "string",
+          "description": "Category or grouping for this value"
+        },
+        "value": {
+          "type": ["string", "number", "boolean"],
+          "description": "Actual value (if different from id)"
+        },
+        "documentationUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "URL to documentation"
+        },
+        "definition": {
+          "type": "object",
+          "description": "Structured definition following Spectrum naming methodology",
+          "properties": {
+            "superordinate": {
+              "type": "string",
+              "description": "The higher-level category or class this term belongs to"
+            },
+            "description": {
+              "type": "string",
+              "description": "Core definition explaining what it is and how it differs"
+            },
+            "essentialCharacteristics": {
+              "type": "array",
+              "description": "Key characteristics that distinguish this term",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "platforms": {
+          "type": "object",
+          "description": "Platform-specific terminology and notes",
+          "patternProperties": {
+            ".*": {
+              "type": "object",
+              "properties": {
+                "term": {
+                  "type": "string",
+                  "description": "Platform-specific term or name"
+                },
+                "notes": {
+                  "type": "string",
+                  "description": "Platform-specific implementation notes"
+                },
+                "reference": {
+                  "type": "string",
+                  "description": "Platform documentation reference"
+                }
+              }
+            }
+          }
+        },
+        "terminology": {
+          "type": "object",
+          "description": "Terminology metadata and classification",
+          "properties": {
+            "conceptType": {
+              "type": "string",
+              "enum": ["word", "term", "name", "concept"],
+              "description": "Classification per Spectrum naming guide"
+            },
+            "namingRationale": {
+              "type": "string",
+              "description": "Why this name was chosen"
+            },
+            "alternatives": {
+              "type": "array",
+              "description": "Alternative terms considered but not used",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "sources": {
+          "type": "array",
+          "description": "References to source documentation",
+          "items": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "wiki",
+                  "industry-standard",
+                  "platform-standard",
+                  "internal-doc",
+                  "research"
+                ],
+                "description": "Type of source"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "URL to source"
+              },
+              "reference": {
+                "type": "string",
+                "description": "Text reference or citation"
+              },
+              "date": {
+                "type": "string",
+                "format": "date",
+                "description": "Date of source or last update"
+              }
+            }
+          }
+        },
+        "governance": {
+          "type": "object",
+          "description": "Governance and ownership metadata",
+          "properties": {
+            "owner": {
+              "type": "string",
+              "description": "Team or person responsible for this term"
+            },
+            "reviewDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Last review date"
+            },
+            "nextReviewDate": {
+              "type": "string",
+              "format": "date",
+              "description": "Scheduled next review date"
+            },
+            "status": {
+              "type": "string",
+              "enum": ["draft", "review", "approved", "deprecated"],
+              "description": "Current status of this term"
+            },
+            "replacedBy": {
+              "type": "string",
+              "description": "If deprecated, the term that replaces this one"
+            }
+          }
+        },
+        "relatedTerms": {
+          "type": "array",
+          "description": "Related or cross-referenced terms",
+          "items": {
+            "type": "string",
+            "description": "ID of related term"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/token.schema.json

@@ -218,7 +218,7 @@
         "$ref": {
           "type": "string",
           "minLength": 1,
-          "description": "Alias target path or stable token id (resolution is Layer 2)."
+          "description": "Alias target. In cascade format: the target token's UUID (canonical, rename-proof, resolved via uuid_index — Layer 2). In the legacy transition format: the target's kebab-case name slug."
         },
         "uuid": {
           "type": "string",