@adobe/design-data-spec 0.0.1 → 0.1.1

package/schemas/token.schema.json

@@ -15,30 +15,73 @@
   "$defs": {
     "nameObject": {
       "type": "object",
-      "description": "Structured token identity; additional dimension keys MUST be strings.",
+      "description": "Structured token identity. Semantic fields describe identity and structure; dimension fields drive cascade resolution. See spec/taxonomy.md and spec/token-format.md. Additional dimension keys MUST be strings.",
       "required": ["property"],
       "properties": {
         "property": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "description": "Semantic: the stylistic attribute being defined (e.g. color, width, padding, gap)."
         },
         "component": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: component scope (e.g. button, checkbox)."
+        },
+        "structure": {
+          "type": "string",
+          "description": "Semantic: reusable visual pattern (e.g. base, container, list). Distinct from component."
+        },
+        "substructure": {
+          "type": "string",
+          "description": "Semantic: child within a parent structure (e.g. item in list-item)."
+        },
+        "anatomy": {
+          "type": "string",
+          "description": "Semantic: visible named part of a component (e.g. handle, icon, label)."
+        },
+        "object": {
+          "type": "string",
+          "description": "Semantic: styling surface (e.g. background, border, edge, visual)."
         },
         "variant": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: variant within a component (e.g. accent, negative, primary)."
         },
         "state": {
-          "type": "string"
+          "type": "string",
+          "description": "Semantic: interactive or semantic state (e.g. hover, focus, disabled)."
+        },
+        "orientation": {
+          "type": "string",
+          "description": "Semantic: direction or order (e.g. vertical, horizontal)."
+        },
+        "position": {
+          "type": "string",
+          "description": "Semantic: location relative to another object (e.g. affixed, top, bottom)."
+        },
+        "size": {
+          "type": "string",
+          "description": "Semantic: relative t-shirt sizing (e.g. small, medium, large). Distinct from dimension scale."
+        },
+        "density": {
+          "type": "string",
+          "description": "Semantic: space within or around component parts (e.g. spacious, compact)."
+        },
+        "shape": {
+          "type": "string",
+          "description": "Semantic: overall component shape (e.g. uniform)."
         },
         "colorScheme": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: color scheme mode (e.g. light, dark, wireframe)."
         },
         "scale": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: platform density scale (e.g. desktop, mobile)."
         },
         "contrast": {
-          "type": "string"
+          "type": "string",
+          "description": "Dimension: contrast level (e.g. regular, high)."
         }
       },
       "additionalProperties": {
@@ -88,20 +131,38 @@
         "introduced": {
           "type": "string"
         },
+        "lastModified": {
+          "type": "string",
+          "description": "Spec version when token value or metadata last changed (e.g. \"2.1.0\"). MUST be >= introduced (see SPEC-014)."
+        },
         "deprecated": {
-          "type": "boolean"
+          "type": "string",
+          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
         },
         "deprecated_comment": {
           "type": "string"
         },
-        "status": {
-          "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."
         },
-        "renamed": {
-          "type": "string"
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when token will be removed."
         },
         "private": {
           "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
         }
       },
       "additionalProperties": false
@@ -131,20 +192,38 @@
         "introduced": {
           "type": "string"
         },
+        "lastModified": {
+          "type": "string",
+          "description": "Spec version when token value or metadata last changed (e.g. \"2.1.0\"). MUST be >= introduced (see SPEC-014)."
+        },
         "deprecated": {
-          "type": "boolean"
+          "type": "string",
+          "description": "Spec version when token was deprecated (e.g. \"3.2.0\"). Truthy = deprecated."
         },
         "deprecated_comment": {
           "type": "string"
         },
-        "status": {
-          "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."
         },
-        "renamed": {
-          "type": "string"
+        "plannedRemoval": {
+          "type": "string",
+          "description": "Spec version when token will be removed."
         },
         "private": {
           "type": "boolean"
+        },
+        "description": {
+          "type": "string",
+          "description": "Plain text describing the token's purpose (aligns with DTCG $description)."
         }
       },
       "additionalProperties": false

package/spec/cascade.md

@@ -26,7 +26,12 @@ Design data is organized in three layers, ordered from lowest to highest precede
 
 **NORMATIVE:** When two candidates from the **same layer** match the context, the candidate with **higher** specificity **MUST** win.
 
