Conformance

The spec ships with a language-agnostic conformance suite under conformance/. Every Sightmap SDK port is expected to pass it. The fixtures are the executable definition of “conforming” — when prose and the suite disagree, the suite wins until prose is updated.

What gets tested

Each fixture is a numbered directory with a simulated .sightmap/ and an expected.json of test cases. The current set covers the load-bearing behavior of stream 1:

#	Fixture	Exercises
001	minimal	Smallest valid sightmap; basic match
002	multi-file-merge	Same view name across two files emits a merge-collision-view warning
003	route-precedence	First-match-wins on * vs ** vs literal
004	param-normalization	Express-style :param normalizes to *
005	selector-array	Array selectors try alternates in order
006	view-scoped-vs-global	Globals match everywhere; scoped only on their view
007	request-method-filter	match filters requests by HTTP method

Fixtures numbered 100+ exercise the formatter (fmt) — quoting, key order, list sorting, comment and header preservation, idempotence. Those are SDK-tooling concerns, not stream-1 semantics.

The runner asserts that every key in expected is present in the actual output and matches deeply. Extra keys are allowed, so the suite is forward-compatible with new optional output.

Running it locally

The reference runner ships in @sightmap/sightmap:

pnpm add -D @sightmap/sightmap
pnpm sightmap conformance ./path/to/spec/conformance

For a port in another language, implement a runner that loads each fixture’s sightmap/ directory, executes the listed command with args, and asserts the result matches expected. The shape of expected.json is documented in conformance/README.md.

Contributing a fixture

1. Create the next-numbered directory under conformance/.
2. Author sightmap/*.yaml and expected.json.
3. Run the conformance runner from any SDK to verify it passes.
4. Open a PR against sightmap/spec.

Good fixture candidates: a behavior the spec mandates that no current fixture exercises, an edge case you hit while implementing an SDK, or a regression you want pinned.

Tip

Fixtures are the cheapest way to influence the spec. A failing fixture in a PR forces the conversation about whether the spec or the SDK is wrong, before either gets entrenched.

Next

The full field-by-field contract is in the Schema reference. The machine-readable version is sightmap.schema.json.