MarkSpec Schema Contract

JSON Schema contracts for MarkSpec site API artifacts. Validate payloads against the matching schema before processing.

Discovery Protocol

Determine payload kind (entry, reference, component, index, search, matrix,

graph, coverage, bom, diagnostics, lock).

Select the matching v1.json from the schema index below.
Validate payload against the schema before parsing.
Parse required fields first, optional fields second.
Treat all schemas as closed unless they explicitly allow extension.
Stop on unknown version.

Schema Index

Contract	JSON Schema	What it describes	Stable key
markspec/lock	v1	Frozen sidecar metadata (`.markspec.lock`)	ULID map key
markspec/link-target	v1	Shared resolved-link target object	`displayId`
markspec/entry	v1	Typed entry detail payload	`id` (ULID) / `displayId`
markspec/component	v1	BOM component detail payload	`id` (ULID) / `displayId`
markspec/reference	v1	Reference entry payload	`id` (ULID) / `displayId`
markspec/index	v1	Entry listing payload	`entries[].displayId`
markspec/bom	v1	BOM index (component summaries)	`components[].displayId`
markspec/search	v1	Search records for client indexing	`displayId`
markspec/traceability-matrix	v1	Full traceability matrix rows	`rows[].displayId`
markspec/traceability-graph	v1	Graph nodes and edges	`nodes[].id`
markspec/coverage	v1	Coverage summary and gaps	`gaps[].displayId`
markspec/diagnostics	v1	Validation and build diagnostics	`code + location`

Validation Contract

Validate early so downstream logic stays predictable.

Validation must happen before business logic parsing.
Missing required fields means hard failure.
Unknown optional fields may be ignored only if the schema allows additional

properties.

If schema fetch fails, return a schema-unavailable error.

Failure Modes

unsupported-version — schema version is not recognized. Stop processing.
schema-unavailable — schema URL cannot be fetched. Return error.
validation-failed — payload does not match schema. Reject payload.
unknown-payload-kind — payload kind cannot be determined. Return error.

Version Policy

Breaking changes create a new major version path (v2.json).
Non-breaking additions stay in the current major version.
Consumers should pin to a major version.

Conventions

Each schema lives in /v1.json.
Schema-local docs live in /README.md.
Schema fixtures live in /tests/.
$id follows https://driftsys.github.io/schemas/markspec//v1.json.

Quick Example

Input kind: entry\ Schema: markspec/entry/v1.json

Validate payload against entry schema.
Parse required fields (displayId, type, title).
Parse optional fields (body, attributes, links, etc.).
Reject if version is unknown.