@adobe/design-data-spec 0.0.1 → 0.1.0

package/conformance/README.md

@@ -2,18 +2,90 @@
 
 Each **invalid** case lives under `invalid/<RULE_ID>/` with:
 
-- One or more JSON **fixture** files (structurally valid for Layer 1 when targeting Layer 2 rules).
-- **`expected-errors.json`** — expected diagnostics after Layer 2 validation (see `errors[].rule_id`, `severity`, optional `message_pattern`).
+* One or more JSON **fixture** files (structurally valid for Layer 1 when targeting Layer 2 rules).
+* **`expected-errors.json`** — expected diagnostics after Layer 2 validation (see `errors[].rule_id`, `severity`, optional `message_pattern`).
 
 **Valid** baselines live under `valid/`.
 
-| Folder             | Rule     | Intent                                            |
-| ------------------ | -------- | ------------------------------------------------- |
-| `invalid/SPEC-001` | SPEC-001 | Alias target does not exist.                      |
-| `invalid/SPEC-002` | SPEC-002 | Alias resolves to incompatible type (semantic).   |
-| `invalid/SPEC-003` | SPEC-003 | Circular alias chain.                             |
-| `invalid/SPEC-004` | SPEC-004 | Duplicate `uuid` across tokens.                   |
-| `invalid/SPEC-005` | SPEC-005 | Dimension `default` not in `modes`.               |
-| `invalid/SPEC-006` | SPEC-006 | Ambiguous resolution / specificity tie (warning). |
+| Folder             | Rule     | Intent                                                  |
+| ------------------ | -------- | ------------------------------------------------------- |
+| `invalid/SPEC-001` | SPEC-001 | Alias target does not exist.                            |
+| `invalid/SPEC-002` | SPEC-002 | Alias resolves to incompatible type (semantic).         |
+| `invalid/SPEC-003` | SPEC-003 | Circular alias chain.                                   |
+| `invalid/SPEC-004` | SPEC-004 | Duplicate `uuid` across tokens.                         |
+| `invalid/SPEC-005` | SPEC-005 | Dimension `default` not in `modes`.                     |
+| `invalid/SPEC-006` | SPEC-006 | Ambiguous resolution / specificity tie (warning).       |
+| `invalid/SPEC-008` | SPEC-008 | Non-default mode variants with no base/default variant. |
 
 Implementors SHOULD run these fixtures once the Rust validator exposes rule IDs ([#724](https://github.com/adobe/spectrum-design-data/issues/724), [#725](https://github.com/adobe/spectrum-design-data/issues/725)).
+
+***
+
+## Resolution conformance fixtures
+
+Each **resolution** case lives under `resolution/<name>/` with:
+
+* `input/` — cascade-format `.tokens.json` files
+* `dimensions/` — (optional) dimension declaration JSON files
+* `query.json` — `{ "property": "...", "context": { ... } }` — the resolution query
+* `expected.json` — `{ "resolved": bool, "expected_uuid": "..." }` — expected outcome
+
+| Folder                                    | Intent                                                               |
+| ----------------------------------------- | -------------------------------------------------------------------- |
+| `resolution/base-fallback`                | Dimensionless base token MUST match any context (wildcard behavior). |
+| `resolution/specificity-wins`             | Higher-specificity variant MUST win over base when both match.       |
+| `resolution/alias-resolved-after-cascade` | Cascade selects the winner first; alias `$ref` chain resolves after. |
+
+The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`resolution_conformance` module, closes [#768](https://github.com/adobe/spectrum-design-data/issues/768)).
+
+***
+
+## Diff conformance fixtures
+
+Each **diff** case lives under `diff/<name>/` with:
+
+* `old/` — old token dataset (`.tokens.json` cascade arrays or `.json` legacy format)
+* `new/` — new token dataset
+* `expected.json` — full `DiffReport` structure (six category arrays: renamed, deprecated, reverted, added, deleted, updated)
+
+| Folder                                | Intent                                                                           |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `diff/identical-tokens`               | Two identical datasets MUST produce an empty diff (all arrays empty).            |
+| `diff/simple-add-delete`              | One old-only token → deleted; one new-only token → added.                        |
+| `diff/rename-by-uuid`                 | Same UUID, different name objects → renamed (not add + delete).                  |
+| `diff/deprecated-new-token`           | Unmatched new token with `deprecated: true` → deprecated (not added).            |
+| `diff/deprecated-set-level`           | All set entries `deprecated: true` normalizes to token-level deprecated.         |
+| `diff/reverted-token`                 | Matched token that loses `deprecated` → reverted (not updated).                  |
+| `diff/matched-gaining-deprecated`     | Matched token that gains `deprecated` → updated (not deprecated).               |
+| `diff/property-value-update`          | Matched token with changed `value` → updated with property change.               |
+| `diff/property-nested-change`         | Nested object change reported at leaf path (e.g. `sets.light.value`).            |
+| `diff/uuid-backfill`                  | Old lacks UUID, new gains it with same name object → paired (not add + delete).  |
+| `diff/cross-format`                   | Legacy old + cascade new, paired by UUID across formats.                         |
+| `diff/rename-with-property-changes`   | Renamed token with additional value changes populates `property_changes`.        |
+
+The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`diff_conformance` module, closes [#788](https://github.com/adobe/spectrum-design-data/issues/788)).
+
+***
+
+## Query conformance fixtures
+
+Each **query** case lives under `query/<name>/` with:
+
+* `input/` — cascade-format `.tokens.json` files
+* `query.txt` — plain-text filter expression
+* `expected.json` — sorted array of matched token UUIDs
+
+| Folder                        | Intent                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `query/single-field`          | Basic `key=value` equality filter.                                        |
+| `query/and-conditions`        | `,` (AND) requires all conditions to match.                               |
+| `query/or-conditions`         | `\|` (OR) matches if any alternative matches.                             |
+| `query/negation`              | `!=` matches non-equal values and absent fields.                          |
+| `query/wildcard-suffix`       | Glob `*` at end of value matches prefix.                                  |
+| `query/wildcard-prefix`       | Glob `*` at start of value matches suffix.                                |
+| `query/empty-matches-all`     | Empty filter expression is a universal match.                             |
+| `query/no-matches`            | Filter with no matching tokens returns empty result.                      |
+| `query/schema-key`            | `$schema` key queries the top-level `$schema` field.                      |
+| `query/and-or-precedence`     | AND binds tighter than OR: `a,b\|c` = `(a AND b) OR c`.                  |
+
+The Rust SDK drives these fixtures in `sdk/core/src/lib.rs` (`query_conformance` module, closes [#788](https://github.com/adobe/spectrum-design-data/issues/788)).

package/conformance/diff/cross-format/expected.json

@@ -0,0 +1,27 @@
+{
+  "renamed": [
+    {
+      "old_name": "background-color-default",
+      "new_name": "background-color-default",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "name",
+          "change_type": "added",
+          "new_value": { "property": "background-color-default" }
+        },
+        {
+          "path": "value",
+          "change_type": "updated",
+          "new_value": "#000000",
+          "original_value": "#ffffff"
+        }
+      ]
+    }
+  ],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/cross-format/new/tokens.tokens.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": { "property": "background-color-default" },
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "#000000",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/cross-format/old/tokens.json

@@ -0,0 +1,7 @@
+{
+  "background-color-default": {
+    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color.json",
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+}

package/conformance/diff/deprecated-new-token/expected.json

@@ -0,0 +1,13 @@
+{
+  "renamed": [],
+  "deprecated": [
+    {
+      "name": "deprecated-token",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+    }
+  ],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/deprecated-new-token/new/tokens.tokens.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": { "property": "deprecated-token" },
+    "deprecated": true,
+    "value": "#999999",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/deprecated-new-token/old/tokens.tokens.json

@@ -0,0 +1 @@
+[]

package/conformance/diff/deprecated-set-level/expected.json

@@ -0,0 +1,13 @@
+{
+  "renamed": [],
+  "deprecated": [
+    {
+      "name": "set-deprecated-token",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+    }
+  ],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/deprecated-set-level/new/tokens.tokens.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": { "property": "set-deprecated-token" },
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "sets": {
+      "light": { "value": "#ffffff", "deprecated": true },
+      "dark": { "value": "#000000", "deprecated": true }
+    }
+  }
+]

package/conformance/diff/deprecated-set-level/old/tokens.tokens.json

@@ -0,0 +1 @@
+[]

package/conformance/diff/identical-tokens/expected.json

@@ -0,0 +1,8 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/identical-tokens/new/tokens.tokens.json

@@ -0,0 +1,12 @@
+[
+  {
+    "name": { "property": "background-color-default" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  },
+  {
+    "name": { "property": "border-color-default" },
+    "value": "#cccccc",
+    "uuid": "aaaaaaaa-0002-4000-8000-000000000001"
+  }
+]

package/conformance/diff/identical-tokens/old/tokens.tokens.json

@@ -0,0 +1,12 @@
+[
+  {
+    "name": { "property": "background-color-default" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  },
+  {
+    "name": { "property": "border-color-default" },
+    "value": "#cccccc",
+    "uuid": "aaaaaaaa-0002-4000-8000-000000000001"
+  }
+]

package/conformance/diff/matched-gaining-deprecated/expected.json

@@ -0,0 +1,20 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": [
+    {
+      "name": "gaining-deprecated",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "deprecated",
+          "change_type": "added",
+          "new_value": true
+        }
+      ]
+    }
+  ]
+}

package/conformance/diff/matched-gaining-deprecated/new/tokens.tokens.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": { "property": "gaining-deprecated" },
+    "deprecated": true,
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/matched-gaining-deprecated/old/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "gaining-deprecated" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/property-nested-change/expected.json

@@ -0,0 +1,27 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": [
+    {
+      "name": "overlay-color",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "sets.dark.value",
+          "change_type": "updated",
+          "new_value": "#111111",
+          "original_value": "#000000"
+        },
+        {
+          "path": "sets.light.value",
+          "change_type": "updated",
+          "new_value": "#eeeeee",
+          "original_value": "#ffffff"
+        }
+      ]
+    }
+  ]
+}

