Skip to content

ADR 0012: Versioned schemas for profiles, scenarios, and tool I/O

  • Status: Accepted
  • Date: 2026-05-20
  • Authors: rmednitzer
  • Builds on: ADR 0003, ADR 0007

Context

Hardware profiles, scenario YAML, and the MCP tool I/O schemas are all external contracts. Without explicit versioning, a profile change that adds a required field silently breaks every existing scenario.

Decision

Each schema carries a top-level schema_version field. The Pydantic models in nous validate against the current version; an older version is upgraded by a small migration function (scripts/migrate_profile.py in L1). The JSON Schema artefacts under docs/schema/ (regenerated by make schema) declare the canonical shape and are committed to the repository.

schema_version follows the project's semver. A patch bump is forward-compatible (added optional fields). A minor bump is forward-compatible. A major bump requires a migration and an ADR.

Consequences

Easier: a contributor knows whether their profile change is breaking by looking at the field they added and the version field they bumped.

Harder: every schema change requires a coordinated bump; the make schema target catches drift in CI.

Revisit triggers

  • A schema needs to fork (e.g. land-borne vs. air-borne profiles). Then introduce a schema_kind field beside schema_version.