Esdieff documentation
Esdieff is a command-line toolkit and Rust library for connected-device models written in Semantic Definition Format, the SDF of IETF RFC 9880. It checks models, shows what a composed interface contains, compares revisions and turns model rules into test values. Model operations run offline on the documents you supply.
Where to start
- New to Esdieff? Install and try a model installs the command, runs the supplied thermostat model and reads your first generated values.
- Checking a model? Inspect and check a model supplies model files and shared definitions, runs the checks and follows each finding back to its source.
- Testing a device or an app? Test values against a model checks single samples, generates boundary and invalid values and checks a log of recorded values in one run.
- Reviewing a model change? Compare two revisions shows which changes between two revisions break the apps that use a device, and acknowledges the ones you intend.
- Running checks in CI? Repeat checks and share reports saves checks as plans, checks whole directories and brings results into automation with JSON, SARIF and Markdown.
- Building your own tool? Use the Rust library embeds the same checking, inspection and comparison in your own program.
- Looking up a command or option? See the command line reference.
- Something not working? See troubleshooting.
Esdieff works on model files and JSON values. It does not connect to devices or test network protocols.
More guides
Each guide walks through one task with real commands and their output.
- Resolve missing and ambiguous name references follows a finding to its authored reference and corrects the supplied catalogue.
- Follow a shared definition through a change connects effective uses and local overrides to a revision comparison.
- Compose and edit models builds a new
sdfThingfrom reusable definitions and makes repeatable edits to an existing document.
Reference
The reference pages are the contracts behind each command. They state what an operation promises, what its report contains and where its limits lie.
- Command line lists every command with its options and exit statuses.
- Workflow and report contract covers the shared report envelope, exit statuses and the command-line rules.
- Supplied source documents explains how supplied files become a catalogue and how source and effective views differ.
- Repeatable catalogue checks and Check a local model collection describe how to select local inputs.
- Model meaning assessment and its subpages define what each assessment level checks.
- Selected samples, Generated values and Recorded traces cover value checking.
- Model references document effective definitions and shared uses. JSON Schema export exports supported selected payload constraints.
- Composed sdfThing authoring, Authored-quality editing and Revision comparison cover changing and comparing models.
- The glossary defines the terms the reports and contracts use, such as catalogue, effective definition and breaking change.
How it works and why
How Esdieff works follows the process map from supplied files to model checks, revision comparisons and test values. The architecture decisions in the repository record why Esdieff behaves as it does, from exact numbers to client-side revision comparison. Contributing and project records links the contribution guide and the changelog.