package/conformance/diff/property-nested-change/new/tokens.tokens.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": { "property": "overlay-color" },
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "sets": {
+      "light": { "value": "#eeeeee" },
+      "dark": { "value": "#111111" }
+    }
+  }
+]

package/conformance/diff/property-nested-change/old/tokens.tokens.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": { "property": "overlay-color" },
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "sets": {
+      "light": { "value": "#ffffff" },
+      "dark": { "value": "#000000" }
+    }
+  }
+]

package/conformance/diff/property-value-update/expected.json

@@ -0,0 +1,21 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": [
+    {
+      "name": "background-color",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "value",
+          "change_type": "updated",
+          "new_value": "#000000",
+          "original_value": "#ffffff"
+        }
+      ]
+    }
+  ]
+}

package/conformance/diff/property-value-update/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "background-color" },
+    "value": "#000000",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/property-value-update/old/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "background-color" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/rename-by-uuid/expected.json

@@ -0,0 +1,22 @@
+{
+  "renamed": [
+    {
+      "old_name": "old-name",
+      "new_name": "new-name",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "name.property",
+          "change_type": "updated",
+          "new_value": "new-name",
+          "original_value": "old-name"
+        }
+      ]
+    }
+  ],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/rename-by-uuid/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "new-name" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/rename-by-uuid/old/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "old-name" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/rename-with-property-changes/expected.json

