Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command line

Every esdieff command reads the model files you name, does one job and reports the result on standard output. Model files are always supplied explicitly. Esdieff does not fetch the namespace URIs a model mentions.

$ esdieff check thermostat.sdf.json
$ esdieff generate --document thermostat.sdf.json thermostat.sdf.json

Run esdieff --help for a task overview and starting examples. Each command has its own help, such as esdieff sample --help, with examples, options and defaults. Run esdieff --version for the installed version.

For commands with --document, that option selects one of the supplied model files. The trailing paths supply the selected model and any dependencies. Use the same path spelling in both places.

Commands

CommandWhat it doesDetails
checkCheck models, or run a saved check planInspect and check a model
inspectShow one definition as written or as composedInspect and check a model
sampleCheck one JSON value against one descriptionSelected samples
generateGenerate test values from model rulesGenerated values
traceCheck a log of recorded valuesRecorded traces
diffCompare two revisionsRevision comparison
referenceWrite a Markdown reference for a Thing or ObjectGenerate a model reference
schemaExport JSON Schema for one descriptionExport JSON Schema
authorCompose a new sdfThing from reusable definitionsComposed sdfThing authoring
editReplace or remove qualities in an existing documentAuthored-quality editing

check

esdieff check [--directory DIR] [--recursive] [--exclude RELATIVE_PATH] [--root INPUT] [--assessment initial-v1|expanded-numeric-v1|expanded-consistency-v1|full-baseline] [--strict-warnings] [--format human|json|sarif] [INPUT...]
esdieff check --plan PLAN [--format human|json]

Checks the supplied model documents. At least one INPUT or --directory is required. INPUT is a file path, or - for one document on standard input.

OptionMeaning
--root INPUTCheck this document and the dependencies it needs. Without it, every supplied model document is checked.
--assessment PROFILEChoose how much to check. The default is initial-v1. Choose how much to check describes the profiles.
--strict-warningsFail the check on warnings as well as errors.
--directory DIRSelect the regular files directly in DIR whose names end in .sdf.json. Repeat it for several directories.
--recursiveDescend into the subdirectories of every supplied directory, including hidden entries.
--exclude RELATIVE_PATHLeave out a literal file or subtree, relative to each directory. Repeat it for several paths.
--format human|json|sarifChoose the report format.
--plan PLANRun the cases of a check plan instead of a direct check.

Check a local model collection states the directory selection rules and limits.

inspect

esdieff inspect [--view source|effective] --document INPUT --pointer POINTER [--required-declarations] [--strict-warnings] [--format human|json] INPUT...

Shows the definition at a JSON Pointer in one document. The default source view is the JSON as written. The optional effective view is the definition after sdfRef composition, with the origin of each quality. --required-declarations adds the declaration relationships selected by sdfRequired.

sample

esdieff sample --document MODEL --kind property|data|action_input|action_output|event_output|context --pointer POINTER --sample SAMPLE [--strict-warnings] [--format human|json] MODEL_INPUT...

Checks the JSON value in SAMPLE against the description that --kind and --pointer select in MODEL. The value is admitted, rejected or undetermined. Check one sample shows a run.

generate

esdieff generate --document MODEL [--kind property|data|action_input|action_output|event_output|context --pointer POINTER] [--format human|json|jsonl] MODEL_INPUT...

Generates test values for one selected description, or for every affordance description of MODEL when --kind and --pointer are left out. The two options come together or not at all. --format jsonl writes the values as JSON Lines that trace can check.

Automatic selection covers Properties and Action/Event data. Select Context explicitly with --kind context and --pointer. An unfinished human report shows retained reasons. JSON Lines contains settled values only, so check the exit status before treating the file as a complete corpus.

trace

esdieff trace --document MODEL --trace FILE [--format human|json] MODEL_INPUT...

Checks each entry of the JSON Lines file FILE against MODEL. FILE is a path, or - for standard input.

diff

esdieff diff --old PATH --new PATH [--recursive] [--exclude RELATIVE_PATH] [--perspective client|implementer] [--acknowledged FILE] [--acknowledgements-output FILE] [--replace-acknowledgements] [--format human|json|sarif|markdown]

Compares an earlier and a later revision. Both paths are files or both are directories, and directories pair their documents by relative path.

OptionMeaning
--perspective client|implementerClassify differences for clients built against the earlier model, which is the default, or for implementations of it.
--acknowledged FILERead a file of acknowledged differences, so only unacknowledged differences decide the result.
--acknowledgements-output FILEWrite the report’s eligible acknowledgement entries to a file for review.
--replace-acknowledgementsAllow --acknowledgements-output to replace an existing file.
--recursive, --exclude RELATIVE_PATHSelect documents in both directories as for check.
--format human|json|sarif|markdownChoose the report format. markdown writes a changelog.

Compare two revisions walks through a comparison and its acknowledgements.

reference

esdieff reference [--uses] --document MODEL --pointer POINTER INPUT...

Selects one effective Thing or Object and writes a Markdown reference to standard output. It does not check the model. --uses adds a section listing where a named definition is used across the supplied models. It also lets you select a reusable data, Property, Action, Event or Context definition.

schema

esdieff schema --document MODEL --kind KIND --pointer POINTER [--format json|schema] INPUT...

Exports the effective constraints of one selected description for use with JSON Schema tools. The default output is a JSON report. --format schema writes only the standalone schema.

author

esdieff author --plan PLAN --document-output DEST [--report-output DEST] [--check initial-v1|full-baseline] [--strict-warnings] [--format human|json] [--replace-document] [--replace-report] --source KEY PATH [--source KEY PATH ...]

Composes a new sdfThing from the definitions in the supplied sources, as the plan describes, and writes it to --document-output. Repeat --source KEY PATH for each model file. --check also checks the generated document. --report-output writes the report to a file instead of standard output. An existing destination is replaced only with --replace-document or --replace-report.

The human report confirms whether the document was written and explains any withholding. Generation and fidelity alone permit delivery when --check is omitted, and the report makes that unchecked status explicit.

edit

esdieff edit --plan PLAN --document-output DEST [--report-output DEST] [--check initial-v1|full-baseline] [--strict-warnings] [--format human|json] [--replace-document] [--replace-report] --source KEY PATH [--source KEY PATH ...]

Replaces or removes the qualities a plan names in one existing document and writes the result to --document-output. The options match author. Compose and edit models shows both commands.

Global options

OptionMeaning
--color auto|always|never, --color=MODEChoose terminal styling. The default is auto.
-h, --helpShow examples and options for the selected command, or the task overview when used alone.

esdieff --version, on its own, prints the installed version. For check, inspect, sample, generate, schema, reference and trace, put -- before a positional input path that begins with -.

Use - for standard input once across the model, sample and trace inputs of a command. diff never reads standard input.

Exit statuses

Every command exits with 0 when the requested work passed, 1 when a finding failed it, 2 for an invalid invocation, 3 when some work could not be settled, and 4 when a host or output operation failed. Use exit statuses has the full table and what each status means in CI.