Editor Schema¶
Sonda publishes a JSON Schema for the v2 scenario file format. Point your editor at it and you get key completion, hover documentation pulled from the Rust doc comments, and a red underline on a misspelled field — before you run anything.
The schema lives at:
Try it without setting anything up
The playground editor already reads this file. Press Ctrl+Space in its YAML pane to see the same completions you will get locally once you have wired the schema up below.
Per-file, no configuration¶
The quickest way, and the one that travels with the file. Add a modeline comment as the first line of any scenario:
# yaml-language-server: $schema=https://davidban77.github.io/sonda/schema/sonda-scenario.schema.json
version: 2
kind: runnable
scenarios:
- signal_type: metrics
name: cpu_usage
rate: 10
duration: 60s
generator:
type: sine
amplitude: 50.0
period_secs: 30
offset: 50.0
The comment is understood by the YAML language server that backs the VS Code
YAML extension, Neovim's
yamlls, Helix, and Zed. Sonda ignores it — it is a YAML comment.
Per-project, by filename pattern¶
If your scenarios follow a naming convention, wire the schema up once instead of per file.
In .vscode/settings.json:
The schema is a plain file. Vendor it and point at the local copy:
Or generate it from the source you are building against, which is what the repository's own copy is produced by:
--all-features matters: the optional delivery features add config shape, so a narrower
build emits a schema that rejects sink config a release binary accepts.
What the schema checks, and what it does not¶
The schema is an authoring aid. sonda itself remains the validator, and it enforces rules that
JSON Schema cannot express. A file your editor is happy with can still be rejected when you run
it.
| Checked by the schema | Checked when you compile the scenario | Checked only when it runs |
|---|---|---|
| Unknown or misspelled field names | id uniqueness across entries |
Encoder precision being 0–17 |
Unknown kind:, generator type:, encoder type:, sink type: |
after.ref and while.ref pointing at an entry that exists |
|
Structural shape — scenarios: is a list, labels: is a mapping |
delay: requiring a while: on the same entry |
|
The while.op operator being one of < or > |
generator: and pack: being mutually exclusive |
|
| Required fields being present | Dependency cycles in after: chains |
|
The two shapes delay.close: accepts |
Unresolvable pack: references |
The middle column is what sonda --dry-run run <file> reports — it compiles the scenario and prints
the resolved plan without emitting anything:
--dry-run is not a full validator
The third column is genuinely deferred to run time, and --dry-run will tell you a file is OK
when it is not. A scenario with precision: 99 passes dry-run and then fails on sonda run
with encoder precision must be 0..=17, got 99. There is no single command that checks
everything short of running the scenario.
Scalar types are deliberately loose¶
You will notice the schema accepts a number or a boolean almost anywhere it accepts a string — so
status: 200 under labels: is not flagged, even though a label value is a string.
That is on purpose, and it matches the parser. Sonda's YAML loader coerces any plain scalar into
a string field, so status: 200 becomes the label value "200" and the file runs. A schema that
insisted on "type": "string" would underline working scenarios in red — including several in
this repository's own examples/ directory. Over-rejection is the one failure that makes a schema
worse than no schema, so the schema follows what Sonda accepts rather than what the Rust types
declare.
The exceptions are fields whose parser takes a string only, where the schema takes a string only
too. Durations are the largest group: a duration takes a unit everywhere, so Sonda refuses
duration: 10 and a flap's phase: 0; write 10s and 0s. at in gap_windows: and open in
delay: also take a bare 0. The OIDs and the SNMPv3 passwords and engine ID are strings only as
well.
Keeping up with your version¶
The published schema tracks the latest release. If you pin an older sonda, generate the schema
from that version rather than fetching the published one — the --example scenario_schema
invocation above works from any checkout or crate source.
The schema is generated from the same Rust types the parser deserializes into, and the repository
holds a test that fails if the committed copy falls behind them, plus a corpus check that every
scenario under examples/ still validates. It cannot quietly describe an older format.