@@ -0,0 +1,28 @@
+{
+  "renamed": [
+    {
+      "old_name": "old-prop[component=button]",
+      "new_name": "new-prop[component=button]",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "name.property",
+          "change_type": "updated",
+          "new_value": "new-prop",
+          "original_value": "old-prop"
+        },
+        {
+          "path": "value",
+          "change_type": "updated",
+          "new_value": "20px",
+          "original_value": "10px"
+        }
+      ]
+    }
+  ],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/rename-with-property-changes/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "new-prop", "component": "button" },
+    "value": "20px",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/rename-with-property-changes/old/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "old-prop", "component": "button" },
+    "value": "10px",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/replaced-by-pairing/expected.json

@@ -0,0 +1,43 @@
+{
+  "renamed": [
+    {
+      "old_name": "old-button-bg",
+      "new_name": "action-background-default",
+      "uuid": "aaaaaaaa-0002-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "deprecated",
+          "change_type": "deleted",
+          "original_value": "3.0.0"
+        },
+        {
+          "path": "deprecated_comment",
+          "change_type": "deleted",
+          "original_value": "Use action-background-default instead."
+        },
+        {
+          "path": "name.property",
+          "change_type": "updated",
+          "new_value": "action-background-default",
+          "original_value": "old-button-bg"
+        },
+        {
+          "path": "replaced_by",
+          "change_type": "deleted",
+          "original_value": "aaaaaaaa-0002-4000-8000-000000000001"
+        },
+        {
+          "path": "uuid",
+          "change_type": "updated",
+          "new_value": "aaaaaaaa-0002-4000-8000-000000000001",
+          "original_value": "aaaaaaaa-0001-4000-8000-000000000001"
+        }
+      ]
+    }
+  ],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/replaced-by-pairing/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "action-background-default" },
+    "value": "#0265dc",
+    "uuid": "aaaaaaaa-0002-4000-8000-000000000001"
+  }
+]

