Stability and the road to 1.0

DSDS 0.14.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 record of the executed breaking window, 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.14.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).

Nothing is currently deprecated: the 0.14.0 window removed both previously deprecated surfaces (link's inter-entity form and chunk's top-level shorthand).

The breaking backlog — executed at 0.14.0

The backlog below was announced in 0.13.0 and executed in full in the 0.14.0 breaking window, as this contract promised — together, once, with a migration script (scripts/migrate-to-0.14.js; run scripts/migrate-relationship-links.js first if your documents still carry relationship-flavored links).

#	Change	Before	Since 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	link's deprecated inter-entity surface	validated with DSDS-010 warning	removed; relationships only (DSDS-010 graduated to the schema)
8	Chunk's top-level guidelines/useCases	validated, marked deprecated	removed; documentBlocks only
9	Draft metadata fields	governance / docOrigin marked "initial draft"	shapes frozen

The backlog is now empty. No further breaking changes are planned before 1.0; a new entry here would restart the clock on criterion 1 below.

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.