Versioned identifiers
The proposed 1.0 document format uses visualSpec: "1.0". Its canonical schema identifier is https://visualspec.dev/schema/1.0/schema.json; the normative text lives at /specification/1.0/. The site and repository label this implementation as a release candidate. A versioned path is not evidence of independent ratification or a published stable release.
Consumers should pin the exact versioned schema they validate. A latest link is useful for discovery but should not be the only dependency in a reproducible build.
Three versions to distinguish
The document format version identifies the contract. An implementation version identifies a validator or renderer release. An asset or reference version identifies the evidence or resource used. Updating one does not automatically update the others.
Compatible evolution
Editorial clarification can improve prose without redefining previously valid behavior. Additive proposals must explain how existing consumers detect and preserve unsupported data. Changes to defaults, units, interpretation or required behavior need explicit compatibility review even when the JSON shape is unchanged.
Once a stable version is published, its normative semantics and artifacts must remain available. Corrections need a visible erratum or new version, not a silent replacement that changes existing documents.
Migration records
A migration should record its source and destination versions, changed paths, unresolved requirements and any loss of fidelity. Keep an unchanged copy of the source document. Validate both the new structure and the relationships affected by the transformation.
A successful migration is not guaranteed by replacing the visualSpec string. Component behavior, reference locators, coordinate assumptions and timing semantics may require explicit decisions.
Propose a change
Use the RFC process for changes to normative behavior, core fields, profiles or public compatibility commitments. Small documentation corrections can use a normal pull request.