[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 (to decide)

1. Spec versioning scheme

• Adopt SemVer for the spec package / published artifacts?
• How do we label pre-1.0 work (e.g. 1.0.0-draft) in spec/index.md once it exists?

2. Change classification

What changes are minor (backward compatible) vs major (breaking)?

• Additive: new optional properties on tokens, new optional rules, new enum values in registry — always minor?
• Deprecation: token or rule deprecated — minor with a migration window?
• Removal or constraint tightening: removing a property, making a field required, tightening a type — major?

3. Compatibility contract for foundationVersion

From #715, manifests pin a foundation version. What does the pin guarantee?

• Validators built for foundation 3.x accept all data valid under 3.0?
• Schemas at 3.2 are a strict superset of 3.0 for the same token shape?
• How do we express “this platform repo validates against spec X.Y” vs “consumes tokens at format Z”?

4. Schema $id / URI strategy

Two common patterns (both valid starting points for discussion):

• Versioned path: e.g. …/schemas/v1/token.schema.json — explicit in the URL; major bumps may introduce new paths.
• Unversioned path + metadata: keep stable $id URLs; carry spec version in schema metadata or a wrapper document.

Phase 0 implementation work should pick one early (see #720).

5. Rule catalog evolution

For rules/rules.yaml (SPEC-001, …):

• introduced_in (spec version) per rule — required from day one?
• Can severity change (warning → error) without a major spec bump?
• How are rules retired (removed vs marked deprecated)?

6. Coexistence during migration

• Dual-format periods: e.g. legacy sets vs cascade tokens — how long both are accepted?
• Does each file carry a format or spec version discriminator?
• How does the validator choose which structural schema + rules apply?

7. SDK behavior across spec versions

• Validate strictly against pinned foundation spec version?
• Or always validate with latest SDK and emit migration suggestions?
• Should the CLI support --spec-version for CI reproducibility?

8. Cross-repo upgrade timeline

• Who triggers automated upgrade PRs after a foundation release?
• Is there a minimum adoption window before old spec versions are unsupported?

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).