Declarative scenario format

Scenarios are normally assembled through the typed builders in scenario-core. The scenario-format crate adds the declarative form (spec §33, §68): a versioned JSON envelope around the same typed Scenario model, parsed and validated before execution.

Document shape

{
  "$schema": "https://crucible.dev/schemas/scenario.schema.json",
  "format": "crucible-scenarios/scenario",
  "schema_version": 1,
  "scenario": { "...the Scenario body..." }
}

• format must equal crucible-scenarios/scenario; anything else is rejected with a structured error.
• schema_version must equal the version this build supports (1). A newer document is refused, never silently partially read.
• The envelope is strict: unknown keys are rejected so a typo cannot change document semantics.
• scenario is the serialized Scenario — field names and shapes are exactly what scenario-core serializes. Reference documents live in examples/declarative/.

Validation before execution

Parsing is validation-first. ScenarioDocument::from_json enforces, in order:

1. well-formed JSON,
2. supported format id,
3. supported schema version,
4. typed deserialization of the body,
5. the shared semantic validator (Scenario::validate_semantics): unique operation ids, non-dangling proof targets and expectations, no confidential field names in proof public inputs, positive timeouts, non-empty invariant keys.

The semantic validator is the same one the builder runs, extracted so declarative and programmatic scenarios follow one rule set — a declarative document cannot be “more permissive” than a builder-built one. Invalid documents fail before any execution could mutate state (spec §68).

Schema files

schemas/scenario.schema.json documents the envelope, and schemas/scenario-step.schema.json documents one operation step, for external tooling. The repository’s enforcement point is the typed parser + semantic validator; the JSON Schema files are the interoperable contract.

CI coupling

The canonical examples are embedded in the crate and re-parsed by its tests and by crucible-scenarios validate, so the documented format, the examples, and the parser cannot drift apart.