> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sightmap Versioning Policy: Spec Stream vs Project SemVer

> Distinguish the integer spec stream from project SemVer and determine which changes require a new stream.

Sightmap versions the spec stream and the project independently.

|                 | Versioned by                                    | Current | Bumps when                                               |
| --------------- | ----------------------------------------------- | ------- | -------------------------------------------------------- |
| **The spec**    | A single integer in the YAML `version:` field   | `1`     | A breaking change to the YAML format                     |
| **The project** | [SemVer](https://semver.org/) (GitHub Releases) | `0.1.0` | A project release; patch, minor, or major follows SemVer |

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.

<Warning>
  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`.
</Warning>

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](/reference/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`](https://github.com/sightmap/sightmap/blob/main/spec/VERSIONING.md) defines how to create a spec stream, apply the deprecation window, and dispatch on `version:`. On any disagreement, that file wins.