[DRAFT RFC] Design Data Specification Versioning and Evolution

[GarthDB]

Status: DRAFT RFC — open questions; no normative decisions yet.

Summary

This RFC proposes a dedicated track for how the Design Data Specification, JSON Schemas, rule catalog, and conformance fixtures evolve in a distributed model (foundation repo + platform repos). Structural validation (JSON Schema) cannot express graph rules; we also need a clear compatibility contract so pinned foundationVersion values, SDK behavior, and upgrade paths are predictable.

This discussion complements (does not replace) token-level lifecycle in #623 and distributed manifests in #715.

Relationship to other work

Artifact	Where it lives
Umbrella vision	#714 — Design Data Specification
Distributed repos, manifests, layers	#715 — Distributed Design Data Architecture
Token lifecycle (deprecated, renamed, …)	#623 — Token Lifecycle Metadata
Token structure, cascade, dimensions	#646 — Token Schema Structure and Validation
Machine-readable semantic rules (SPEC-NNN)	Tracking: #733

Open questions

Status update (April 2026): Most policy questions in this RFC are now answered by spec/evolution.md. The list below is restructured into Resolved (with a pointer to the normative source) and Still open.

Resolved

• Spec versioning scheme — SemVer adopted; current label 1.0.0-draft. See spec/evolution.md.
• Change classification — additive / clarifying / breaking categories defined in spec/evolution.md. New optional fields and new advisory rules are minor; tightening required-ness or removing fields is major.
• Compatibility contract — defined in spec/evolution.md: schemas at X.Y are a strict superset of X.0 for the same token shape; validators built for X.x accept all data valid under X.0.
• Coexistence during migration (dual-format) — legacy sets and cascade tokens coexist; resolution rules in spec/cascade.md and a legacy mapping table in spec/evolution.md.
• Deprecation window — NORMATIVE: a deprecated token MUST remain published for at least two minor versions before removal (spec/evolution.md §"Migration windows"); major-version escape hatch permitted. Full token-level lifecycle in #623.
• Rule catalog introduced_in — every rule in rules/rules.yaml carries introduced_in (e.g. "1.0.0-draft"); SPEC-001 through SPEC-014 implemented.

Still open

• Schema $id / URI strategy — no formal policy yet; v0 URIs in use de facto. Tracked via #720.
• Rule severity / retirement policy — can a rule's severity change (warning → error) without a major spec bump? How are rules retired (removed vs marked deprecated)? Not yet codified.
• SDK behavior across spec versions — runtime selection (--spec-version flag, validate-against-pinned vs validate-with-latest) not yet implemented.
• Cross-repo upgrade timeline — foundation upgrade-bot specifics, minimum adoption windows for old spec versions, automated upgrade PR triggers — deferred.

Phase alignment (non-binding)

• Phase 0: Decide structural hooks: spec version in overview, $id strategy, introduced_in on rules (see linked issues).
• Phase 2+: Finalize full policy while implementing first format migration (e.g. sets → cascade); see #729 and the dedicated implementation issue for evolution policy.

Inspiration (informative)

Other ecosystems handle “schema as contract” differently (e.g. strict immutability vs semver). This RFC should pick an approach that fits Spectrum’s backward-compat and multi-repo constraints—not adopt another stack wholesale.

---

Please comment with preferences, constraints from Adobe org process, and links to prior art.

[GarthDB]

Tracking

• Implementation issue for full evolution policy: #736 (Phase 2: Cascade + Resolve)

Phase 0 issue updates (structural hooks aligned with this RFC):

• #716 — spec version + pointer here
• #720 — $id URI versioning decision
• #733 — introduced_in on each rule

[GarthDB]

Decision / next sequencing (maintainer note, Mar 2026)

Phase 1 design-data tooling is now on main (Rust validate / migrate verify, rule catalog through SPEC-007, packages/tokens Moon tasks, Version Packages release via #739).

Chosen order for upcoming work

1. Spec evolution policy & migration contract (this discussion) — Do this before deep Phase 2 implementation so cascade/resolution behavior has a clear versioning and migration story (SemVer layers, changelog expectations, optional future design-data --spec-version, migration windows).
2. Phase 2: cascade token format + resolution engine — Start after the policy doc is sketched enough to gate schema/tooling changes.

This matches the project board item Define spec evolution policy and migration contract (still Todo) and unblocks Phase 2 without rework.

[GarthDB]

Resolution: Versioning and Evolution Policy

PR #793 resolves the open questions in this RFC. The normative outcome is spec/evolution.md. Closes #736.

Decisions on open questions

1. Spec versioning scheme — SemVer. Currently 1.0.0-draft. Published artifacts align with MAJOR (breaking) / MINOR (additive) / PATCH (clarifications).

2. Change classification

• Minor: new tokens, new optional fields, deprecations, rule severity relaxed, new enum values
• Major: token removals, required fields added, fields removed/type-changed, constraint tightening
• Patch: typo fixes, clarifications, test fixture additions

3. foundationVersion compatibility contract — Validators for X.Y accept all data valid under X.0. replaced_by (UUID-based) provides machine-readable migration paths between token versions.

4. Schema $id strategy — Unversioned v0 path (decided in Phase 0). Future 1.0.0 may introduce v1 paths.

5. Rule catalog evolution — introduced_in per rule (already present). Severity changes (warning to error) are major. Rules are retired via deprecation, not removal.

6. Coexistence during migration — Cascade format is the authoritative source. Legacy output (@adobe/spectrum-tokens) is generated from it: deprecated: "3.2.0" maps to deprecated: true, replaced_by maps to renamed, plannedRemoval/introduced are dropped. Both formats published simultaneously.

7. SDK behavior across spec versions — Validate against the current spec version. --spec-version CLI flag deferred to future work (no platform consumers yet).

8. Cross-repo upgrade timeline — Deferred. No platform consumers are pinning foundation versions yet. Automated upgrade PRs will be designed when the first platform repo adopts the SDK.

Migration windows

Deprecated tokens must remain for at least 2 minor versions before removal. Major version releases may clean up all accumulated deprecations. If plannedRemoval is set, it overrides the default window.

Token lifecycle fields

See the resolution comment on #623 for the full lifecycle model (deprecated as version string, replaced_by, plannedRemoval, introduced).