DriftSys Schema Contracts

Validation schemas and agent contracts for DriftSys projects. Each schema is published to GitHub Pages and available as HTML for humans and raw markdown for agents.

Discovery Protocol

Identify the schema domain (project or markspec).
Navigate to the domain contract page.
Use the schema index to find the matching v1.json.
Validate payload against the schema before processing.
Parse required fields first, optional fields second.

Contracts

Contract	Description
project/	Minimal flat project manifest
markspec/	MarkSpec site API artifacts (12 schemas)

Schema Index

Contract	JSON Schema	Description
project	v1	Project manifest
markspec/lock	v1	Frozen sidecar metadata (`.markspec.lock`)
markspec/link-target	v1	Shared resolved-link target object
markspec/entry	v1	Typed entry detail payload
markspec/component	v1	BOM component detail payload
markspec/reference	v1	Reference entry payload
markspec/index	v1	Entry listing payload
markspec/bom	v1	BOM index (component summaries)
markspec/search	v1	Search records for client indexing
markspec/traceability-matrix	v1	Full traceability matrix rows
markspec/traceability-graph	v1	Graph nodes and edges
markspec/coverage	v1	Coverage summary and gaps
markspec/diagnostics	v1	Validation and build diagnostics

Usage

Reference a schema from your project file to get autocompletion and validation in your editor.

YAML

Uses the $schema key — supported by the Red Hat YAML extension (VS Code) and IntelliJ.

# project.yaml
$schema: https://driftsys.github.io/schemas/project/v1.json

name: com.company.dash
description: Cross-platform SDK for the Dash service
category: library
version: 1.4.2

TOML

Uses the #:schema comment directive — supported by taplo and the Even Better TOML extension (VS Code).

# project.toml
#:schema https://driftsys.github.io/schemas/project/v1.json

name = "com.company.dash"
description = "Cross-platform SDK for the Dash service"
category = "library"
version = "1.4.2"

JSON

Uses the $schema property — supported natively by VS Code and IntelliJ.

{
  "$schema": "https://driftsys.github.io/schemas/project/v1.json",
  "name": "com.company.dash",
  "description": "Cross-platform SDK for the Dash service",
  "category": "library",
  "version": "1.4.2"
}

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.

Post-clone setup

Run ./bootstrap after git clone or git worktree add.