Stability and the road to 1.0

DSDS 0.13.0 is a pre-1.0 draft. This page is the contract around that status: what can change and how you will be told, what will never change, the complete list of known breaking changes still to come, and the conditions under which 1.0 is declared. The goal is that an adopter can read this page and price the risk of adopting now.

What never changes

Published schema URLs are immutable. Every released version is served under its own path (https://designsystemdocspec.org/v0.13.0/…), and a released path is never edited or removed. A document that pins its $schema to a released URL will validate against exactly that schema forever. Adopting DSDS at any version is therefore safe in the narrow sense: your documents cannot be broken retroactively — only left behind.

Version semantics

Change	Version bump	Your documents
Documentation-only edits	none	Unaffected
Additions and loosenings (new optional fields, new union members, relaxed constraints)	patch	Remain valid unchanged
Tightenings and behavior changes (new constraints, new required fields, moved fields)	minor	May need edits; a changelog entry lists every affected position
Renames and removals	major (post-1.0) / batched minor pre-1.0	Migration script provided

Pre-1.0, minors carry tightenings without a deprecation window — that is what pre-1.0 means here. Post-1.0 this table hardens into the contract described below.

Deprecation policy

From 0.13.0 onward, a form scheduled for removal is: (1) marked deprecated: true in the schema where JSON Schema supports it, (2) flagged by a lint rule (warning, never blocking), (3) documented with its replacement in the schema description, and (4) kept validating for at least one further minor release. Removals happen only in the release that executes the breaking backlog below, and each removal ships with a migration script (scripts/migrate-to-*.js — the mechanism used for every past migration).

Currently deprecated: link's inter-entity reference form (identifier/role/required — use relationships; lint rule DSDS-010), and chunk's top-level guidelines/useCases shorthand (use documentBlocks).

The breaking backlog — everything 1.0 will change

This is the complete list of known breaking changes, drawn from the recorded naming exceptions and deprecation notices. They will be executed together in one breaking window (0.14.0) rather than dripped across releases, each with a migration script.

#	Change	Today	At 0.14.0
1	Block-kind casing	useCases	use-cases
2	Procedural entry naming	stepEntry.title (string)	label (richText), matching checklistItem
3	Scale step naming	scaleStep.label	name, matching sibling entries
4	System info naming	systemName / systemVersion	name / version
5	Status prose property	description on status object forms	note, matching lastUpdated/lastReviewed/docOrigin
6	Event payload naming	apiEvent.returns	payload
7	Remove link's deprecated inter-entity surface	validates with DSDS-010 warning	removed; relationships only
8	Remove chunk's top-level guidelines/useCases	validates, marked deprecated	removed; documentBlocks only
9	Graduate draft metadata fields	governance / docOrigin marked "initial draft"	shapes frozen

Nothing else is planned to break. A breaking change not on this list would itself be treated as a defect in this contract.

Criteria for declaring 1.0

1.0 is declared when all of the following hold, and not before:

The breaking backlog is executed — the 0.14.0 window has shipped with its migration scripts, and at least one subsequent minor has passed without new entries being added to the backlog.
The draft fields have survived contact — governance and docOrigin have been exercised by real documentation for a full review cycle without shape changes.
A second independent consumer exists — at least one tool not maintained by the spec author reads or writes DSDS documents in earnest, so the spec's assumptions have been tested from outside.
The conformance surface is complete — the Conformance page's classes, the normative-statements index, and the negative-fixture suite are published as the versioned conformance kit for independent validators.

The post-1.0 contract

After 1.0: the 1.x line is additive only — new optional fields, new union members, new block kinds; nothing existing tightens, renames, or disappears. Anything breaking waits for 2.0, arrives deprecation-first (lint warning through at least two minors before removal), and ships with a migration script. The immutability guarantee above continues to apply to every released version.