Skip to main content
Sightmap versions the spec stream and the project independently. The spec stream identifies the contract an implementation supports. Project SemVer covers repository releases, including documentation, schema clarifications, examples, and tooling. A project release does not require a new spec stream. The project can move through 0.x, 1.0.0, and later releases while the spec remains at stream 1.

​
Version summary

  • The spec stream version (version: 1) bumps only on breaking changes to the YAML format.
  • The project semver bumps as spec/v1/ matures: 0.x while we tighten in place, 1.0.0 once we commit to compatibility, 2.0.0 only if spec/v2/ ever ships.
  • We support the previous spec stream for at least 12 months after a successor stream is released.

​
Pre-1.0 (today)

The project is at 0.1.0. Per SemVer 0.x semantics:
  • The shape of spec/v1/ may tighten or clarify in place.
  • Such changes are announced in CHANGELOG.md and a Discussion before they land.
  • We won’t introduce a version: 2 until the project hits 1.0.0 and we have a real break to commit to.
When the project reaches 1.0.0, the rules below become commitments rather than guidance.

​
What counts as a breaking change to the spec stream

These require bumping version: 1 → version: 2 and creating spec/v2/:
  • Removing or renaming a field
  • Changing the type of a field (e.g. string → array)
  • Making a previously optional field required
  • Changing route-matching semantics (*, **, :param) in a way that alters existing matches
  • Changing the file-merge rules under .sightmap/
  • Any change that could make a previously valid .sightmap/ directory produce different behavior in a conforming implementation
Every breaking change requires an accepted SEP, explicit maintainer consensus, and a migration path.

​
Changes that do not bump the spec stream

These can land within stream 1 and ship as a project minor or patch bump:
  • Adding a new optional field at any level
  • Adding a new top-level key (a new peer to views, components, requests)
  • Adding a new match kind that is opt-in via a new field
  • Tightening validation to reject input that was always underspecified — pre-1.0 these land freely; post-1.0 they get a deprecation window
  • Clarifying wording that doesn’t change conforming behavior

​
Additive fields and older implementations

The JSON Schema sets additionalProperties: false at every level. Conforming implementations MUST reject unknown fields instead of ignoring, defaulting, or migrating them.
A document that uses a newly added optional field is schema-invalid under older implementations, even though adding the field is “not a breaking change” and version: stays 1.
The stream version identifies the contract a file targets, not its schema revision. Additive and reductive schema changes therefore require coordinated releases:
  • Tooling releases that understand the new field ship before sightmaps in the wild start using it.
  • Adopters who pin a vendored schema copy or an older CLI should upgrade before authoring the new field.
  • CI that validates against a pinned schema (see JSON Schema) rejects an unknown field.

​
Support windows

  • Current spec stream: fully supported. Bug fixes, clarifications, new examples, new optional fields.
  • Previous spec stream: supported for at least 12 months after the successor is released. Security fixes and clarifications only.
  • Older than that: best-effort. Implementations may choose to drop support.

​
Canonical document

spec/VERSIONING.md defines how to create a spec stream, apply the deprecation window, and dispatch on version:. On any disagreement, that file wins.