package/conformance/diff/replaced-by-pairing/old/tokens.tokens.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": { "property": "old-button-bg" },
+    "value": "#0265dc",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+    "deprecated": "3.0.0",
+    "deprecated_comment": "Use action-background-default instead.",
+    "replaced_by": "aaaaaaaa-0002-4000-8000-000000000001"
+  }
+]

package/conformance/diff/reverted-token/expected.json

@@ -0,0 +1,13 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [
+    {
+      "name": "reverted-prop",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+    }
+  ],
+  "added": [],
+  "deleted": [],
+  "updated": []
+}

package/conformance/diff/reverted-token/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "reverted-prop" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/reverted-token/old/tokens.tokens.json

@@ -0,0 +1,8 @@
+[
+  {
+    "name": { "property": "reverted-prop" },
+    "deprecated": true,
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/simple-add-delete/expected.json

@@ -0,0 +1,18 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [
+    {
+      "name": "new-only-token",
+      "uuid": "aaaaaaaa-0002-4000-8000-000000000001"
+    }
+  ],
+  "deleted": [
+    {
+      "name": "old-only-token",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+    }
+  ],
+  "updated": []
+}

package/conformance/diff/simple-add-delete/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "new-only-token" },
+    "value": "#000000",
+    "uuid": "aaaaaaaa-0002-4000-8000-000000000001"
+  }
+]

package/conformance/diff/simple-add-delete/old/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "old-only-token" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/uuid-backfill/expected.json

@@ -0,0 +1,20 @@
+{
+  "renamed": [],
+  "deprecated": [],
+  "reverted": [],
+  "added": [],
+  "deleted": [],
+  "updated": [
+    {
+      "name": "background-color",
+      "uuid": "aaaaaaaa-0001-4000-8000-000000000001",
+      "property_changes": [
+        {
+          "path": "uuid",
+          "change_type": "added",
+          "new_value": "aaaaaaaa-0001-4000-8000-000000000001"
+        }
+      ]
+    }
+  ]
+}

package/conformance/diff/uuid-backfill/new/tokens.tokens.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": { "property": "background-color" },
+    "value": "#ffffff",
+    "uuid": "aaaaaaaa-0001-4000-8000-000000000001"
+  }
+]

package/conformance/diff/uuid-backfill/old/tokens.tokens.json

@@ -0,0 +1,6 @@
+[
+  {
+    "name": { "property": "background-color" },
+    "value": "#ffffff"
+  }
+]

package/conformance/invalid/SPEC-008/dimension.json

@@ -0,0 +1,5 @@
+{
+  "name": "colorScheme",
+  "modes": ["light", "dark", "wireframe"],
+  "default": "light"
+}