-**NORMATIVE:** Ties on layer and specificity **MUST** be broken by a deterministic **document order** rule defined by the manifest or dataset index (implementation-defined in this draft; validators **SHOULD** emit a warning on ambiguous ties).
+**NORMATIVE:** Ties on layer and specificity **MUST** be broken by **document order**:
+
+1. Within a single source file, the token that appears **earlier** in the array **MUST** win.
+2. Across multiple files, the file with the **lexicographically earlier path** within the dataset **MUST** win.
+
+**NORMATIVE:** Validators **MUST** emit a SPEC-006 warning when a tie is detected, as ties indicate potential authoring mistakes.
 
 ## Context
 
@@ -40,10 +45,19 @@ The following outline is **RECOMMENDED** for conforming resolvers:
 2. Filter to candidates at or below the requested layer.
 3. Select the maximum **layer** precedence.
 4. Within that layer, select the maximum **specificity**.
-5. Break remaining ties by deterministic ordering.
+5. Break remaining ties by document order (earlier in file wins; lexicographically earlier file path wins across files). Emit SPEC-006 warning.
+6. If the winning candidate is an alias (`$ref`), **resolve the alias chain** to a literal value (see [Alias resolution](#alias-resolution)).
 
 Exact matching rules for omitted dimensions are defined alongside dimension declarations in [Dimensions](dimensions.md).
 
+## Alias resolution
+
+**NORMATIVE:** Alias (`$ref`) resolution **MUST** occur **after** cascade selection. The resolution algorithm selects the winning candidate using layer, specificity, and tie-breaking rules before any alias chain is followed.
+
+**NORMATIVE:** If the winning candidate is an alias, its `$ref` chain **MUST** be resolved to a literal value using the standard alias-resolution rules (SPEC-001 through SPEC-003 in `rules/rules.yaml`). The alias target is resolved within the same dataset (i.e. the same merged layer stack), not relative to any single layer.
+
+**RATIONALE:** Aliases participate in cascade as opaque references — their target values are not examined during specificity calculation or layer comparison. This keeps resolution deterministic and allows aliases to be valid candidates at any specificity level.
+
 ## Cross-dimensional overrides
 
 **NORMATIVE:** Overrides that combine multiple dimensions in a way not expressible by a single name object alone **MUST** use **explicit combination tokens** (tokens whose name object sets multiple non-default dimensions) as defined in the dataset; magic merging of unrelated tokens is **NOT** allowed.
@@ -52,3 +66,5 @@ Exact matching rules for omitted dimensions are defined alongside dimension decl
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#757 — Phase 2: Cascade tie-breaking rule](https://github.com/adobe/spectrum-design-data/issues/757)
+* [#758 — Phase 2: Alias resolution ordering in cascade context](https://github.com/adobe/spectrum-design-data/issues/758)

package/spec/diff.md

@@ -0,0 +1,97 @@
+# Semantic diff
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **semantic diff model**: how two versions of a design data dataset are compared to produce a structured change report with awareness of renames, deprecations, and property-level changes.
+
+## Token identity
+
+A **token identity** determines whether a token in the old dataset and a token in the new dataset refer to the same logical token.
+
+**NORMATIVE:** Implementations **MUST** use the following matching rules, in order:
+
+1. **UUID match** — If a token in the old dataset and a token in the new dataset share the same `uuid` value, they are the **same token** regardless of name.
+2. **Name-object equivalence** — When a UUID match is not found for a token — because the old token, the new token, or both lack a `uuid`, or because no counterpart with the matching `uuid` exists in the other dataset — two tokens are the same if their `name` objects are deeply equal (all fields present with identical values).
+3. **Replacement link** — When passes 1 and 2 leave an old token unpaired and it carries a `replaced_by` field whose UUID matches an unpaired new token, the pair is established. This enables diff classification as **renamed** for tokens that were deprecated with a machine-readable replacement pointer.
+
+**NORMATIVE:** UUID matching **MUST** take precedence over name-object equivalence, which **MUST** take precedence over replacement link matching. A UUID match always identifies the token pair, even if name objects differ (which constitutes a rename).
+
+**RATIONALE:** UUID-based identity allows tokens to be renamed without breaking continuity tracking. Name-object equivalence is a fallback for legacy datasets that predate UUID adoption. Replacement link matching is a tertiary fallback for deprecated tokens that carry an explicit `replaced_by` UUID pointing to their successor.
+
+## Change taxonomy
+
+A semantic diff classifies every token into exactly one of six categories:
+
+| Category       | Definition                                                                                       |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| **renamed**    | Token exists in both datasets (matched by identity) but the name has changed.                    |
+| **deprecated** | Token exists only in the new dataset (unmatched) and carries a `deprecated` field.               |
+| **reverted**   | Token existed with `deprecated` in the old dataset and no longer carries it in the new dataset.  |
+| **added**      | Token exists only in the new dataset and is not renamed, deprecated, or pre-existing.            |
+| **deleted**    | Token exists only in the old dataset and is not the source of a rename.                          |
+| **updated**    | Token exists in both datasets (matched by identity) with the same name but changed properties.   |
+
+**NORMATIVE:** Every token that appears in the old dataset, the new dataset, or both **MUST** be classified into exactly one category. Categories are mutually exclusive.
+
+## Category partitioning
+
+**NORMATIVE:** Implementations **MUST** resolve categories in the following order to ensure mutual exclusivity:
+
+1. **Renamed** — Identify all identity-matched pairs where the name has changed. These tokens are removed from further classification as added or deleted.
+2. **Deprecated** — Among remaining unmatched new tokens, identify those carrying a `deprecated` field. These are removed from the "added" pool.
+3. **Reverted** — Among identity-matched pairs, identify tokens where `deprecated` was present in the old version and absent in the new. These are removed from the "updated" pool.
+4. **Added** — Remaining unmatched new tokens that are not renamed, deprecated, or pre-existing in the old dataset.
+5. **Deleted** — Remaining unmatched old tokens that are not the source of a rename.
+6. **Updated** — Remaining identity-matched pairs with unchanged names but differing properties.
+
+**RATIONALE:** This ordering mirrors the pipeline in existing tooling and ensures that a renamed token does not also appear as "added" + "deleted", a deprecated token does not appear as "added", and so forth. A matched token that newly gains a `deprecated` field is classified as **updated** — the deprecation surfaces as a property-level change in the updated sub-categories, not as a new-token deprecation.
+
+## Deprecation normalization
+
+**NORMATIVE:** When a token uses the legacy `sets` structure and **all** set entries carry `deprecated: true`, the token **MUST** be treated as deprecated at the token level for diff classification purposes, even if the top-level token object does not carry `deprecated`.
+
+**RATIONALE:** Set-level deprecation that covers all variants is semantically equivalent to token-level deprecation. Normalizing this prevents diff noise from implementation-level differences in where the `deprecated` flag is placed.
+
+## Property-level changes
+
+For tokens classified as **updated** (or **renamed** with additional property changes), a semantic diff **SHOULD** produce property-level change records.
+
+### Change record format
+
+Each property-level change is described by:
+
+| Field            | Type   | Description                                             |
+| ---------------- | ------ | ------------------------------------------------------- |
+| `path`           | string | Dot-separated path from the token root (e.g. `value`, `name.colorScheme`, `sets.light.value`). |
+| `new_value`      | any    | The value in the new dataset. Present for additions and updates. |
+| `original_value` | any    | The value in the old dataset. Present for deletions and updates. |
+
+### Property change sub-categories
+
+| Sub-category          | Condition                                         |
+| --------------------- | ------------------------------------------------- |
+| **added-properties**  | Property exists in new but not in old.             |
+| **deleted-properties**| Property exists in old but not in new.             |
+| **updated-properties**| Property exists in both but with different values. |
+
+**NORMATIVE:** Property comparison **MUST** be recursive: nested objects are traversed and changes reported at the leaf level with full dot-separated paths.
+
+**NORMATIVE:** Property comparison **MUST** use deep equality for values. Two values are equal if their JSON serializations are identical.
+
+## Output ordering
+
+**RECOMMENDED:** Diff output **SHOULD** be deterministic. Within each category, tokens **SHOULD** be sorted by their canonical name (or new name for renames) in lexicographic order.
+
+**RATIONALE:** Deterministic output makes diff reports suitable for snapshot testing and human review.
+
+## Cross-format compatibility
+
+**NORMATIVE:** A conforming diff engine **MUST** accept both legacy format (JSON object maps) and cascade format (JSON arrays with `.tokens.json` extension) as inputs for either the old or new dataset, including mixed-format comparisons (e.g. legacy old, cascade new).
+
+**RATIONALE:** The diff operates on the token graph abstraction, which normalizes both formats into the same `TokenRecord` structure. This enables diffing across format migrations without special-case handling.
+
+## References
+
+* [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)
+* [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#776 — Phase 3: Diff change taxonomy and token identity rules](https://github.com/adobe/spectrum-design-data/issues/776)

package/spec/dimensions.md

@@ -25,13 +25,21 @@ A **dimension declaration** is a JSON object describing one axis of variation. I
 
 ## Built-in dimensions
 
-These dimensions **SHOULD** be used consistently across Spectrum-compatible datasets:
+These dimensions are declared in the `dimensions/` catalog (see [Dimension catalog](#dimension-catalog)) and **SHOULD** be used consistently across Spectrum-compatible datasets:
 
-| `name`        | Typical `modes`                 | Notes                         |
-| ------------- | ------------------------------- | ----------------------------- |
-| `colorScheme` | `light`, `dark`, `wireframe`, … | Theme / appearance.           |
-| `scale`       | `medium`, `large`, …            | Density / t-shirt scale.      |
-| `contrast`    | `regular`, `high`, …            | Accessibility contrast level. |
+| `name`        | `modes`                      | `default` | Notes                                                                             |
+| ------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
+| `colorScheme` | `light`, `dark`, `wireframe` | `light`   | Theme / appearance.                                                               |
+| `scale`       | `desktop`, `mobile`          | `desktop` | Density scale. Legacy names; desktop = medium, mobile = large in W3C terminology. |
+| `contrast`    | `regular`, `high`            | `regular` | Accessibility contrast level.                                                     |
+
+## Dimension catalog
+
+The Spectrum foundation publishes dimension declarations as JSON files under `packages/design-data-spec/dimensions/`. Each file conforms to [`dimension.schema.json`](../schemas/dimension.schema.json).
+
+**NORMATIVE:** Tooling (validators, resolution engine) **MUST** load dimension declarations from the dataset’s dimension catalog before performing specificity calculations or coverage validation.
+
+**RECOMMENDED:** The catalog directory is named `dimensions/` and is co-located with the dataset’s spec package or manifest.
 
 ## Optional dimensions
 
@@ -53,3 +61,4 @@ Additional dimensions (e.g. `language`, `motion`) **MAY** be declared in a datas
 
 * [#646 — Token Schema Structure and Validation System](https://github.com/adobe/spectrum-design-data/discussions/646)
 * [#714 — Design Data Specification](https://github.com/adobe/spectrum-design-data/discussions/714)
+* [#746 — Phase 2: Dimension declarations (machine-readable)](https://github.com/adobe/spectrum-design-data/issues/746)

package/spec/evolution.md

@@ -0,0 +1,99 @@
+# Evolution
+
+**Spec version:** `1.0.0-draft` (see [Overview](index.md))
+
+This document defines the **evolution policy** for the Design Data Specification: how the spec, schemas, and token data change over time, with a focus on the token deprecation lifecycle and backward compatibility.
+
+## Token deprecation lifecycle
+
+Tokens progress through the following lifecycle stages:
+
+```
+introduced → active → deprecated → planned removal → removed
+```
+
+| Stage               | Token state                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Introduced**      | Token first appears in the dataset. `introduced` field records the version.                                                                                                    |
+| **Active**          | Token is current and recommended for use. No `deprecated` field.                                                                                                               |
+| **Deprecated**      | Token is no longer recommended. `deprecated` records the version. Consumers receive warnings. `replaced_by` points to the successor token(s) when a direct replacement exists. |
+| **Planned removal** | `plannedRemoval` records the target version. The token remains in the dataset but consumers should complete migration.                                                         |
+| **Removed**         | Token is deleted from the dataset. Consumers that still reference it will break.                                                                                               |
+
+### Lifecycle fields
+
+See [Token format — Lifecycle and metadata](token-format.md#lifecycle-and-metadata) for the full field definitions and normative rules.
+
+### What `replaced_by` guarantees
+
+When a token carries `replaced_by`:
+
+* Each target UUID **MUST** resolve to an existing token in the dataset (rule `SPEC-010`).
+* The target token **SHOULD NOT** itself be deprecated. Chains of replacements (A replaced by B, B replaced by C) are discouraged; authors should point directly to the final replacement.
+* For a single UUID (1:1 replacement), consumers can mechanically rewrite references.
+* For an array of UUIDs (one-to-many split), the `deprecated_comment` **MUST** explain which replacement applies in which context.
+
+## Migration windows
+
+**NORMATIVE:** A deprecated token **MUST** remain in the published dataset for at least **two minor versions** after the version recorded in `deprecated` before it may be removed.
+
+**EXAMPLE:** A token deprecated in `3.2.0` may not be removed until `3.4.0` at the earliest. Removal in a major version (e.g. `4.0.0`) is always permitted regardless of how recently the token was deprecated.
+
+**RATIONALE:** Two minor versions gives consumers at least two release cycles to migrate. The major-version escape hatch allows accumulated deprecations to be cleaned up in a coordinated breaking release.
+
+If `plannedRemoval` is set, it overrides the default window — the token will be removed in the specified version (which must not precede the `deprecated` version).
+
+## Change classification
+
+The specification follows [Semantic Versioning](https://semver.org/) for its published artifacts (schemas, rule catalog, spec documents).
+
+### Minor changes (backward compatible)
+
+* New tokens added to the dataset
+* New optional fields added to token schema
+* New validation rules added to the rule catalog
+* Tokens deprecated (with `deprecated` field)
+* Rule severity relaxed (error → warning)
+* New enum values added to registries
+
+### Major changes (breaking)
+
+* Tokens removed from the dataset
+* Required fields added to token schema
+* Existing fields removed or type-changed
+* Rule severity tightened (warning → error)
+* Enum values removed from registries
+* Constraint tightening (e.g. stricter value validation)
+
+### Patch changes (clarifications)
+
+* Typo fixes in spec prose
+* Clarifications to normative text that do not change conformance behavior
+* Test fixture additions or corrections
+
+## Legacy format contract
+
+The `@adobe/spectrum-tokens` package continues to publish tokens in the **legacy format** (JSON object maps with `color-set`, `scale-set`, etc.) for backward compatibility with existing consumers.
+
+**NORMATIVE:** The legacy format output **MUST** be generated from the cascade-format authoritative source. It is a **derived artifact**, not independently authored.
+
+### Lifecycle field mapping
+
+| Cascade format                         | Legacy format                         |
+| -------------------------------------- | ------------------------------------- |
+| `deprecated: "3.2.0"` (version string) | `deprecated: true` (boolean)          |
+| `replaced_by: "<uuid>"`                | `renamed: "<target-token-name>"`      |
+| `introduced`                           | Not emitted                           |
+| `lastModified`                         | Not emitted                           |
+| `plannedRemoval`                       | Not emitted                           |
+| `deprecated_comment`                   | `deprecated_comment` (passed through) |
+
+### Coexistence during migration
+
+Both formats are published simultaneously. The cascade format is the source of truth; the legacy format is generated from it. This dual-format period continues until platform consumers have migrated to the cascade format or to platform SDKs that consume it.
+
+## References
+
+* [#623 — Token Lifecycle Metadata](https://github.com/adobe/spectrum-design-data/discussions/623)
+* [#735 — RFC: Versioning and Evolution](https://github.com/adobe/spectrum-design-data/discussions/735)
+* [#736 — Define spec evolution policy and migration contract](https://github.com/adobe/spectrum-design-data/issues/736)

package/spec/index.md

@@ -10,14 +10,13 @@ This document is the top-level overview for the **Design Data Specification**: a
 The specification defines:
 
 1. **Token format** — structured token identity (`name`), literal `value` or alias `$ref`, and lifecycle metadata ([Token format](token-format.md)).
-2. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
-3. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
-4. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
-
-Out of scope for this draft (tracked elsewhere):
-
-* Exact query syntax for `include` / `exclude` in manifests (placeholder fields only).
-* Full evolution, migration windows, and SDK version negotiation — see [discussion #735](https://github.com/adobe/spectrum-design-data/discussions/735).
+2. **Taxonomy** — concept categories, token term vocabulary, formatting style, and the distinction between component anatomy and token objects ([Taxonomy](taxonomy.md)).
+3. **Cascade and resolution** — layered data (foundation, platform, product), specificity, and how a context picks a winning value ([Cascade](cascade.md)).
+4. **Dimensions** — declared modes, defaults, and coverage expectations ([Dimensions](dimensions.md)).
+5. **Platform manifest** — how a platform repo pins foundation data, filters tokens, and applies typed overrides ([Manifest](manifest.md)).
+6. **Semantic diff** — change taxonomy, token identity rules, and property-level change tracking for comparing dataset versions ([Diff](diff.md)).
+7. **Query notation** — filter syntax for selecting tokens by structured fields ([Query](query.md)).
+8. **Evolution** — deprecation lifecycle, migration windows, change classification, and legacy format contract ([Evolution](evolution.md)).
 
 ## Conformance
 
@@ -54,9 +53,13 @@ Full governance (compatibility tiers, migration, CLI `--spec-version`) is discus
 | Document                        | Role                                                             |
 | ------------------------------- | ---------------------------------------------------------------- |
 | [Token format](token-format.md) | Token `name`, `value` / `$ref`, value types, lifecycle metadata. |
+| [Taxonomy](taxonomy.md)         | Concept categories, vocabulary, formatting, anatomy vs objects.  |
 | [Cascade](cascade.md)           | Layers, specificity, resolution algorithm.                       |
 | [Dimensions](dimensions.md)     | Dimension declarations, built-in dimensions, coverage.           |
 | [Manifest](manifest.md)         | Platform manifest fields and validation expectations.            |
+| [Diff](diff.md)                 | Semantic diff change taxonomy, token identity, property changes. |
+| [Query](query.md)               | Filter notation for selecting tokens by structured fields.       |
+| [Evolution](evolution.md)       | Deprecation lifecycle, migration windows, change classification. |
 
 ## JSON Schema `$id` and versioning
 

package/spec/manifest.md

@@ -26,7 +26,9 @@ A manifest **MUST** conform to [`manifest.schema.json`](../schemas/manifest.sche
 
 ### `include` / `exclude`
 
-**NORMATIVE:** Entries **MUST** be non-empty strings. The **query language** is **not** normative in `1.0.0-draft`; treat values as opaque identifiers for tooling until a future spec version defines syntax.
+**NORMATIVE:** Entries **MUST** be non-empty strings.
+
+> **Note:** Query notation syntax is fully defined in [Query](query.md) and is normative for programmatic use. Its normative use in manifest `include`/`exclude` is deferred to a post-`1.0.0-draft` revision pending conformance fixtures; until then, implementations **MUST** treat manifest query values as opaque identifiers.
 
 ### `overrides`
 
@@ -38,6 +40,21 @@ Each override object **MUST** include enough information to identify a target to
 
 **RECOMMENDED:** `extensions` follows the same structural conventions as foundation token files (tokens, dimensions) and **SHOULD** be validated with the same Layer 1 and Layer 2 rules.
 
+#### `extensions.formatting`
+
+A platform **MAY** declare formatting rules that control how structured name objects are serialized into flat token name strings for that platform. See [Taxonomy — Platform formatting configuration](taxonomy.md#platform-formatting-configuration) for motivation and examples.
+
+| Field           | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `conceptOrder`  | array of string | Ordered list of name object field names for serialization. Each entry **MUST** be a declared field name from the design system's [field catalog](../fields/) (see [Token format — Name object](token-format.md#name-object)). Omitted fields are appended in the default order defined by each field declaration's `serialization.position` (see [Taxonomy — Default serialization](taxonomy.md#default-serialization-legacy-format)). |
+| `casing`        | string          | One of: `kebab-case`, `camelCase`, `PascalCase`, `SCREAMING_SNAKE_CASE`. Default: `kebab-case`.                                                                                                                                                                                                                                                                                                                                        |
+| `delimiter`     | string          | Character(s) separating concepts in the serialized string (e.g. `-`, `_`, `.`, `/`). Default: `-`.                                                                                                                                                                                                                                                                                                                                     |
+| `abbreviations` | object          | Map of full term → abbreviated form (e.g. `{ "background": "bg" }`). Abbreviations are applied after concept ordering and before casing.                                                                                                                                                                                                                                                                                               |
+
+**NORMATIVE:** When `extensions.formatting` is absent, the default serialization defined in [Taxonomy](taxonomy.md#default-serialization-legacy-format) is used.
+
+**NORMATIVE:** A formatter applying `extensions.formatting` **MUST** produce deterministic output — the same name object and formatting configuration **MUST** always yield the same string.
+
 ## Validation
 
 **NORMATIVE:** Manifests **MUST** pass Layer 1 JSON Schema validation.