Skip to content

ADR-0005 — Scenarios are declarative YAML validated by a versioned schema

  • Status: Accepted
  • Date: 2026-10-14
  • Deciders: maintainer
  • Tasks affected: P1-T05, P2-T03, P2-T05, P7-T04

Context

Scenarios must be authored by robotics engineers, reviewed in pull requests, diffed, generated by tools (matrix sweeps, the world editor) and executed in CI. They describe world, vehicles, time, a timeline of events and assertions.

Decision

We will define scenarios as YAML documents with an apiVersion, validated by Pydantic models that also export JSON Schema. Expressions inside when: and assertions use a small, sandboxed expression language over topic fields and metrics. Extensibility is through registered plugins (events, assertions), not arbitrary code in the scenario file.

Alternatives considered

  • Python DSL — maximum power, but scenarios become code: hard to validate, diff semantically, or generate from a GUI.
  • OpenSCENARIO 2.0 — industry standard for automotive, heavy and road-centric; we borrow concepts (timeline, conditions) not the format.
  • BehaviorTree XML (as in scenario_execution) — good for sequencing, poor for declaring worlds, fleets and assertions in one place.

Consequences

  • Editor autocompletion and validation via JSON Schema; GUI can round-trip YAML.
  • Scenario schema is versioned independently with a migration path.
  • Complex logic lives in plugins with tests, keeping scenarios readable.