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. Every operation runs offline on the files you supply.

Start here

• Install and try a model Install Esdieff, run the supplied thermostat model and read your first generated values.
• Inspect and check a model Supply model files and shared definitions, run the checks and follow each finding back to its source.
• Compare two revisions See which changes between two revisions break the apps that use a device, and acknowledge the ones you intend.
• Test values against a model Check single samples, generate boundary and invalid values and check a log of recorded values in one run.

Guides

The guides walk through one task each with real commands and their output.

• Compose and edit models builds a new sdfThing from reusable definitions and makes repeatable edits to an existing document.
• Repeat checks and share reports saves checks as plans, checks whole directories and brings results into automation with JSON, SARIF and Markdown.
• Use the Rust library embeds the same checking, inspection and comparison in your own program.

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.

• 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, Check a local model collection and Pinned document acquisition describe the ways to bring documents in.
• Model meaning assessment and its subpages define what each assessment level checks.
• Selected samples, Generated values and Recorded traces cover value checking.
• Composed sdfThing authoring, Authored-quality editing and Revision comparison cover changing and comparing models.

Design

The domain language defines the terms the reports and contracts use, such as catalogue, effective definition and breaking change. The architecture decisions record why Esdieff behaves as it does, from exact numbers to client-side revision comparison.

Install and try a model

This guide installs Esdieff and runs it on a supplied thermostat model. No device is needed, and nothing leaves your machine.

Install Esdieff

Esdieff supports macOS 15+, Linux and Windows. Prebuilt releases are available through Homebrew, apt and dnf, and as direct downloads.

macOS

Install the prebuilt command from the Esdieff Homebrew tap:

brew install pederbe/tap/esdieff

Update with brew update && brew upgrade esdieff. Remove it with brew uninstall esdieff.

Windows

Download the Windows ZIP, extract it, and add the folder containing esdieff.exe to your PATH. Open a new terminal and check the installation:

esdieff --version

To update, replace the extracted files with a newer release. To uninstall, remove the folder and its entry from your PATH.

A WinGet listing is being prepared. WinGet installation will become available after the community listing is approved.

Linux

Install on Debian, Ubuntu or Fedora:

curl -fsSL https://raw.githubusercontent.com/pederbe/esdieff/main/scripts/install.sh | sh

Updates arrive through your package manager.

Direct downloads and Cargo

Download a release archive, extract it and put the command on your PATH. Download a newer archive to update it. Remove the extracted command to uninstall it.

Rust users can install a prebuilt release with:

cargo binstall esdieff

To build from source, install a current Rust toolchain and run:

cargo install --locked esdieff

This builds the esdieff command and puts it in Cargo’s binary directory, normally ~/.cargo/bin. Make sure that directory is on your PATH.

From a checkout of the repository, install the same way with a path instead:

cargo install --locked --path .

Repeat the Cargo installation command to update. Use cargo uninstall esdieff to remove it.

Check that it works

$ esdieff --help
Usage:
esdieff check --plan PLAN [--format human|json]
esdieff acquire --github OWNER/REPOSITORY --commit COMMIT --path REPOSITORY_PATH --sha256 DIGEST --document-output DEST [--report-output DEST] [--format human|json]
esdieff check [--directory DIR] [--recursive] [--exclude RELATIVE_PATH] [--root INPUT] [--assessment initial-v1|expanded-modified-v1|expanded-units-v1|expanded-content-format-v1|expanded-pattern-syntax-v1|expanded-numeric-v1|expanded-consistency-v1|full-baseline] [--registry-knowledge recorded|withheld] [--strict-warnings] [--format human|json|sarif] [INPUT...]

The help continues with one line per command. If the command is not found, check that its installation folder is on your PATH and open a new terminal. Cargo installations normally use ~/.cargo/bin.

Try the thermostat example

The example is a room thermostat with two properties, one action and one event. Its writable targetTemperature accepts numbers from 5 to 30 °C in half-degree steps:

"targetTemperature": {
  "description": "Requested room temperature in half-degree increments",
  "type": "number", "nullable": false, "minimum": 5, "maximum": 30,
  "multipleOf": 0.5, "unit": "Cel", "readable": true, "writable": true
}

Download rich.sdf.json from the repository, or copy it from a checkout, and save it as thermostat.sdf.json in an empty directory. Take the rich model, not the smaller thermostat.sdf.json next to it in the repository: that one has no half-degree step, so it accepts 5.25. Then generate test values from its rules. The command names the document to generate for, followed by every model file to supply, which here is the same file:

$ esdieff generate --document thermostat.sdf.json thermostat.sdf.json
Generated values esdieff.generation/1: passed
Values: 15 admitted, 60 rejected, 0 undetermined
Descriptions: 4

property /sdfObject/Thermostat/sdfProperty/currentTemperature: complete
  ...

property /sdfObject/Thermostat/sdfProperty/targetTemperature: complete
  rejected     null          null (sample.null)
  admitted     minimum       5
  admitted     maximum       30
  rejected     below_minimum 4 (sample.bound)
  rejected     above_maximum 31 (sample.bound)
  rejected     not_multiple  5.25 (sample.multiple)
  rejected     wrong_type    "" (sample.type)
  rejected     wrong_type    true (sample.type)
  rejected     wrong_type    {} (sample.type)
  rejected     wrong_type    [] (sample.type)

action_input /sdfObject/Thermostat/sdfAction/configure: complete
  ...

The output is trimmed to the targetTemperature block. The full report lists 75 values across the two properties, the configure action input and the alarm event output.

Each line is one generated value. The middle column names the rule the value aims at, and the first column says what the model does with it:

• 5 and 30 aim at the minimum and maximum and are admitted. They are the boundary values a device must accept.
• 31 aims just above the maximum and is rejected, with the condition code sample.bound naming the rule it breaks.
• 5.25 is a quarter-degree value, so it is rejected by the half-degree step, sample.multiple.

Admitted and rejected are not guesses. Esdieff checks every generated value against the model the same way it checks a sample you supply, so the labels are what the model actually says. A value nobody can settle would be listed as undetermined.

Next, check the model itself. --assessment full-baseline requests every model obligation Esdieff records from RFC 9880:

$ esdieff check --assessment full-baseline thermostat.sdf.json
Esdieff: passed
Complete: true
Errors: 0; warnings: 0; notices: 0; incomplete checks: 0
Scope: catalogue
Broader RFC coverage: complete
Recorded registry policy: use_recorded
Unit guidance: complete
Assessment area unit-spelling/1: assessed
Assessment area unit-registry-guidance/1: assessed
Unit counts: known_primary 4; known_secondary 0; unknown 0; unavailable 0; legacy 0; uri_names 0
Assessment area content-format-syntax/1: not_applicable
Assessment area content-format-registry/1: not_applicable
Registry iana.senml-units: available; snapshot iana.senml-units/2026-10-05/6246352c590e933b; scope senml-units; entries_count 67
Registry extraction_policy esdieff.unit-section-positives/1; digest 6246352c590e933b72c25ef9f363171e40fea347bb7e23d08b04f9436894ed34; raw_digest 3eff03640c5a5d2abd09e330488aeb9fae0b2766ea69b1114295bbec5c44e754; source_updated 2026-02-02; retrieved_at 2026-10-05T16:49:51Z
Requested assessment: rfc9880/base-1
Baseline: rfc9880/base-1 (RFC 9880)
Acceptance restrictions: A001, A002; strict warnings: false
Requested sources: [1]
Requested inventory: esdieff.full-model/1
Requested coverage (assessment_area): total 13; assessed 10; not applicable 3; unassessed 0; undetermined 0
Requirement inventory: rfc9880.model/1
Requirement coverage: total 54; assessed 28; not applicable 26; unassessed 0; undetermined 0
Source 1 ["input1"]: acquired / usable (1932 retained bytes, content complete: true)
Diagnostic details omitted: 0

The first line is the verdict. Complete: true means nothing was left unfinished, and the coverage lines account for every one of the 54 recorded requirements as assessed or not applicable to this model. The unit lines show that the four Cel unit names were found in the recorded SenML units registry snapshot, so the check needed no network access. The command exits with status 0 for a passed check, 1 for findings, and 3 when something could not be settled.

Next steps

• Inspect and check a model supplies shared definitions, reads findings and follows them to their source.
• Test values against a model checks single samples, saves generated values as test vectors and checks recorded logs.
• Compare two revisions finds the changes that break the apps using a device.
• Repeat checks and share reports saves these checks as a plan and runs them in CI.

Inspect and check a model

This guide checks a model that reuses a shared definition, reads the findings and looks at what the composed interface contains. It assumes Esdieff is installed and uses the thermostat.sdf.json from that page, plus two small files shown below.

Supply the files a model needs

An SDF model can reference definitions in other documents. Esdieff resolves such references only among the files you supply on the command line, so a check sees exactly what you give it and never fetches anything. Together, the supplied files are the catalogue.

Save these two files from the repository’s directory-check example next to each other. The sensor’s reading property reuses a Reading type from the second file through its namespace types:

{
  "info": { "title": "Directory sensor" },
  "namespace": { "types": "https://example.com/directory/types" },
  "sdfObject": {
    "Sensor": {
      "sdfProperty": {
        "reading": { "sdfRef": "types:#/sdfData/Reading" }
      }
    }
  }
}

{
  "info": { "title": "Shared reading type" },
  "namespace": { "types": "https://example.com/directory/types" },
  "defaultNamespace": "types",
  "sdfData": { "Reading": { "type": "number", "minimum": 0 } }
}

Checking the device on its own cannot finish, because the referenced definition is not in the catalogue:

$ esdieff check device.sdf.json
Esdieff: undetermined
Complete: false
Errors: 0; warnings: 0; notices: 0; incomplete checks: 6
Scope: catalogue
...
reference.unavailable: supplied global target unavailable
effective 1 "/sdfObject/Sensor/sdfProperty/reading"
  related source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
  related source 1 "/sdfObject/Sensor/sdfProperty/reading"
coverage.unavailable: Requested assessment area has unfinished applicable work
...

The verdict is undetermined, not failed. Esdieff does not treat a missing dependency as a mistake in the model, and it never reports a definition as valid when it could not establish what it means. Supply both files, and name the device as the root so the check covers the device and whatever it needs:

$ esdieff check --root device.sdf.json device.sdf.json types.sdf.json
Esdieff: passed
Complete: true
Errors: 0; warnings: 0; notices: 0; incomplete checks: 0
Scope: selected
Broader RFC coverage: partial
Requested assessment: esdieff.initial/1
Baseline: rfc9880/base-1 (RFC 9880)
Acceptance restrictions: A001, A002; strict warnings: false
Requested sources: [1]
Requested inventory: esdieff.initial/1
Requested coverage (assessment_area): total 8; assessed 7; not applicable 1; unassessed 0; undetermined 0
Source 1 ["input1"]: acquired / usable (247 retained bytes, content complete: true)
Source 2 ["input2"]: acquired / usable (211 retained bytes, content complete: true)
Dependency sources: [2]
Diagnostic details omitted: 0

Scope: selected with Dependency sources: [2] records that the types file was used as a dependency of the root. Without --root, the scope is catalogue and every supplied file is checked in full, including definitions nobody uses. Both scopes are useful: catalogue scope for a collection you maintain, selected scope for one product and its dependencies.

Choose how much to check

--assessment selects an assessment level. The default initial-v1 covers the document envelope, names and roles, namespaces, composition, parameters and the other fundamentals in eight assessment areas. full-baseline requests all 13 areas and accounts for all 54 model requirements Esdieff records from RFC 9880, including unit names against a recorded registry snapshot and numeric contradictions. The expanded-* levels add one concern to the initial set, such as expanded-pattern-syntax-v1 for regular expressions. Two of them offer advice that full-baseline does not include. expanded-numeric-v1 finds number ranges that no integer or step value can satisfy, and expanded-consistency-v1 finds a const or default value that its own description excludes.

esdieff check --assessment full-baseline --root device.sdf.json device.sdf.json types.sdf.json

Every report says which inventory it assessed and how many areas were assessed, not applicable or undetermined, so a passed check always states what it covered. --strict-warnings turns warnings into a failed verdict, which is the setting to use in CI once a collection is clean. The model meaning contract and the assessment inventory describe each area.

Read findings and locations

A finding has a condition code, a message and a location. The example collection includes a draft with a broken type:

$ esdieff check draft/unfinished.sdf.json
Esdieff: failed
Complete: true
Errors: 1; warnings: 0; notices: 0; incomplete checks: 0
...
data.string: A textual data quality must contain a string
source 1 "/sdfData/Unfinished/type"
Diagnostic details omitted: 0

data.string is the stable code of the rule, and the message explains it. The location is a source location: source 1 is the first supplied file, and the JSON Pointer /sdfData/Unfinished/type is the member in that file. Findings come in four kinds. Errors fail the check, warnings and notices are advice that leave it passed unless --strict-warnings is set, and incomplete checks mark work Esdieff could not finish, which makes the verdict undetermined.

Some findings are about the composed interface rather than one file. The reference.unavailable finding earlier had an effective location, /sdfObject/Sensor/sdfProperty/reading, which is the property as the device presents it after references and overrides are applied. Its related source locations point at the sdfRef that caused it. The report contract describes both location kinds.

Inspect what the interface contains

esdieff inspect shows one definition in either view. The --view source form prints the member as written in the file, found by its JSON Pointer. The --view effective form prints the definition the device presents, with inherited qualities applied and RFC defaults filled in, and then lists where each quality came from. Inspect the thermostat’s target temperature:

$ esdieff inspect --view effective --document thermostat.sdf.json --pointer /sdfObject/Thermostat/sdfProperty/targetTemperature thermostat.sdf.json
Esdieff: passed
...
Inspection effective at "/sdfObject/Thermostat/sdfProperty/targetTemperature":
{"description":"Requested room temperature in half-degree increments","type":"number","nullable":false,"minimum":5,"maximum":30,"multipleOf":0.5,"unit":"Cel","readable":true,"writable":true}
Alternatives absent at effective 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature"
source at effective 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature"; source 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature"
default true at effective 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature/observable"
source at effective 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature/description"; source 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature/description"
...

The report before the inspection is trimmed. Every quality of this property is authored in the file itself, and observable is absent in the source, so the view records that its RFC default of true applies.

The sensor’s reading is more interesting, because its content comes from the other file:

$ esdieff inspect --view effective --document device.sdf.json --pointer /sdfObject/Sensor/sdfProperty/reading device.sdf.json types.sdf.json
...
Inspection effective at "/sdfObject/Sensor/sdfProperty/reading":
{"type":"number","minimum":0}
Alternatives absent at effective 1 "/sdfObject/Sensor/sdfProperty/reading"
inherited at effective 1 "/sdfObject/Sensor/sdfProperty/reading"; source 2 "/sdfData/Reading"; source 1 "/sdfObject/Sensor/sdfProperty/reading"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
default true at effective 1 "/sdfObject/Sensor/sdfProperty/reading/readable"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
default true at effective 1 "/sdfObject/Sensor/sdfProperty/reading/writable"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
default true at effective 1 "/sdfObject/Sensor/sdfProperty/reading/observable"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
default true at effective 1 "/sdfObject/Sensor/sdfProperty/reading/nullable"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
inherited at effective 1 "/sdfObject/Sensor/sdfProperty/reading/type"; source 2 "/sdfData/Reading/type"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"
inherited at effective 1 "/sdfObject/Sensor/sdfProperty/reading/minimum"; source 2 "/sdfData/Reading/minimum"; imported at source 1 "/sdfObject/Sensor/sdfProperty/reading/sdfRef"

Each inherited line names the file and pointer the quality came from, and imported at names the sdfRef that brought it in. This is how you see whether a supplier’s property really has the bound you expect and which shared definition sets it.

The catalogue-check example works the same way for a reusable sdfData definition:

$ esdieff inspect --view effective --document count.sdf.json --pointer /sdfData/Count count.sdf.json
...
Inspection effective at "/sdfData/Count":
{"type":"integer","minimum":0,"maximum":100}
Alternatives absent at effective 1 "/sdfData/Count"
source at effective 1 "/sdfData/Count"; source 1 "/sdfData/Count"
default true at effective 1 "/sdfData/Count/nullable"
source at effective 1 "/sdfData/Count/type"; source 1 "/sdfData/Count/type"
source at effective 1 "/sdfData/Count/minimum"; source 1 "/sdfData/Count/minimum"
source at effective 1 "/sdfData/Count/maximum"; source 1 "/sdfData/Count/maximum"

Add --required-declarations to list which contained definitions an owner declares as required through sdfRequired, and --format json to get the same views as JSON for scripts.

Follow a finding to its source

A finding’s source location is a pointer you can inspect directly. Take the draft’s data.string finding at /sdfData/Unfinished/type and look at its owner:

$ esdieff inspect --view source --document draft/unfinished.sdf.json --pointer /sdfData/Unfinished draft/unfinished.sdf.json
...
Inspection source at "/sdfData/Unfinished":
{ "type": 7 }

The source view prints the member byte for byte as it appears in the file, so what you see is what you need to fix. For a finding with an effective location, inspect the effective pointer first to see the composed definition, then use its inherited and imported at lines to find the file to change. Source inspection also works when a check failed or could not finish, so you can always look at what was supplied.

Where to go next

• Repeat checks and share reports saves these commands as a plan, checks whole directories and emits JSON and SARIF.
• Compare two revisions follows a changed shared definition to every device that uses it.
• The supplied source documents reference explains catalogues, roots and views in full.

Compose and edit models

This guide builds a new device description from reusable definitions and then makes repeatable edits to an existing document. Both commands read a small JSON plan, write a new file and leave every input unchanged. It assumes Esdieff is installed.

Compose a thing from reusable objects

In SDF, an sdfObject describes one capability and an sdfThing groups objects into a product. esdieff author creates a new sdfThing document whose objects reference the reusable ones through sdfRef, so the new document stays linked to its sources instead of copying them.

Save a reusable capabilities document as capabilities.sdf.json:

{
  "info": { "title": "Reusable climate capabilities" },
  "namespace": { "cap": "https://example.com/capabilities" },
  "defaultNamespace": "cap",
  "sdfObject": {
    "Thermostat": {
      "description": "Reusable thermostat capability",
      "sdfProperty": {
        "targetTemperature": {
          "type": "number", "nullable": false, "minimum": 5, "maximum": 30,
          "multipleOf": 0.5, "unit": "Cel", "readable": true, "writable": true
        }
      }
    },
    "Fan": {
      "sdfProperty": {
        "speed": { "type": "integer", "minimum": 0, "maximum": 3 }
      }
    }
  }
}

Then write the recipe as recipe.json. It names the new thing, binds the namespace prefixes the generated document will use, and declares each object: a name in the new thing, the supplied source and pointer to copy the reference from, the prefix that reference should use, a refinement patch and whether the object is required. The thermostat refinement lowers the maximum to 25 for this product:

{
  "key": "climate-recipe",
  "generated_key": "climate-unit",
  "thing_name": "ClimateUnit",
  "info": { "title": "Climate unit" },
  "namespace": {
    "cap": "https://example.com/capabilities",
    "product": "https://example.com/products"
  },
  "default_namespace": "product",
  "objects": [
    {
      "name": "thermostat",
      "source": "capabilities",
      "pointer": "/sdfObject/Thermostat",
      "prefix": "cap",
      "refinement": { "sdfProperty": { "targetTemperature": { "maximum": 25 } } },
      "required": true
    },
    {
      "name": "fan",
      "source": "capabilities",
      "pointer": "/sdfObject/Fan",
      "prefix": "cap",
      "refinement": {},
      "required": false
    }
  ]
}

source matches the key you give the file with --source KEY PATH. The key and generated_key name the request and the generated document in reports. Run the recipe, and ask for an initial check of the result in the same step:

$ esdieff author --plan recipe.json --source capabilities capabilities.sdf.json --document-output climate-unit.sdf.json --check initial-v1
Author ClimateUnit: passed
Generation: complete
Fidelity: established
Broader RFC coverage: partial
Errors: 0; warnings: 0; notices: 0; unfinished authoring units: 0
Baseline: rfc9880/base-1
Selected generated root: 2
Dependency sources: 1
Sources with attempted work: 2, 1
Unavailable required sources: none
Source 1 "capabilities": Model, Acquired
Source 2 "climate-unit": Generated, Generated
Requested checking esdieff.initial/1: passed (0 incomplete assessment units)
Requested check inventory: esdieff.initial/1
Requested check coverage (assessment_area): total 8; assessed 8; not applicable 0; unassessed 0; undetermined 0

Generation: complete says the document was assembled, and Fidelity: established says Esdieff verified that every generated reference still points at its source and every refinement value kept its exact spelling. The document is written only when both hold and the requested check passes. Here is the generated climate-unit.sdf.json:

{
  "namespace": {
    "cap": "https://example.com/capabilities",
    "product": "https://example.com/products"
  },
  "defaultNamespace": "product",
  "info": {
    "title": "Climate unit"
  },
  "sdfThing": {
    "ClimateUnit": {
      "sdfObject": {
        "thermostat": {
          "sdfRef": "cap:#/sdfObject/Thermostat",
          "sdfProperty": {
            "targetTemperature": {
              "maximum": 25
            }
          }
        },
        "fan": {
          "sdfRef": "cap:#/sdfObject/Fan"
        }
      },
      "sdfRequired": ["thermostat"]
    }
  }
}

The thermostat keeps its link to the capabilities document and overrides only the maximum. Inspect the effective property to confirm what the product presents, supplying both files:

$ esdieff inspect --view effective --document climate-unit.sdf.json --pointer /sdfThing/ClimateUnit/sdfObject/thermostat/sdfProperty/targetTemperature climate-unit.sdf.json capabilities.sdf.json
...
Inspection effective at "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfProperty/targetTemperature":
{"type":"number","nullable":false,"minimum":5,"maximum":25,"multipleOf":0.5,"unit":"Cel","readable":true,"writable":true}
...
override at effective 1 "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfProperty/targetTemperature/maximum"; source 1 "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfProperty/targetTemperature/maximum"; source 2 "/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum"; imported at source 1 "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfRef"
inherited at effective 1 "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfProperty/targetTemperature/multipleOf"; source 2 "/sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf"; imported at source 1 "/sdfThing/ClimateUnit/sdfObject/thermostat/sdfRef"

The maximum is an override from the generated document, and the step is inherited from the capabilities file. Running the same command again refuses to overwrite the output until you add --replace-document:

$ esdieff author --plan recipe.json --source capabilities capabilities.sdf.json --document-output climate-unit.sdf.json --check initial-v1
esdieff: existing output requires explicit replacement of a regular non-symlink file

Use --report-output report.json --format json to save the report beside the document, and --check full-baseline for the complete assessment. A refinement member set to null deletes the inherited member. The authoring contract lists every plan field, the refinement rules and the limits.

Edit qualities in an existing document

esdieff edit changes named qualities of definitions you already have, such as a description, a bound or a unit, and writes a new document. It is a way to make the same correction repeatably, review it as a plan and keep the original untouched.

Starting from the thermostat model as thermostat.sdf.json, save this plan as edits.json. Each edit names the definition that owns the quality, the quality, and either a replacement value or a removal:

{
  "key": "winter-edits",
  "source": "thermostat",
  "generated_key": "thermostat-winter",
  "edits": [
    {
      "owner": "/sdfObject/Thermostat/sdfProperty/targetTemperature",
      "quality": "maximum",
      "operation": "replace",
      "value": 25
    },
    {
      "owner": "/sdfObject/Thermostat/sdfProperty/targetTemperature",
      "quality": "description",
      "operation": "replace",
      "value": "Requested room temperature in half-degree increments, capped for winter"
    },
    {
      "owner": "/sdfObject/Thermostat/sdfProperty/currentTemperature",
      "quality": "description",
      "operation": "remove"
    }
  ]
}

Run it the same way as a recipe:

$ esdieff edit --plan edits.json --source thermostat thermostat.sdf.json --document-output thermostat-winter.sdf.json --check initial-v1
Edit winter-edits: passed
Generation: complete
Fidelity: established (esdieff.authored-quality-edit/1)
Substitution: source 1 with generated source 2
Root sources: [2]
Dependency sources: []
Assessed sources: [2]
Unavailable required sources: []
Requested editing coverage: total 1, assessed 1, undetermined 0
Checking: esdieff.initial/1: passed
Requested model coverage: total 8, assessed 8, not applicable 0, unassessed 0, undetermined 0
Broader RFC coverage: partial
Errors: 0, unfinished editing units: 0

Fidelity here means that every requested change was made and that everything else, including the spelling of every number, is unchanged. Esdieff reformats the output as indented JSON, so expect whitespace differences but no value differences. Each edit must target a member that exists: replace and remove both refuse an absent quality, which keeps a plan from silently doing nothing after the model changes under it.

Compare the result with the original to see exactly what changed and what it means for apps:

$ esdieff diff --old thermostat.sdf.json --new thermostat-winter.sdf.json --format markdown
# Model changes

Disposition: failed, with 1 breaking, 0 undetermined and 2 compatible differences.

## Breaking differences

- Changed quality `maximum` in `document` at `/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum` (witness `30` for client-supplied data, earlier admitted, later rejected)

## Compatible differences

- Changed quality `description` in `document` at `/sdfObject/Thermostat/sdfProperty/targetTemperature/description`
- Changed quality `description` in `document` at `/sdfObject/Thermostat/sdfProperty/currentTemperature/description`

Lowering the maximum is breaking, because an app that used to write 30 would now be refused. Compare two revisions explains the classification. The editing contract lists the qualities each kind of definition accepts and the limits. Definitions behind an authored sdfRef cannot be edited in place, because the member lives in the referenced document.

Where to go next

• Inspect and check a model checks the generated documents with their dependencies.
• Use the Rust library builds the same requests from Rust with AuthorRequest and EditRequest.

Compare two revisions

This guide compares two revisions of a model before a change is published, reads which differences break the apps that use the device, and records the ones you intend. It assumes Esdieff is installed.

Build a before and after pair

Save the earlier revision as v1/thermostat.sdf.json. It is the thermostat’s target temperature on its own, with a version in its info block:

{
  "info": { "title": "Room thermostat", "version": "1.0.0" },
  "sdfObject": {
    "Thermostat": {
      "sdfProperty": {
        "targetTemperature": {
          "description": "Requested room temperature in half-degree increments",
          "type": "number", "nullable": false, "minimum": 5, "maximum": 30,
          "multipleOf": 0.5, "unit": "Cel", "readable": true, "writable": true
        }
      }
    }
  }
}

Save the later revision as v2/thermostat.sdf.json. It raises the maximum to 35, drops the half-degree step, shortens the description and leaves the version unchanged:

{
  "info": { "title": "Room thermostat", "version": "1.0.0" },
  "sdfObject": {
    "Thermostat": {
      "sdfProperty": {
        "targetTemperature": {
          "description": "Requested room temperature",
          "type": "number", "nullable": false, "minimum": 5, "maximum": 35,
          "unit": "Cel", "readable": true, "writable": true
        }
      }
    }
  }
}

Compare them

$ esdieff diff --old v1/thermostat.sdf.json --new v2/thermostat.sdf.json
Revision comparison esdieff.revision-comparison/2: breaking
Documents: 1 compared, 0 removed, 0 added
Differences: 1 breaking, 1 undetermined, 1 compatible
Warnings:
  comparison.version_not_increased in document: later version "1.0.0" does not compare higher than earlier version "1.0.0", after 1 breaking difference
Breaking differences:
  changed quality maximum (client-supplied and thing-supplied data)
    witness 35 for thing-supplied data: earlier rejected, later admitted
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/maximum
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/maximum
Undetermined differences:
  changed quality multipleOf (client-supplied and thing-supplied data): no breaking witness or compatibility proof
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf (absent)
Compatible differences:
  changed quality description (client-supplied and thing-supplied data)
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/description
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/description

Esdieff takes the side of the client, the app or controller that talks to the device. Each difference is classified by what it means for a client built against the earlier revision:

• Breaking means such a client can be surprised. Raising the maximum looks harmless for values the client writes, but the property is also readable, and a device may now report 35 where the client expects at most 30. The witness line shows the concrete value that proves it: 35 was rejected before and is admitted now, in the direction the device supplies.
• Compatible means no client can tell the difference, as with a changed description.
• Undetermined means Esdieff found neither a breaking witness nor a proof of compatibility, so the change needs a human look. Removing the step is such a case. An undetermined difference is never presented as safe.

The warning says that a breaking change shipped under an unchanged version, which RFC 9880 advises against. Warnings do not change the result. The command exits 1 for a breaking comparison, 3 for an undetermined one and 0 for a compatible one, so a CI job can stop a breaking change from merging.

Changes that reach other documents through a shared definition

A changed shared definition appears in every device model that reuses it, at the place where that device presents it. Compare two directories to see this. Put a types.sdf.json with a shared Celsius type and a thermostat that references it in v1/, then copy both to v2/ and lower the shared minimum from -40 to -50:

{
  "info": { "title": "Shared types" },
  "namespace": { "types": "https://example.com/types" },
  "defaultNamespace": "types",
  "sdfData": { "Celsius": { "type": "number", "minimum": -40, "maximum": 80, "unit": "Cel" } }
}

{
  "info": { "title": "Room thermostat" },
  "namespace": { "types": "https://example.com/types" },
  "sdfObject": {
    "Thermostat": {
      "sdfProperty": {
        "currentTemperature": { "sdfRef": "types:#/sdfData/Celsius", "writable": false },
        "targetTemperature": { "sdfRef": "types:#/sdfData/Celsius", "minimum": 5, "maximum": 30 }
      }
    }
  }
}

$ esdieff diff --old v1 --new v2
Revision comparison esdieff.revision-comparison/2: breaking
Documents: 2 compared, 0 removed, 0 added
Differences: 1 breaking, 0 undetermined, 0 compatible
Breaking differences:
  changed quality minimum (thing-supplied data)
    witness -50 for thing-supplied data: earlier rejected, later admitted
    earlier thermostat.sdf.json /sdfObject/Thermostat/sdfProperty/currentTemperature/minimum
      from types.sdf.json /sdfData/Celsius/minimum
    later thermostat.sdf.json /sdfObject/Thermostat/sdfProperty/currentTemperature/minimum
      from types.sdf.json /sdfData/Celsius/minimum

Documents in the two directories pair up by relative path, and files that end in .sdf.json are selected as for esdieff check --directory. The difference is reported on the thermostat’s currentTemperature, because that is what a client sees, and the from lines name the shared definition that caused it. targetTemperature overrides the minimum, so it is unaffected. Add --recursive and --exclude to select nested files, as Check a local model collection describes.

Acknowledge the changes you intend

When a breaking change is deliberate, record it so the comparison passes while the report still shows the break. First export the eligible differences for review:

esdieff diff --old v1/thermostat.sdf.json --new v2/thermostat.sdf.json --acknowledgements-output reviewed.json

The comparison report and exit status stay as before, and reviewed.json lists every breaking and undetermined difference with its exact identity:

$ jq . reviewed.json
{
  "differences": [
    {
      "classification": "breaking",
      "earlier": {
        "document": "document",
        "pointer": "/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum"
      },
      "kind": "changed",
      "later": {
        "document": "document",
        "pointer": "/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum"
      },
      "quality": "maximum",
      "subject": "quality"
    },
    {
      "classification": "undetermined",
      ...
    }
  ],
  "schema": "esdieff.acknowledged-differences",
  "version": "1"
}

Review the file, delete any entry you do not intend, add a note to each if you like, and keep it with the model. Then supply it:

$ esdieff diff --old v1/thermostat.sdf.json --new v2/thermostat.sdf.json --acknowledged reviewed.json
Revision comparison esdieff.revision-comparison/2: breaking
Disposition: passed, with 1 breaking and 1 undetermined differences acknowledged
Documents: 1 compared, 0 removed, 0 added
Differences: 1 breaking, 1 undetermined, 1 compatible
Warnings:
  comparison.version_not_increased in document: later version "1.0.0" does not compare higher than earlier version "1.0.0", after 1 breaking difference
Acknowledged differences:
  changed quality maximum (client-supplied and thing-supplied data), breaking
    witness 35 for thing-supplied data: earlier rejected, later admitted
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/maximum
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/maximum
  changed quality multipleOf (client-supplied and thing-supplied data), undetermined: no breaking witness or compatibility proof
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf (absent)
Compatible differences:
  changed quality description (client-supplied and thing-supplied data)
    earlier document /sdfObject/Thermostat/sdfProperty/targetTemperature/description
    later document /sdfObject/Thermostat/sdfProperty/targetTemperature/description

The classification is still breaking, the disposition is passed and the exit status is 0. Only unacknowledged differences decide the result. An entry stops matching if the difference changes, for example when a later release can classify a former undetermined change as breaking, so a stale acknowledgement never hides a new problem. The version warning stays, so bump the version before publishing.

Share the comparison

--format markdown writes the comparison as a changelog for release notes, grouped by breaking, undetermined and compatible changes:

$ esdieff diff --old v1/thermostat.sdf.json --new v2/thermostat.sdf.json --format markdown
# Model changes

Disposition: failed, with 1 breaking, 1 undetermined and 1 compatible differences.

## Warnings

- Version `1.0.0` in `document` at `/info/version` does not compare higher than earlier version `1.0.0`, after 1 breaking difference (`comparison.version_not_increased`)

## Breaking differences

- Changed quality `maximum` in `document` at `/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum` (witness `35` for thing-supplied data, earlier rejected, later admitted)

## Undetermined differences

- Changed quality `multipleOf` in `document` at `/sdfObject/Thermostat/sdfProperty/targetTemperature/multipleOf`: no breaking witness or compatibility proof (`comparison.unproven`)

## Compatible differences

- Changed quality `description` in `document` at `/sdfObject/Thermostat/sdfProperty/targetTemperature/description`

--format sarif writes a SARIF log that code-scanning tools such as GitHub’s show as annotations on the model file. Acknowledged differences are marked as suppressed, so reviewers still see them while scanning treats them as intended:

$ esdieff diff --old v1/thermostat.sdf.json --new v2/thermostat.sdf.json --acknowledged reviewed.json --format sarif | jq -c '.runs[0].results[] | {ruleId, level, suppressed: (.suppressions | length > 0)}'
{"ruleId":"comparison.version_not_increased","level":"warning","suppressed":false}
{"ruleId":"comparison.breaking","level":"error","suppressed":true}
{"ruleId":"comparison.unproven","level":"warning","suppressed":true}
{"ruleId":"comparison.compatible","level":"note","suppressed":false}

--format json gives the full report for scripts. A comparison can also run as a case in a check plan beside the model checks, as Repeat checks and share reports shows. The revision comparison contract explains how each kind of quality is classified and what a witness proves.

Test values against a model

This guide checks single values against a model, generates boundary and invalid values for tests, and checks a log of recorded values in one run. It uses the thermostat.sdf.json from Install and try a model, whose targetTemperature accepts 5 to 30 °C in half-degree steps.

Check one sample

A sample is one JSON value for one definition. Save 21.5 in comfortable.json and check it against the target temperature. --kind property and --pointer select the definition, and the trailing argument supplies the model file:

$ esdieff sample --document thermostat.sdf.json --kind property --pointer /sdfObject/Thermostat/sdfProperty/targetTemperature --sample comfortable.json thermostat.sdf.json
Esdieff: passed
Complete: true
Errors: 0; warnings: 0; notices: 0; incomplete checks: 0
Scope: selected
...
Selected property in model 1 at "/sdfObject/Thermostat/sdfProperty/targetTemperature"
Sample 2: admitted; context available
...

Sample 2: admitted is the verdict on the value. Now save 35 as too-hot.json:

$ esdieff sample --document thermostat.sdf.json --kind property --pointer /sdfObject/Thermostat/sdfProperty/targetTemperature --sample too-hot.json thermostat.sdf.json
Esdieff: failed
Complete: true
Errors: 1; warnings: 0; notices: 0; incomplete checks: 0
...
Sample 2: rejected; context available
...
sample.bound: Sample violates an exact numerical bound
source 2 ""
  related effective 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum"
  related source 1 "/sdfObject/Thermostat/sdfProperty/targetTemperature/maximum"
...

The reports are trimmed to the lines about the sample. A rejected sample is a failed check with exit status 1, and the finding names the rule it broke and where that rule is defined. The other kinds are data for an sdfData definition, action_input, action_output and event_output, which select the data an action or event carries. Numbers compare exactly, so 30.0 and 30 are the same value and 0.1 is never rounded.

Generate values for every rule

esdieff generate builds values from the model’s rules, so your tests get expectations without hand-written payloads. Select one definition with --kind and --pointer, or leave them out to cover every property, action and event in the document:

$ esdieff generate --document thermostat.sdf.json --kind property --pointer /sdfObject/Thermostat/sdfProperty/targetTemperature thermostat.sdf.json
Generated values esdieff.generation/1: passed
Values: 2 admitted, 8 rejected, 0 undetermined
Descriptions: 1

property /sdfObject/Thermostat/sdfProperty/targetTemperature: complete
  rejected     null          null (sample.null)
  admitted     minimum       5
  admitted     maximum       30
  rejected     below_minimum 4 (sample.bound)
  rejected     above_maximum 31 (sample.bound)
  rejected     not_multiple  5.25 (sample.multiple)
  rejected     wrong_type    "" (sample.type)
  rejected     wrong_type    true (sample.type)
  rejected     wrong_type    {} (sample.type)
  rejected     wrong_type    [] (sample.type)

Each value aims at one target, named in the middle column: the two bounds, a value just outside each, a value off the step, and one wrong type of each kind. Esdieff then checks every value against the model, and the first column is the result of that check, not the intention. The two agree here, but a model that allows null would list the null target as admitted. For a map, generation also builds a value missing each required entry, and a wrong value for each entry, as the full thermostat output in the getting-started guide shows for the configure action.

Generation is deterministic. The same model and selection always give the same values in the same order, so the output can live under version control. Save the values as test vectors with --format jsonl, which writes one JSON object per line:

$ esdieff generate --document thermostat.sdf.json --kind property --pointer /sdfObject/Thermostat/sdfProperty/targetTemperature --format jsonl thermostat.sdf.json > vectors.jsonl
$ head -3 vectors.jsonl
{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/targetTemperature","value":null,"expected":"rejected","label":"null"}
{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/targetTemperature","value":5,"expected":"admitted","label":"minimum"}
{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/targetTemperature","value":30,"expected":"admitted","label":"maximum"}

Each line carries the selector, the value and its settled result as expected. Feed the values to the device or app under test and assert that it accepts the admitted ones and refuses the rejected ones. --format json gives the same values inside the full report. The generation contract lists every target.

Check a log of recorded values

esdieff trace checks a recorded trace, a JSON Lines file of values your device or app actually produced, in one run. Each line names a definition the way the generated vectors do, carries the value and may say what you expected. Save this as readings.jsonl:

{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/targetTemperature","value":21.5,"label":"evening"}
{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/targetTemperature","value":21.3,"label":"app bug"}
{"kind":"property","pointer":"/sdfObject/Thermostat/sdfProperty/currentTemperature","value":null,"label":"sensor offline"}
{"kind":"action_input","pointer":"/sdfObject/Thermostat/sdfAction/configure","value":{"targetTemperature":31,"mode":"heat"}}
{"kind":"event_output","pointer":"/sdfObject/Thermostat/sdfEvent/alarm","value":{"temperature":85,"reason":"overheat"},"expected":"rejected"}

$ esdieff trace --document thermostat.sdf.json --trace readings.jsonl thermostat.sdf.json
Recorded trace esdieff.trace/1: failed
Entries: 3 passed, 2 failed, 0 undetermined
Admissions: 2 admitted, 3 rejected, 0 undetermined

line 2 property "/sdfObject/Thermostat/sdfProperty/targetTemperature": failed
  label "app bug"
  admission rejected
  error sample.multiple at "/value" bytes 206..210: Sample is not an exact multiple of the positive step

line 4 action_input "/sdfObject/Thermostat/sdfAction/configure": failed
  admission rejected
  error sample.bound at "/value/targetTemperature" bytes 459..461: Sample violates an exact numerical bound

Only the failed lines are listed, each with its line number, the byte range of the offending part of the line and the rule it broke. Line 1 passed because 21.5 is admitted. Line 3 passed because the current temperature is nullable. Line 5 passed too: the alarm’s temperature of 85 is above its maximum of 80, and the line said that rejection was expected, so an expected rejection counts as a pass. Lines 2 and 4 failed because nothing was expected and the values were rejected.

Each line is checked on its own, so one malformed line fails only itself and the rest of the file still runs. The model is composed once, which keeps a trace of a hundred thousand values fast. The trace contract describes the line format and the limits.

Replay generated vectors against a new revision

Generated vectors are a recorded trace, so esdieff trace replays them. Against the model they were generated from, every line passes:

$ esdieff trace --document thermostat.sdf.json --trace vectors.jsonl thermostat.sdf.json
Recorded trace esdieff.trace/1: passed
Entries: 10 passed, 0 failed, 0 undetermined
Admissions: 2 admitted, 8 rejected, 0 undetermined

Against a revision that raised the maximum to 35 and dropped the half-degree step, exactly the vectors whose result changed fail:

$ esdieff trace --document revised.sdf.json --trace vectors.jsonl revised.sdf.json
Recorded trace esdieff.trace/1: failed
Entries: 8 passed, 2 failed, 0 undetermined
Admissions: 4 admitted, 6 rejected, 0 undetermined

line 5 property "/sdfObject/Thermostat/sdfProperty/targetTemperature": failed
  label "above_maximum"
  admission admitted, expected rejected
  error trace.expected at "/expected" bytes 648..658: The definite admission differs from the Expected admission

line 6 property "/sdfObject/Thermostat/sdfProperty/targetTemperature": failed
  label "not_multiple"
  admission admitted, expected rejected
  error trace.expected at "/expected" bytes 791..801: The definite admission differs from the Expected admission

This is a quick way to see what a model change does to values you already rely on. Compare two revisions explains the same change from the app’s point of view, and Repeat checks and share reports saves sample checks in a plan to run again.

Repeat checks and share reports

This guide saves checks so they run the same way every time, checks a whole directory of models, and brings the results into CI and code review. It assumes Esdieff is installed.

Save checks as a plan

A check plan is a JSON file that names the model and sample files to supply and the cases to run on them. One command then runs every case and reports each outcome by name. The repository’s thermostat-check example includes this plan.json:

{
  "schema": "esdieff.check-plan",
  "version": "1",
  "sources": [
    { "key": "thermostat", "path": "thermostat.sdf.json", "role": "model" },
    { "key": "comfortable", "path": "comfortable.json", "role": "sample" },
    { "key": "too-hot", "path": "too-hot.json", "role": "sample" }
  ],
  "cases": [
    { "name": "Catalogue", "operation": "check", "scope": { "kind": "catalogue" } },
    {
      "name": "Thermostat model",
      "operation": "check",
      "scope": { "kind": "selected", "roots": ["thermostat"] },
      "assessment": "full-baseline",
      "strict_warnings": true
    },
    {
      "name": "Comfortable target",
      "operation": "sample",
      "document": "thermostat",
      "kind": "property",
      "pointer": "/sdfObject/Thermostat/sdfProperty/targetTemperature",
      "sample": "comfortable"
    },
    {
      "name": "Too hot target",
      "operation": "sample",
      "document": "thermostat",
      "kind": "property",
      "pointer": "/sdfObject/Thermostat/sdfProperty/targetTemperature",
      "sample": "too-hot"
    }
  ]
}

Paths are relative to the plan, so the directory moves as a unit. Each case keeps its own scope, assessment level and warning policy. Copy the example directory and run it. The human report prints each case in full, so this command keeps the summary lines:

$ esdieff check --plan plan.json | grep -E '^(Case|Disposition|Admission|Check case summary)'
Case: "Catalogue"
Disposition: passed
Case: "Thermostat model"
Disposition: passed
Case: "Comfortable target"
Disposition: passed
Admission: admitted
Case: "Too hot target"
Disposition: failed
Admission: rejected
Check case summary: {"admission_undetermined":0,"admitted":1,"complete":true,"complete_cases":4,"failed":1,"incomplete_cases":0,"omitted_reports":0,"passed":3,"rejected":1,"request_errors":0,"total":4,"undetermined":0,"verdict":"failed"}

The run exits 1, because the rejected sample is a failed case. A plan has no expected-result field: a sample you intend to reject still fails, which keeps the verdict honest. Keep such samples in a separate plan, or check them with recorded traces, where an expected member turns an intended rejection into a pass. The catalogue-check example is the smallest model-only plan, and a diff case can compare two revisions beside the checks, as Repeatable catalogue checks shows.

Check a directory of models

--directory selects every regular file ending in .sdf.json in a directory, so a check follows the collection as files are added. Run this on the repository’s directory-check example, which holds a device, a shared type, a nested status model and an unfinished draft:

$ esdieff check --directory examples/directory-check --recursive --exclude draft --format json | jq -c '.sources[] | {id, label}'
{"id":1,"label":"examples/directory-check/device.sdf.json"}
{"id":2,"label":"examples/directory-check/nested/status.sdf.json"}
{"id":3,"label":"examples/directory-check/types.sdf.json"}

--recursive descends into subdirectories and --exclude prunes a literal file or subtree relative to each directory. Sample files, plans and a .bak lookalike are not selected. Without the exclusion, the draft’s broken type fails the run:

$ esdieff check --directory examples/directory-check --recursive
Esdieff: failed
Complete: true
Errors: 1; warnings: 0; notices: 0; incomplete checks: 0
...
data.string: A textual data quality must contain a string
source 2 "/sdfData/Unfinished/type"
Diagnostic details omitted: 0

Repeat --directory for several collections, add explicit files beside them, and name a discovered root by its joined path, such as --root examples/directory-check/device.sdf.json. Check a local model collection states the selection rules and limits.

Use JSON reports in automation

--format json writes the same report as a JSON document with a stable schema, for every command. The outcome member is the summary a script needs:

$ esdieff check --format json thermostat.sdf.json | jq '.outcome'
{
  "complete": true,
  "disposition": "passed",
  "errors": 0,
  "incomplete_checks": 0,
  "notices": 0,
  "strict_warnings": false,
  "warnings": 0
}

diagnostics.items holds each finding with its code, message, locations and the RFC section it rests on, and coverage records what was assessed. A plan run has its own schema, esdieff.check-run, whose summary counts the cases:

$ esdieff check --plan plan.json --format json | jq -c '.summary'
{"admission_undetermined":0,"admitted":1,"complete":true,"complete_cases":4,"failed":1,"incomplete_cases":0,"omitted_reports":0,"passed":3,"rejected":1,"request_errors":0,"total":4,"undetermined":0,"verdict":"failed"}

The report contract describes every member and how reports stay within their size limits. Additive fields can appear in later releases, so read the members you need rather than comparing whole documents.

Show findings in code review with SARIF

esdieff check --format sarif and esdieff diff --format sarif write a SARIF 2.1.0 log, the format code-scanning tools such as GitHub’s read to annotate files in a pull request. Each finding becomes a result with its code as the rule, a level and the file, line and column it is about:

$ esdieff check --directory examples/directory-check --recursive --format sarif | jq '.runs[0].results[] | {ruleId, level, message: .message.text, file: .locations[0].physicalLocation.artifactLocation.uri, line: .locations[0].physicalLocation.region.startLine}'
{
  "ruleId": "data.string",
  "level": "error",
  "message": "A textual data quality must contain a string",
  "file": "examples/directory-check/draft/unfinished.sdf.json",
  "line": 3
}

File paths are relative to the directory the command ran in, so run it from the repository root and upload the log with your code-scanning tool’s SARIF step. Acknowledged revision differences appear as suppressed results, as Compare two revisions shows.

Write change notes with Markdown

esdieff diff --format markdown writes a revision comparison as a changelog grouped by breaking, undetermined and compatible changes, ready to paste into release notes or a pull request description. Compare two revisions shows the output.

Use exit statuses

Every command uses the same exit statuses, so a shell or CI step can act on them without parsing a report:

esdieff generate never fails, so it exits 0 or 3. A status of 3 deserves attention in CI as much as 1 does: the model was not shown to be wrong, but it was not shown to be right either.

Use the Rust library

Everything the esdieff command does is available as a Rust library, so you can embed model checking, inspection, generation and revision comparison in your own tools. The library uses no unsafe code and performs no network access.

Add the crate

There is no release on crates.io yet, so depend on the repository directly:

[dependencies]
esdieff = { git = "https://github.com/pederbe/esdieff" }

The crate builds on stable Rust with the 2024 edition. Pin a commit with rev = "..." once you depend on it in CI.

The entry points

A Catalogue holds the documents you supply. Build one from SourceInput values, each with a key that names it in reports: SourceInput::file reads a path, SourceInput::supplied takes bytes you already hold, and .sample() marks a sample value rather than a model. Every operation is a method on the catalogue that takes a request and returns a result you can query or render:

Results borrow the catalogue, so keep it alive while you read them. Each has to_json() and to_human() for the same reports the command prints, and a disposition whose exit_code() matches the command’s exit status.

A complete example

This program checks the thermostat model from Install and try a model with the full assessment, reads the effective range of its target temperature and prints the property as written in the file. Create a new binary crate, add the dependency above, put thermostat.sdf.json in the crate directory and use this src/main.rs:

use esdieff::{Assessment, Catalogue, CheckRequest, Class, EffectiveRequest, InspectRequest, Lookup, SourceInput};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Supply the model files. Every input is a candidate, and its key names it in reports.
    let catalogue = Catalogue::from_inputs(&[SourceInput::file(
        "thermostat",
        Path::new("thermostat.sdf.json"),
    )])?;
    let thermostat = catalogue.source_id("thermostat").expect("supplied source");

    // Check the thermostat against every RFC 9880 model requirement Esdieff records.
    let request = CheckRequest::new()
        .root(thermostat)
        .assessment(Assessment::FullBaseline);
    let report = catalogue.check(request)?;
    println!("check: {:?}", report.outcome().disposition());
    for condition in report.diagnostics().conditions() {
        println!("{}: {}", condition.code(), condition.message());
    }

    // Read the effective target temperature range, with inherited qualities applied.
    let effective = catalogue.effective(EffectiveRequest::new(thermostat))?;
    let Lookup::Found(object) = effective.definition(Class::Object, "Thermostat") else {
        panic!("Thermostat missing")
    };
    let (_, target) = object
        .children(Class::Property)
        .require()?
        .find(|(name, _)| *name == "targetTemperature")
        .expect("targetTemperature");
    let description = target.require()?.data_description().require()?;
    println!(
        "targetTemperature: {} to {}",
        description.minimum().require()?.lexeme(),
        description.maximum().require()?.lexeme()
    );

    // Show the authored source of that property as written in the file.
    let pointer = "/sdfObject/Thermostat/sdfProperty/targetTemperature";
    let inspection = catalogue.inspect(InspectRequest::new(thermostat, pointer))?;
    if let Some(json) = inspection.inspection_json() {
        println!("source: {}", json.raw_json());
    }
    std::process::exit(report.outcome().disposition().exit_code().into());
}

$ cargo run --quiet
check: Passed
targetTemperature: 5 to 30
source: {
          "description": "Requested room temperature in half-degree increments",
          "type": "number", "nullable": false, "minimum": 5, "maximum": 30,
          "multipleOf": 0.5, "unit": "Cel", "readable": true, "writable": true
        }

A few things to notice. Operations return Err(&'static str) only for an invalid request, such as an unknown source key. A model problem is never an error: it is a finding in the report, and the disposition says whether the check passed. Fields that may be absent, unfinished or outside the supported meaning are Field values, and require() turns anything but a present value into an error, which suits a tool that expects a complete model. Numbers are exact: lexeme() returns the text from the document, and ExactNumber compares values without converting them to floating point. The source view prints the member byte for byte, whitespace included.

Keep the memory and work bounded

Every operation runs within Limits, which cap input size, decoding depth, work and report size, so an untrusted document cannot make a tool run away. The defaults suit ordinary models. Catalogue::take_inputs_with_limits sets others, and an operation that reaches a limit reports the work it could not finish instead of failing silently. ADR 0009 explains the approach.

Where the contracts are

Each operation’s reference page states what its result promises, with a Rust example at the top:

• Supplied source documents covers catalogues, source and effective views, locations and exact numbers.
• Selected samples covers SampleRequest, admission and typed sample values built with JsonBuilder.
• Generated values covers GenerationRequest, targets and JSON Lines output.
• Recorded traces covers TraceRequest and per-entry outcomes.
• Composed sdfThing authoring and Authored-quality editing cover AuthorRequest, EditRequest, plans and fidelity.
• Revision comparison covers ComparisonRequest, differences, witnesses and acknowledgements.
• Workflow and report contract covers the shared report envelope that to_json() renders.

The repository’s examples directory holds complete programs that read effective values and requirement coverage.

Public workflow and report contract

This text specifies the shared guarantees behind the library, command and JSON report. The reasons are ADR 0010: Domain-oriented library and caller simplicity, ADR 0011: Machine-readable report contracts, and ADR 0012: Exact numbers and JSON input policies. Domain terms follow the domain language. Standards semantics come from RFC 9880 Sections 4.4 and 4.7, RFC 6901 Sections 3 and 4 for pointer tokens, and RFC 7396 Section 2 for merge/deletion. Resource limits and report fields are toolkit contracts, not RFC limits.

Library work and ownership

The public boundary is document-supplied domain work. A Catalogue owns each supplied source’s identity, acquisition result and content. Construction accepts owned content, or converts borrowed caller content into owned storage once. Views borrow the catalogue/result; callers do not keep the original strings alive, own reference graphs, manually merge JSON, or expose a particular parser/numeric dependency. Internals may use immutable sharing and caches, but do not expose mutable checked state.

The operation families are check(request), source(document), effective(request), check_sample(request), author(request), edit(request) and compare(request), using the same source/result/report foundation. Requests use builders with private fields. Operations produce usable results alongside scoped conditions. Malformed source input, unavailable dependencies and exceeded admitted work budgets are domain results. Configuration errors, unknown selectors and hard ceilings that prevent complete plan/request admission are request errors. Neither is a panic contract.

Each acquisition attempt receives a unique request-local SourceId before reading. Identity is an opaque caller key, distinct from a bounded display label, optional acquisition URI, content identity and SDF namespace. Duplicate caller keys are request errors. Same bytes supplied twice are two contributors, with no deduplication or precedence. CLI paths have distinct explicit identities; input position is not a semantic role. Source content is immutable owned bytes; UTF-8 text is available if decoding permits it, and raw bytes remain inspectable after decoding failures. Partial read/size-limit content records retained bytes and content_complete:false; it never purports to be the whole source. Acquisition failure has no content and stays visible. An optional caller content-version token is opaque; no path or label is a content hash. Reproducible callers may provide a digest; mandatory library hashing is not required.

Before copying any caller metadata, request validation checks UTF-8 byte lengths: caller key at most 256, display label 512, optional acquisition URI 2,048, content-version token 128 and digest 256. It preflights all attempts together against 1 MiB combined caller metadata, including exact raw filesystem identity bytes, every repeated source/scope-reference representation and all model, sample and generated attempts. These roles share one ceiling of 256 source attempts. Internal/report SourceId is a compact nonzero u32 allocated per request; it is separate from the bounded unique caller key. UTF-8 keys compare exactly, without case folding or normalization. Raw filesystem identities can contain non-UTF-8 bytes and are retained exactly for acquisition; their bytes consume the combined metadata budget. CLI adapters use bounded opaque caller keys to associate these identities, rather than forcing raw path bytes into UTF-8 keys.

Oversized semantic keys, URI/version/digest metadata, or aggregate metadata are request errors before ownership/copying or model processing. Keys/version identifiers are never clipped to fit. Only a display label may be shortened or omitted for presentation with a structured label_omitted reason; its full accepted form can remain available in owned metadata. Oversized supplied labels are request errors unless the caller explicitly requests label omission before retention. Library-owned baseline, policy and inventory metadata share a 64 KiB request budget. The mandatory report envelope is reserved before work using worst-case JSON escaping (up to six output bytes per input byte), all accepted source counts, fixed field overhead, repeated source/scope references, outcome/coverage counters and omission records. A report configuration smaller than that reserve is rejected before copying or acquisition. Optional report details consume only the remaining budget. No source attempt, aggregate finding or semantic identity is erased to meet a small report budget.

The default request has catalogue scope, including all supplied definitions and all source attempts. Explicit selected scope contains a nonempty set of supplied SourceId roots. Other sources are lookup candidates; reports separately identify roots, needed dependency sources, independently assessed sources and unavailable required sources. A missing/failed root is incomplete; an unreadable unrelated candidate remains in sources without alone spoiling selected-model work. If inability to inspect a candidate prevents establishing a needed addressed contributor or ambiguity, that lookup is incomplete. No implied network fetching or first/last input preference applies. Selected scope is rooted in documents, not individual definitions.

Selected checks independently assess their roots and use the shared effective evaluator for surviving imported content. Dependency source membership does not promise independent assessment of every definition or Information quality in that source. Catalogue checks do independently assess all sources. Global target discovery uses exact decoded namespace text and decoded target-pointer identity after the needed critical-feature context is established, as ADR 0023: Supplied global composition and dependency scope specifies. Possible contributors with unavailable identity remain distinct from established dependencies.

Source views expose all retained JSON and raw content, even when effective work fails. Typed source projections distinguish malformed/unsupported fields from absent fields. Effective views expose Things, Objects, Properties, Actions, Events and sdfData definitions with class-specific grouping, affordance, input/output and data-description access. Consumers can traverse groupings, inspect required declarations, obtain effective Property capabilities, data types and constraints, choices/enum alternatives, declared defaults and opaque qualities without rebuilding their semantics. Data-entry required remains separate from declaration sdfRequired. Extended data types remain tagged known/extended/undetermined values, not guessed base types.

An effective definition handle is scoped to its owning result and points to a root-document/effective path. Available subviews remain usable if another subview is incomplete. Missing, present, deleted and unavailable are distinct outcomes. Known defaults are returned as effective semantic values with a default origin when established; source access does not insert them. A lookup supports Lookup::Found, NotFound, Ambiguous, and Unavailable, so uncertainty cannot be mistaken for absence. Domain accessors return Field::Absent, Present(T), or Unavailable(reason) as appropriate. Option<T> is reserved for an established optional absence.

The implemented effective owner is EffectiveModel, returned by Catalogue::effective(EffectiveRequest::new(source_id).pointer(selector)) or borrowed from Report::effective_model(). It owns compact derived records and borrows immutable catalogue sources; its views borrow that owner. Effective named collection rows are (name, Field<handle>), preserving known unavailable entries and accessible siblings without changing source iterator item types. A containing handle can retain independent subviews when one descendant is unavailable. Unknown needed identity makes the affected collection or lookup unavailable.

explanation(pointer) describes composed content and its nearest source, inheritance, override or deletion contributors. default_explanation(pointer) separately describes an established implicit semantic value without an authored contributor. Both can describe the same absent path: a null patch deleting inherited writable:false retains a Deleted content explanation and a Default explanation for the typed true capability. No defaults are inserted into JSON. Direct-item defaults and copied requiredness in full data descriptions remain scoped limitations, with raw syntax accessible. These guarantees follow ADR 0020: Owned effective views and nearest origins.

Explanation::consumer() returns the established importing source sdfRef as an optional immutable source view. Ordinary source content has no importing consumer. An outer consumer survives its mandatory target-root chain; separately composed nested references establish their own consumers. Human inspection and optional JSON consumer locations expose the same boundary without changing nearest content origins or fabricating authored default sources.

Checks evaluate independent source definitions and surviving effective vocabulary through one role and rule set. Distinct composed observations contribute to aggregate findings before detail retention. Unchanged local replay requires completed source evaluation, identical established role and clear feature context, and unchanged rule premises; traversal still reaches composed descendants. Initial and expanded source extension.optional_unsupported summaries count actually inspected source occurrences in observed_occurrences. Their effective summaries retain that code and basis but omit the source-only count. Condition, byte and pointer presentation limits leave semantic totals and requested-unit status unchanged.

Full reports retain extension.optional_unsupported per inspected occurrence, with its decoded Quality Name in arguments.quality and its source location as primary. A composed observation has its effective position as primary and the nearest source contribution as one related location. quality.unfamiliar conditions also carry arguments.quality, in every assessment. Human reports show the name separately from the pointer, so it remains visible when a pointer is omitted. These details identify unsupported content behind unfinished Full requirements without changing its severity, interpretation or coverage status. Full optional notices count occurrences rather than summaries. Each source notice keeps observed_occurrences: 1; effective notices omit that source-only argument. Existing condition and diagnostic-byte limits bound how many occurrences are retained. Existing pointer limits omit pointers with their structured reason, and the name is charged against the diagnostic-byte limit before retention. No additional location collection or independent limit is used.

Accessible JSON has an Esdieff wrapper providing JSON kind, map/array traversal, scalar access and bounded generation. It retains arbitrary JSON numbers as numbers. No serde_json::Value, decimal-library type or mutable graph escapes into the public contract. Opaque structural access does not prove unknown extension meaning or permit generic edits to checked state.

Numbers and locations

An exact numeric view exposes its accepted original JSON lexeme, mathematical sign/integrality and budgeted exact ordering. Explicit checked machine conversions may return not-representable; they never round silently and cannot replace exact access. Comparison and later equality have their own finite-work result. The public number type is independent of its private representation. Unchanged generated numbers preserve an accepted raw lexeme, including 10e1000000 and 1e-1000000. A normalized internal coefficient is not a mandatory emitted token. Exact access to a count such as 18446744073709551616 establishes mathematical information, not normative CDDL uint membership, as ADR 0012 requires.

Locations are tagged source, effective or sample locations. A source location contains source_id, an optional decoded RFC 6901 pointer, and an optional half-open UTF-8 byte span. Byte spans refer to the retained original source, including key/token spans where relevant, and are not recomputed offsets in generated JSON. A root pointer is the empty string. Failed acquisition has a source identity with no invented pointer/span. A sample location uses its separate sample-source identity and pointer/span. An effective location contains the selected root identity and effective pointer; it is not a claim that this path exists in a supplied source. Non-renderable paths have pointer:null and a structured omission reason, with available spans retained.

An available explanation identifies the effective target, explanation kind (source, inherited, override, deleted, or default) and relevant source location(s). It may identify only the nearest contributor and patch location; it does not promise a complete history. Unavailable is explicit. For Device.ambient’s temperature minimum, the effective path ends /minimum, with the Temperature source /sdfData/Temperature/minimum. Its maximum 100 points to the patch source /sdfThing/Device/sdfObject/ambient/sdfProperty/temperature/maximum. The removed description’s explanation targets effective /sdfThing/Device/sdfObject/ambient/description despite the quality’s absence, identifies deletion at the null patch source and, when available, the inherited Sensor description. Controller.level inherits minimum from the supplied Level document, while maximum 80 and removed description refer to the Controller patch. Explanations of relocated content keep their nearest content origins, and their importing consumer is the original authored reference, following ADR 0036: Copied reference relocation.

An established Boolean default explanation additionally carries optional default_value:true, with the same value shown in human output. The field is absent for other origin kinds. It covers the already-supported Property readable/writable/observable and full-description nullable defaults, preserves separate deletion and default rows, and adds no JSON quality or interaction value. Detail admission reserves the annotation before construction; omitted explanation rows keep an explicit reason and do not erase typed characteristic access. This additive 1.x field follows ADR 0022: Scalar constraints and characteristic states.

Effective inspection additionally reports optional result.alternatives owner records with an effective owner location and collection state of absent, present or unavailable. Present can be empty. Known branches retain an id tagged choice with name or enum with occurrence index; branch states are available, partial or unavailable, with independent complete, json_present, optional unavailable reason and nearest/default/consumer explanations. A partial branch’s derived json can retain opaque raw quality values while unavailable_qualities explicitly identifies unestablished meanings. Raw JSON is not sample admission or consistency evidence. The composed result.json and existing pointer selectors retain their meaning. Count, byte, pointer or work omissions use explicit reasons and never imply an absent collection or completed meaning. Human output exposes the same collection, branch and unavailable-quality distinctions. These additive fields deliberately retain emitted check/inspect version 1.0 and follow ADR 0024: Effective alternatives and nullable characteristics.

Required declaration relationships

Requested required-declaration inspection adds result.required_declarations to the existing inspect1.0 result. Its twelve mandatory fields are state, complete, unavailable_reason, owners_known, owners_retained, references_known, references_retained, targets_known, targets_retained, owners_omitted, traversal_complete and owners. Counts describe discovered work and retained or presented subsets; no total of undiscovered owners is inferred. available with completed empty owners differs from unavailable, while a retained unfinished traversal is partial. Known invalid findings can coexist with complete traversal. Optional owner rows separate source and effective locations, relationship status, importing consumer and target capability (established, partial, unavailable, not_requested). Missing targets produce the Advice notice required.target_missing and scoped incompleteness; established wrong roles and malformed syntax are independent RFC errors. This inspection keeps the one existing inspection unit and the initial assessment inventory unchanged, following ADR 0026: Required declaration relationships and source evidence.

The requested operation admits the existing mandatory envelope plus twelve times selector bytes plus 1024 bytes before semantic work. The same additional reserve is subtracted from optional wire and scratch allowances. The summary is emitted directly into the existing output buffers with exact decimal Counts, fixed printable ASCII reasons of at most 96 bytes and quote/backslash escaping. It creates no summary Value/map, owned escaped text, numeric string, redundant selector flag or hidden empty owner transport DTO. A fixed Counts record occupies 28 bytes and the optional presentation plan 48 bytes in the 64-bit test executable. The worst supported literal control with seven ten-digit Counts, a maximally escaped reason and the one owner suffix omission emits 636 bytes; the conservative global diagnostic addition is 40 bytes, below the 768-byte wire bound. The complete early human prefix is 497 bytes, below 512. JSON and human are alternative outputs within the existing buffer allowance.

Optional owners stop at the first failed admission. One directly emitted omissions record gives the exact retained-minus-shown owner suffix and that first cause (count_limit, byte_limit or report_limit). The mandatory summary remains with empty owners at the exact admitted report cap, where optional wire and scratch are zero. Global diagnostic truncation and deduplicated reasons reflect the omission. The current borrowed reason inventory is at most eight entries: count_limit, byte_limit, not_available, report_limit, location_limit, byte_or_count_limit and presentation_limit. One additional owner omission reason needs at most 128 bytes borrowed-vector growth, 128 bytes for a Value cell and 16 bytes reason-string capacity, 272 bytes within the 528-byte allowance and 4096-byte additional mandatory ownership share. Reasons are deduplicated before known-length JSON conversion. Admitted optional location limitations use fixed flags; their global reasons and per-location DTO metadata are covered by that owner’s optional precharge.

Each optional owner reserves 1024 wire bytes, each reference 2048 and each target 3072, plus 512 per source/effective/related location and six times measured pointer or text bytes. Checked sums refuse unfit owners before constructing DTOs. Scratch reserves 32768 plus eight times the complete owner wire bound, covering nested DTO maps, strings, vector growth, parent serialization and temporary encoding. Actual retained wire size, plus 64 bytes for human row framing, is verified against that admission. Fixed missing/syntax/context conditions use the existing 512-wire/32768-scratch diagnostic admission. Semantic traversal edges, source positions, coordinates, contributor context, record capacities and all four operation counters are precharged before their work or allocation. Semantic failure changes completion; presentation omission does not.

Assessment identities and coverage

esdieff.initial/1 is the immutable default model-assessment identity. Its inventory is the agreed initial structure/composition inventory, independent of implemented checks. The eight stable area identities are document-envelope/1, base-roles-names/1, metadata-namespaces/1, established-composition/1, basic-parameters/1, alternatives-requiredness/1, extensions-policies/1, and advisory-four/1. Precise membership and guards are as follows.

The eight areas are assessed through the original bounded traversal, composition and required-declaration resolver. Completion requires every applicable area to be assessed or established not applicable; a definite error can coexist with complete work. Needed acquisition, composition, critical meaning or checking limits leave affected areas undetermined. The advisory area completes its four local proofs when relevant meanings and traversal are established, is not applicable after reliable absence, and is undetermined when needed meaning or work is unavailable. Warnings retain their basis and severity under strict policy. See initial contradiction advice for guards, witnesses and numeric work.

Declared or specified-default nullable true excludes the first three classes before applicability is recorded. A failed derived numeric precharge also retains an operation.limit condition in advisory-four/1, with Operational basis advisory-numeric-work and fixed proof_class, operation and affected qualities arguments. Multiple specific limits still make only the one advisory requested area incomplete. Unavailable meaning and omitted presentation details retain their separate causes; Full includes the same advisory area once.

The parameter context matrix is part of that identity: full descriptions at Property, sdfData, Action input/output, Event output, properties entries and sdfChoice alternatives; direct items require a map and only their established sdfRef, description, $comment, optional number/string/Boolean/integer/object type, choice/enum, minimum/maximum, format, minLength/maxLength meanings. An object direct item additionally permits required/properties, whose property descriptions are full descriptions. Direct-item choice alternatives are full descriptions. Wider framework-admitted vocabulary is retained with scoped limitations, not silently imported full-description meanings. Direct format checks text shape; direct array/minItems/nullable/nested-items/default meanings remain limited as recorded in ADR 0012 and the standards questions.

Map-data required shape checking applies to a reliable explicit type:"object" in either data-description role. A missing, nonobject, extended or unavailable type does not establish that applicability; unknown member identity also prevents it. Borrowed required_entries() presents nonempty authored syntax independently of semantic applicability in full descriptions, with the established object guard in direct items. An available list alone is not proof of an applicable map constraint or mandatory sample entries. Composition applies null deletions before assessing surviving effective qualities, and replay must preserve the containing object-type premise, following ADR 0020: Owned effective views and nearest origins.

Broader omitted requirements include formal CDDL numeric admission, detailed modified/unit/content-format checks, ECMA-262 pattern syntax, broader const/default consistency, full sample matching, and unresolved grammar/reference-form/item/requiredness/group-presence questions. A successful initial result therefore always reports broader baseline coverage as partial. Absence of a proof never establishes satisfiability.

esdieff.expanded.modified/1 explicitly requests those unchanged eight areas plus modified-date-time/1. Its ninth area checks ordinary Information modified dates and UTC labels directly, with exact fractions and finite recorded leap knowledge. Its membership stays fixed; other expanded work does not silently enter it. The modified metadata contract and ADR 0021: Explicit modified metadata assessment specify the additional meaning.

esdieff.expanded.numeric/1 explicitly requests the unchanged Initial eight areas plus advisory-numeric-three/1. Its ninth area attempts integer interval gaps, numeric const against every applicable bound, and positive-step interval gaps in established effective Full descriptions. The numeric advice contract and ADR 0030: Bounded numeric advice specify the exact role, meaning, null and finite arithmetic guards. The added mandatory reserve is zero; requested aggregates remain nine even with all optional rows and condition details omitted. Other profiles and Full do not implicitly acquire the new area. Undetermined numeric rows use Operational expanded-numeric-establishment; numeric capability conditions use Operational expanded-numeric-capability with no citation key. Completed or not-applicable numeric rows use Advice advisory-numeric-three/1. Numeric proofs preserve four original operand identities and absent-type argument/location absence.

esdieff.expanded.consistency/1 explicitly requests the unchanged Initial eight areas plus const-consistency/1 and default-consistency/1, for ten areas. The declared-value consistency contract and ADR 0031: Bounded declared-value consistency specify candidate selection, complete alternative witnesses and supported reasoning. Each definitively excluded candidate adds one Warning/Advice, independently of existing Initial producers and rejected leaf count. Documentary defaults are not inserted. The nearest real candidate source is primary, with effective constraints, origins and consumers related. Unknown needed meaning or finite evaluation limits leave the affected area undetermined; independent established advice remains. The added mandatory reserve is zero. Omitted rows/details preserve the ten-area aggregates and warning counts. Other profiles and Full retain their inventories.

esdieff.expanded.content-format/1 explicitly adds content-format-syntax/1 and content-format-registry/1 to the unchanged initial eight. The content-format contract distinguishes whole declaration spelling, decimal range, dated positives, current registration unknown, needed withheld evidence and excluded parameter meaning. The two private area states contribute to existing mandatory requested aggregates; located coverage rows remain optional. No mandatory per-name result graph or duplicate status map is added. Available registry metadata means actual admitted consultation, including a later unfinished lookup; an unconsulted table is Absent, and needed withheld knowledge has unavailable state with snapshot null. Completing these two areas alone does not complete any unfinished initial work. This follows ADR 0029: Content-format declarations and recorded registry guidance.

esdieff.expanded.pattern-syntax/1 explicitly requests those same initial eight areas plus pattern-syntax/1. It checks surviving effective Full string patterns with partial Unicode ECMAScript syntax capability, independently of explicit string type. Syntax-admitted and independently invalid inputs are assessed; no applicable string patterns after complete traversal is not applicable. Needed unknown context/text, unsupported syntax capability and operational limits make the one area undetermined. Every new condition carries that area identity. pattern.syntax is an RFC/ECMA error, pattern.unsupported uses Operational pattern-syntax-capability, pattern.unavailable uses pattern-establishment, and syntax operation.limit uses pattern-syntax-capability. Optional omissions preserve counts and status. See the pattern contract and ADR 0028: Bounded effective model pattern syntax.

Both ExpandedPatternSyntax and Full reserve 171 additional report bytes above the actual existing request envelope before composition or syntax work. The same reserve is removed from optional wire/scratch space. Full binds pattern syntax to M047 and full.pattern-format/1; repeated findings or limits do not add requested units. Initial, modified, unit, content-format, inspect and sample inventories retain their meanings.

full-baseline selects the immutable assessment and baseline rfc9880/base-1, area inventory esdieff.full-model/1, and its 54-member model relation rfc9880.model/1. The cited inventory covers the normative body and Appendices A/C with exclusive clause ownership, formal CDDL number rules and explicit nonmodel roles. Its 13 area members are full.document-syntax/1, full.model-roles/1, full.metadata/1, full.namespace-reference/1, full.composition-requiredness/1, full.critical-extensions/1, full.data-grammar/1, full.formal-numbers/1, full.scalar-meaning/1, full.pattern-format/1, full.compound-meaning/1, full.special-type-unit/1 and advisory-four/1. Known membership is independent of implemented capability. Every applicable unfinished requirement remains unassessed or undetermined. Sample admission, registry administration, device/protocol/operator duties and optional general analyses do not enter the model denominator.

Each model requirement joins its occurrences using undetermined before unassessed, assessed, then not applicable. Its owning area joins requirements once; the separate advisory area retains its existing meaning. Definite errors are assessed work. Full incomplete_checks counts unfinished areas among 13, while optional requirement aggregates count unfinished requirements among 54. They are never summed together. Historical Full reports with null inventory and coverage.inventory_unavailable remain interpretable as unknown membership, never an empty inventory.

Full broader coverage names rfc9880.model/1 with available membership. Its state is complete exactly when those54 model obligations are all assessed or not applicable; otherwise it is partial. The separate advisory area still contributes to the13-area requested outcome. Thus a model-complete report may have an incomplete requested outcome if only advice is unfinished. Completed model work can contain errors and a failed disposition; complete never means valid, universally supported or successful sample/device/protocol behavior. Full omits the optional broader omitted_areas list; absence does not establish completion. Other operations retain their partial/unavailable broader representation. Human and JSON presentations use the same state calculation.

Reports identify requested inventory, completion within it, and broader coverage separately. Coverage statuses are assessed, not_applicable, unassessed, or undetermined; assessed includes findings and does not mean satisfied. Unsupported applicable requested work is incomplete. Excluded initial work is outside that request and appears in broader coverage; it does not alone make the initial incomplete. Adding checks to meet existing inventory obligations is implementation progress. Enlarging membership, guards or semantic scope requires a new assessment/requirement identity. A bug fix may change a result for unchanged input while preserving the advertised meaning; it cannot silently redefine the meaning to match new behavior.

Report::assessment_area_status(id) returns a typed semantic status independently of optional coverage rows and conditions. Field::Present(AssessmentStatus) identifies a requested area; Absent means outside a known requested inventory; Unavailable means complete inventory membership cannot be established. An inspection requests no model assessment areas. Requested-but-not-applicable differs from not requested. Report::requested_coverage() exposes typed inventory, count-unit and aggregate accessors. Unknown needed context in any requested document makes the one modified area undetermined while independent definite errors remain visible.

Full also exposes requirement_inventory(), requirement_coverage(), requirement_status(id) and requirement_descriptors(). These borrowed accessors do not render or allocate a report. Known members have authoritative Present statuses even with zero retained detail; an unknown member is Absent, and other operations return Absent because they do not request the model inventory. Descriptors supply a stable ID, RFC citations, owning area and current check/limitation description. The description is capability documentation, never a runtime verdict.

Conditions preserve their producing assessment_unit. Full may add optional coverage_owner for the actual requested area. Modified work owns M012; both unit dimensions join M023 once; content work owns M024 and pattern syntax M047. Recorded extension values own M028. Required relationships preserve producing inspection and own M020 only in the Full recording context. Generic data conditions use the actual role and parameter: selector admission M034, numeric bounds M036, formal counts M037 and literal admission M035. No universal code-to-owner map is invented. Missing owner detail does not remove typed semantic states or mandatory inventory binding.

The report baseline records the RFC edition, specifically adopted corrections, interpretations, deviations, acceptance restrictions, and recorded external knowledge actually used. Temporal facts have their own interval and evidence identities, separate from registry knowledge. No registry snapshot means unavailable knowledge, not zero relevant entries or an unregistered-name conclusion. Findings identify a baseline requirement citation, recorded registration, adopted interpretation/deviation identifier, acceptance-policy identifier, advice class or operational limitation. Policy A001/A002 identities remain separate from RFC requirements.

Full content-format rule consultation records content-format-model-meaning/1 under the content-format contract. This records admitted use independently of successful establishment and optional diagnostics; it does not expand the existing content-format assessment’s scope.

baseline.interpretations lists copied-reference-relocation/1 from ADR 0036: Copied reference relocation whenever a result relied on it. That is when requested work relocated a copied reference, read a copied CURIE reference with its authoring document’s namespace mappings, or found that a name reference target in the resolved model differs from the document as written. The target differs when the written document has no element at its pointer, when the selected element holds copied content or a deletion that the written element lacks, or when composition removed the element the written document has there. A copied CURIE counts even when its prefix has no mapping in its authoring document. Reports that did none of these omit the identifier.

baseline.interpretations lists undeclared-extensions-ignorable/1 from ADR 0037: Undeclared extension vocabulary whenever a reported conclusion relied on it. That is when Full model meaning, contextual equality, declared-value consistency, numeric advice or Sample admission set aside undeclared extension vocabulary in a description and established its conclusion as if that vocabulary were absent. Recorded extension vocabulary set aside the same way, such as oma:id under ADR 0038: Recorded extension vocabulary, counts too when the report did not consult its recorded registry evidence. That is the case in a Sample report, in an assessment other than FullBaseline and in a FullBaseline check that withholds recorded evidence. Where FullBaseline consulted the evidence, setting the recorded quality aside names nothing. The sample contract describes the Sample case. An extension quality that no such conclusion consulted names nothing. Neither does one in a description whose base meaning is already stopped, for example by a base quality outside its role. Initial contradiction advice never consults the vocabulary. Reports that relied on no such description omit the identifier.

Outcomes, conditions and truncation

outcome contains complete, retained aggregate errors, warnings, notices, incomplete_checks, strict_warnings, and disposition. Requested work is complete only when every applicable requested requirement is assessed or established not applicable. Definite errors and scoped incompleteness can coexist. failed means an error exists or strict warnings are selected and at least one warning exists; otherwise unfinished work gives undetermined; otherwise passed. A failed incomplete result keeps complete:false. Strict warning policy changes disposition/exit eligibility, not warning severity, condition code, baseline meaning or error count.

Conditions have stable string code, severity (error, warning, notice, incomplete), basis, requirement/proof identity where applicable, optional primary source/effective/sample location, related locations and bounded structured arguments. Human message is explanatory and unstable. Report ordering is deterministic for the same supplied identities/request/version where practical, but consumers must not rely on ordering or wording. Codes are not message templates. For example:

This minimum code catalogue can grow additively with new operation-specific codes. Existing codes keep severity and meaning; changing either allocates a new code. Code parameters grow through optional fields without changing existing parameter meanings. Future codes are handled as strings with an unknown-code fallback; a client must still use structural severity/outcome. Future disposition/severity/basis semantics require a report major version, so a 1.x client can safely classify the fixed values above. The registration basis kind is the one exception. It joined version 1.0 in place because no report reader predates the first release, as recorded in ADR 0038: Recorded extension vocabulary.

The metadata.info_absent and quality.unfamiliar warnings identify their advice rules with a basis.id equal to the condition code and retain the supporting RFC citation. Advice identifiers and citations serve separate roles and can appear together.

Selected civil-value conditions use the domain, severity and basis catalogue in the civil-time contract. Actual convention use adds ADR0018-selected-representation to the shared interpretation array. Temporal knowledge retains its existing optional shape and records only actual C72 queries. These fields survive optional condition/witness/coverage omission and discarded branch evidence. Declared-value consistency keeps its existing advisory codes and check report shape.

The optional-vocabulary summary’s arguments.observed_occurrences is a Count of unsupported optional occurrences actually inspected in that source. It is bounded detail and can be absent if the condition is omitted; unfinished checking can leave additional occurrences uninspected. Check reports identify A001 and A002 in policy.restrictions, while standalone source inspection applies A002 without assessing SDF vocabulary. The A001 condition keeps its acceptance basis and current Action-input guidance, following ADR 0008: Reject the historical Action input quality.

Diagnostic count and byte budgets limit detail storage and rendering, not assessment. Aggregate counts and completion are updated before any condition is dropped. diagnostics records retained/omitted counts and count/byte/location omission reasons; details can be entirely empty while errors remain nonzero. Aggregate requirement-status and outcome counters remain even when coverage rows/details are omitted. Presentation-only pointer omission or condition truncation leaves otherwise completed checking complete. A semantic ancestry/storage/work limit makes affected requested conclusions incomplete. Rendering never allocates a complete oversized report and cuts it afterward.

Finite default work and allocation

ADR 0012’s input/number defaults remain: 4 MiB per source, 32 MiB catalogue, 256 documents, 64 nested containers, 100,000 JSON nodes per source, 1,024 bytes per number token, 512 coefficient digits, explicit exponent magnitude 1,000,000, and 2,000,000 numeric units per request. The following additional defaults close catalogue/derived/report amplification. They are capability, not standards limits or performance targets.

Capacity arithmetic is checked. Check work admits effective-result storage before composing the next root. Failed admission retains an operation.limit cause at that checked effective root, preserves earlier findings and supplied scope, and contributes to aggregate diagnostics even if detail is omitted. No zero/unlimited sentinel is accepted. Configuration validation enforces finite representable values, supported stack/identity ceilings, and enough report space for the mandatory supplied-source inventory; invalid configurations are request errors before work. Independent definite results and raw retained content survive limits. Builders allow lowering/raising supported budgets, but no public guarantee of accepting every arbitrary usize value exists.

A parser may borrow immutable raw source spans or allocate compact decoded values. Composition may share immutable/COW values or materialize them only after charging nodes, bytes and byte work. Either strategy must obey the same public limits. In particular, a 4 MiB opaque source value expanded thousands of times cannot bypass derived-byte/work budgets merely because its expansion count is under 100,000. Traversing shared content still charges check work. No performance target is invented; ordinary catalogue evidence is structural operation/allocation evidence and a bounded representative timing observation, not throughput qualification.

JSON report 1.0 and compatibility

Every supported JSON result is a single UTF-8 JSON object with schema:"esdieff.report". Required top-level fields are operation, request, sources, baseline, policy, outcome, coverage, diagnostics and result. Check and inspect retain version 1.0. Sample and author use their distinct version 1.1 payloads, edit adds version 1.2, diff uses version 1.5 after 1.4, and generate and trace add version 1.5 below. The sample contract, authoring contract, editing contract, revision comparison contract, generation contract and trace contract specify these operation payloads without changing check/inspect meanings. A reader rejects an unknown operation before interpreting its result. request identifies assessment/inventory identity and scope. sources includes every acquisition attempt with role, bounded identity/label and acquisition/decode/content-completeness status and never embeds whole source content. baseline identifies actual standards/corrections/interpretations/knowledge. policy identifies acceptance restrictions and strict warnings. coverage carries requested and broader inventories with aggregate statuses and optionally bounded rows. diagnostics carries aggregates, omission reasons and retained conditions. result is tagged by operation.

The tables below specify the normative shared check/inspect version-1.0 envelope. Later operation contracts add their own fields and tags. R means required; O means optional and omitted when absent. Only explicit T|null permits null. No absent optional field is interpreted as an assessed result. All maps admit additional optional fields under version-1.x rules, but every listed field retains its meaning/type. Id is a nonzero JSON integer from 1 through 256, unique within sources; IDs are request-local handles, not durable namespace/content identities. All references must select listed IDs; all source roles share that ceiling. Count is a JSON integer from 0 through 4,294,967,295; aggregate counters must not saturate or wrap. The accepted finite-work ceilings guarantee count bounds; configurations that cannot do so are rejected. Bytes is a Count measured in UTF-8 bytes except explicit raw filesystem-byte identity. Spans are [start,end] Count pairs with start <= end; spans cannot exceed retained source bytes. General JSON model numbers remain exact and are not restricted to Count.

The existing mandatory Full request.inventory binds both 13-area and 54-requirement memberships even when every new optional field is absent. Optional requirement rows have exact retained/omitted counts summing to54; a nonzero omission has one coverage.requirement_rows record with its reason and count. Area rows plus rows_omitted sum to the requested area total. Coverage-only omission also appears in diagnostics.omissions, sets truncated and links its reason in diagnostics.reasons. Consumers compare surviving condition multisets, including codes, bases, arguments, producing IDs and coordinates; duplicate facts cannot stand in for erased facts. Unknown additive fields, row order and human wording do not change meaning. Missing entire optional groups do not imply empty membership or finished per-requirement work. incomplete_checks counts each declared requested area once, independently of condition or row retention. Scope IDs and mandatory metadata remain within the original reserve; copied opaque source content is never automatically embedded.

Inspection does not implicitly request a model assessment. Its one declared inspection unit covers the acquisition, decoding, selection and, for an effective view, composition required to establish the requested view. Its explicit document selector supplies the root; unrelated candidate failures remain visible without alone making this work incomplete. Inspect outcome.complete is true only when that requested operation is complete, and incomplete_checks counts its one unfinished unit. An available subview does not erase other requested limitations. Broader coverage remains partial/undetermined: source inspection passing establishes a usable requested view, never RFC conformance. A presentation-only omission can produce a partial displayed payload while the operation’s semantic work remains complete. If required semantic view establishment is incomplete, the disposition is undetermined unless independent errors or strict warnings already make it failed. The operation tag and count_unit distinguish its one operation from check’s declared assessment areas without inventing a standards inventory.

Check result contains no additional payload beyond shared coverage. Inspection result contains a bounded source/effective selected view, explicit partial/unavailable state and explanations; large content is accessed via library-owned source or explicit CLI inspection output, never automatically included in every check report. Sample result contains separate sample source/selector, tagged admitted, rejected or undetermined conclusion and relevant effective model selector/locations. Authoring result contains generated-document identities/content availability, assessment and fidelity state (established or undetermined); generated bytes are obtained from owned result accessors or an explicit CLI document output. Its generated catalogue supports the same check and inspection operations. Failed or limited authoring never presents a partial candidate as faithfully completed output.

Report wire types are explicit DTOs, independent of Rust struct layout/private graph/enum serialization. JSON null means the explicitly unavailable/absent field defined by its containing tag, never a generic successful default. Version 1.x permits additive optional fields and condition codes; readers ignore unknown fields and retain unknown codes, and handle integer aggregates without lossy floating-point conversion. Existing required fields, fixed outcome/severity/basis/acquisition/decode values, units and absence semantics cannot change within 1.x. Renaming/removal/type changes need a major version. New operations have new tags: a check/inspect reader rejects an unknown operation before interpreting its result. Future sample/author tags can be added with their own pinned contracts, without changing existing check/inspect meanings. Rust views/builders use private fields, nonexhaustive extensible result enums and stable accessors; implementation dependencies and storage remain replaceable. Rust source compatibility is maintained for documented public callers within the supported crate version family, with breaking interface changes explicitly versioned independently of the JSON report.

Authored-quality editing report 1.2

Operation edit uses version 1.2 under ADR 0034: Authored-quality editing with source substitution. The shared source, scope, outcome and diagnostic meanings remain intact. The edit envelope adds the following mandatory operation fields.

Generation and fidelity may be complete/established while a requested check leaves editing coverage undetermined. Completed checking with findings completes assessment of the editing unit but gives a failed disposition. Available Full model inventories retain 13 assessment areas and 54 requirements, including mandatory aggregate coverage when optional rows are omitted. Unavailable inventories keep their ordinary null meaning. Individual edits never inflate RFC completion counts.

Every supplied/generated attempt stays in sources, including the substituted original evidence. active_sources excludes that original and retains every other distinct contributor. Scope identifies actual generated roots, needed dependencies, assessed sources and unavailable required sources. Optional detail omission cannot remove source identities, substitution, edit count, errors, candidate completeness, fidelity or established checking aggregates. Diagnostic omission remains explicit through ordinary omission records.

Original source locations refer to original bytes, generated locations to generated bytes, and effective locations to the active Catalogue. Replacement findings can have related original-member and edit-request locations. A removed generated member is absent and has no invented generated span. These bounded relationships do not claim exhaustive provenance.

Revision comparison report 1.5

Operation diff uses version 1.5 under ADR 0039: Client-side revision comparison, ADR 0040: Acknowledged revision differences and ADR 0044: Versions of breaking revisions. Version 1.4 succeeded 1.3, because Difference acknowledgements change what the outcome counts and the disposition mean and add required fields. Version 1.5 succeeds 1.4, because outcome.warnings now counts Version warnings and diagnostics.items holds them. Every diff report is emitted at 1.5. It reports one comparison of an earlier and a later Catalogue. The shared source, outcome and diagnostic meanings remain intact, and the revision comparison contract specifies every field.

Generated values report 1.5

Operation generate uses version 1.5 under ADR 0041: Generated values settled by Sample-value checking. It reports the Generated values of one selected model document and their admissions. Composition spends the request’s allowance, each description’s values are built on an allowance of their own, and each value is checked with the allowance one sample request receives, so running out leaves only the affected description partial. The 64-value and 1024-description ceilings keep the request finite, and every description and kept value is charged the report bytes its largest rendering needs, so every output format fits report_bytes. Values and descriptions that do not fit are counted with byte_limit and report_limit records and leave the operation undetermined. The shared source, outcome and diagnostic meanings remain intact, and the generation contract specifies every field.

Recorded trace report 1.5

Operation trace uses version 1.5 under ADR 0042: Recorded traces with independent entries. It reports one Recorded trace checked against one selected model document. The document is composed once on the request’s allowance, each distinct Sample selector is resolved once, and each Trace entry is decoded and checked with the allowances one sample request receives, so a malformed or heavy entry affects only itself. The file, line and entry ceilings are request errors, and each listed entry is charged the report bytes its larger rendering needs, so both formats fit report_bytes. Failed and undetermined entries that do not fit are counted with a report_limit record. The shared source, outcome and diagnostic meanings remain intact, and the trace contract specifies every field.

SARIF projection

check --format sarif and diff --format sarif emit a SARIF 2.1.0 log for code-scanning annotations, following ADR 0043: SARIF and Markdown report projections. The library gives the same log through Report::to_sarif(directory) for a check report and RevisionComparison::to_sarif(directory), where directory is the directory relative paths were resolved from. A log projects the same report as the JSON format. It renders only the conditions or differences that report retained and changes no conclusion, disposition or exit code.

The log has one run. tool.driver names Esdieff and the crate version, and lists one descriptor per result code in rules and one per notification code in notifications. Each descriptor has the code as its id and short description. Its full description names a condition code’s severity and basis kind, which the code keeps, or what a diff classification, undetermined reason or warning code means, and its help text points to the contract that describes the codes. run.columnKind is unicodeCodePoints. run.originalUriBaseIds gives %SRCROOT% the invocation directory as a file URI ending in /, when that directory is known. run.properties holds the report’s disposition and the omittedResults and omittedNotifications counts described below. The one invocation has executionSuccessful:true, because the report was produced, and holds the tool execution notifications.

A check result is a retained condition of severity error, warning or notice, at level error, warning or note, with its code as ruleId and its message. Errors come first, then warnings, then notes. A retained incomplete condition is a tool execution notification at level warning instead, with its code as descriptor, because unfinished checking is not a finding about the model.

The physical location of a check result comes from its primary source location, or else from its first related source location, and the other related locations follow in relatedLocations. The artifact URI is the source’s file path relative to the invocation directory, with / separators, percent-encoded segments, . and .. segments resolved as RFC 3986 resolves them, and the base %SRCROOT%, so code scanning finds the files when Esdieff runs from the repository root. A path outside the invocation directory, whether absolute or reached through .. segments, becomes an absolute file URI without a base. The region comes from the retained byte span. startLine and endLine count lines from 1, where CR, LF and CR LF end a line. startColumn and endColumn count Unicode code points from 1 within the line, and endColumn is the column just past the span. byteOffset and byteLength give the span itself. A location without a span, such as a source that could not be acquired, is a file-level location whose region is only startLine:1, because code scanning requires a start line. An effective location becomes a logical location whose fullyQualifiedName is the effective pointer, with properties view:"effective" and document, the label or else the key of its root document. A source without a UTF-8 file path, such as standard input, has no physical location, and its source pointer becomes a logical location with view:"source".

A diff result is a Version warning or a retained difference. Version warnings come first, each at level warning with its code as rule, located at the later document’s version or the nearest member that would hold it, with the earlier version as a related location. Differences follow in report order. A breaking difference is level error with rule comparison.breaking, an undetermined one is level warning with its reason code as rule, and a compatible one is level note with rule comparison.compatible. The message names the classification, then the kind, subject, document source key and effective pointer, and the undetermined reason or the Breaking witness with its admissions, in the words the Markdown changelog uses. Every diff result carries suppressions. An Acknowledged difference has one suppression of kind external with status accepted, so reviewers still see the break while code scanning treats it as intended, and the list is empty for every other difference and every Version warning. The later revision’s side locates the result when it has a nearest content origin, or when the earlier side has none either. Otherwise the earlier side does, as for a removed definition. The side’s origin gives the physical location, and its effective location gives a logical location with the property revision. The other revision’s side is a related location whose message names that revision.

The log stays within the report byte limit, which it applies on its own, so it can show differences whose details the JSON report left out for space, and the other way around. After the envelope, results and then notifications are kept in order while they fit, and the first that does not fit ends the list. omittedResults counts every finding the outcome counts that the log does not show, whether the report or the log left it out: the errors, warnings and notices of a check, and every Version warning and difference of a comparison. omittedNotifications counts the incomplete conditions of a check the same way. When either count is nonzero, a final notification at level warning states both.

Markdown changelog

diff --format markdown and RevisionComparison::to_markdown() give a Markdown changelog of a Revision comparison for release notes, following ADR 0043: SARIF and Markdown report projections. Like the SARIF log, it projects the same report as the JSON format, renders only the differences that report retained and changes no disposition or exit code.

It starts with the title # Model changes and a disposition line that counts breaking, undetermined and compatible differences, and the acknowledged ones when acknowledgements were supplied. A Warnings section lists each Version warning with the later document, its version or the place it is absent, the earlier version, the breaking count and the code. Sections follow for unacknowledged breaking, unacknowledged undetermined, compatible and acknowledged differences, in that order, and a section without differences is left out. Each item is one list entry naming the kind, the subject, the document’s source key and the effective pointer, taken from the later revision’s side when it has one. An undetermined item adds its reason and code, and an item with a Breaking witness adds the witness value, its Client direction and both admissions. An acknowledged item starts with its classification.

Model text appears only in code spans, including Given Names in pointers, quality names, source keys and witness values. A span’s fence is longer than any run of backticks inside it, and control characters, line breaks among them, become \uXXXX escapes, so a name can neither end its span nor start a new block. Reason messages are plain text with Markdown punctuation escaped.

The changelog stays within the report byte limit, which it applies on its own like the SARIF log. Items are kept in order while they fit, warnings first. When any difference or warning is not listed, whether the report or the changelog left it out, a closing line counts them.

CLI contract

The direct command is esdieff check [--directory DIR] [--recursive] [--exclude RELATIVE_PATH] [--root INPUT] [--assessment initial-v1|expanded-modified-v1|expanded-units-v1|expanded-content-format-v1|expanded-pattern-syntax-v1|expanded-numeric-v1|expanded-consistency-v1|full-baseline] [--registry-knowledge recorded|withheld] [--strict-warnings] [--format human|json|sarif] [INPUT...].

At least one positional INPUT or directory request is required. INPUT is an explicit file path or - for one stdin document. Repeat --directory DIR to prepare model sources from several directories. --recursive enables descent for all supplied directories, and repeatable --exclude RELATIVE_PATH omits literal files or subtrees relative to each directory. These traversal options require a directory request and apply only to direct checking and diff. Plan mode, inspect, sample, author and edit do not accept discovery options. The directory discovery contract defines selection, ordering, overlap and finite preparation limits.

An explicitly selected root must match exactly one supplied attempt by its exact native acquisition path. For a discovered root, this is the joined directory/file path. Directory, positional file and root paths resolve from the invocation directory. Repeated -, unknown or multiply matched roots and malformed options are usage errors. Positional files and discovered files are model candidates. Position never picks the root. Default roots are absent, which requests catalogue scope. Non-UTF-8 filesystem paths get a safe display label with their distinct identity preserved. Path labels are not namespace meanings.

The default is initial-v1; expanded-modified-v1 explicitly selects the fixed nine-area inventory, expanded-units-v1 selects the ten-area unit inventory, expanded-content-format-v1 selects the ten-area declaration inventory, expanded-pattern-syntax-v1 selects the fixed nine-area inventory comprising the initial eight plus pattern-syntax/1, expanded-numeric-v1 selects the Initial eight plus advisory-numeric-three/1, and expanded-consistency-v1 selects the unchanged Initial eight plus const-consistency/1 and default-consistency/1, with requested denominator 10. Explicit registry-knowledge values require an expanded unit/content or full-baseline assessment.

After successful invocation preparation, exactly one requested report goes to stdout, with a trailing newline. Directory preparation failures exit 2 with stderr and empty stdout before model content or stdin is read. Acquisition and decoding problems are in the ordinary report. stderr contains usage errors and output/host failures, not semantic conclusions omitted from JSON. Human and JSON formats use the same outcome/scope/coverage/baseline/policy. Exit 0 is passed requested work, 1 is failed (including strict warnings), 2 is invocation/configuration error, 3 is undetermined work without blocking errors, 4 is inability to emit the requested report or another host operation failure. Failed+incomplete uses 1 and keeps structural incompleteness. Truncated detail alone does not change exit status. stdin is read under input limits; no implicit retrieval/discovery occurs.

--format sarif emits the SARIF projection of a direct check or diff report, and --format markdown the Markdown changelog of a diff report, each with the exit code of that report’s disposition. Plan mode, inspect, sample and trace refuse --format sarif, and every operation other than diff refuses --format markdown, each with exit 2 and empty stdout.

esdieff diff --old PATH --new PATH [--recursive] [--exclude RELATIVE_PATH] [--acknowledged FILE] [--format human|json|sarif|markdown] compares an earlier and a later Model revision and emits one revision comparison report. Both PATHs are directories or both are files. Each directory is prepared separately with the directory discovery rules, and --recursive and --exclude apply to both. A document’s source key is its path relative to its directory, with components joined by /, so documents pair by location. In the two-file form both documents take the key document and correspond directly. A file beside a directory, - on either side, a missing --old or --new, a nonexistent PATH, and a relative path that is not UTF-8 or exceeds the 256-byte source key are invocation errors. Standard input is never read. --acknowledged FILE may appear once and names a file of Difference acknowledgements. The file is read and decoded before either revision’s content, and -, an unreadable file and any file the acknowledgement decoder refuses are invocation errors. Both revisions finish preparation before either one’s content is read, and both are acquired and compared under one operation allowance. Exit codes follow check and the disposition, which only unacknowledged differences decide: a comparison passes with exit 0, an unacknowledged breaking difference exits 1 and otherwise an unacknowledged undetermined one exits 3.

diff also accepts --acknowledgements-output FILE and --replace-acknowledgements. They write the JSON report’s eligible acknowledgement entries to a named file for review, following the acknowledgement export rules. Export preserves the report format and comparison exit status. Existing output requires explicit replacement and cannot alias a selected revision document or supplied acknowledgement file. Invalid destinations and exports the acknowledgement reader cannot accept exit 2 before delivery. Delivery failures exit 4.

esdieff generate --document MODEL [--kind KIND --pointer POINTER] [--format human|json|jsonl] MODEL_INPUT... emits the Generated values of one selected description, or of every affordance description of MODEL, as one human report, one generate report or JSON Lines Trace entries. MODEL, the inputs and - follow esdieff sample, and --kind and --pointer come together or not at all. A selector that selects nothing is an invocation error. Exit 0 is generation completed for every selected description and 3 is any other result, since generation never fails.

esdieff trace --document MODEL --trace FILE [--format human|json] MODEL_INPUT... checks the Recorded trace FILE against MODEL and emits one human report or one trace report. MODEL and the inputs follow esdieff sample. FILE is a path or -, and standard input may be used once across the inputs and the trace. The trace is read before any model input, and a trace that is missing, unreadable or larger than 64 MiB, a line over 1 MiB and more than 100,000 entries are invocation errors. A malformed entry fails only itself. Exit codes follow check: 1 for any failed entry, otherwise 3 for any undetermined entry, otherwise 0.

esdieff inspect --view source|effective --document INPUT --pointer POINTER ... is a complementary explicit inspect operation using the same report metadata/locations; callers can inspect retained source after assessment failures. Effective inspection never silently falls back to source. Its selector and requested output remain finite. Future sample/author commands use distinct operation tags and the shared source/report/exit rules, but operation-specific selectors, request options and document write/collision behavior are separately specified before those commands ship. Authoring’s report and document bytes have separate explicit destinations; it never mixes a report and generated SDF on stdout or writes an unasked destination.

Concrete cross-workflow obligations

The six-class Temperature/Sensor/Device fixture provides source and effective views: all six classes appear, ambient’s inherited minimum is -50, maximum 100, writable false, Event-output maximum 150, deleted description absent; source Sensor/Temperature are unchanged. The Controller/Level fixture uses explicit Controller roots, differently named prefixes for one namespace, minimum 0, maximum 80 and deleted description with unchanged source Level. Scope contrast adds an independently bad unused source: catalogue work fails, selected relevant work retains its appropriate outcome, and every supplied source remains visible.

For the selected temperature sample 101, a later sample request reports rejected, with sample root pointer ""/byte span [0,3] and model effective maximum path ending /maximum, related to the patch maximum 100; source Event-output maximum 150 is irrelevant to this selected description. Undetermined sample meaning cannot become rejection. Sample admitted/rejected is independent of strict-warning disposition. Sample request details remain future contract work, but its source/result/location foundation is settled here.

For a later authored Device Thing built from Sensor with the same override, the result owns generated SDF documents with new generated source identities, an assessed catalogue and effective views, while reusable source identities/content remain unchanged. Generated known numbers retain mathematical values and accepted unchanged lexemes. It reports any opaque-context fidelity limitation; structural retention alone is insufficient. Name/namespace request assembly, collision choices and file write policy remain the separate authoring decision. The shared contract does not force an internal flattened format, generic mutation API or speculative plugin system.

Explicit unit assessments add policy.recorded_registry, result.unit_guidance, and actual-use entries in baseline.registry_knowledge and baseline.interpretations under the existing 1.x additive field rules. The ten-area profile preserves the initial eight meanings. Fixed counters, null owner failure, scoped dated positives, withheld evidence and independent consultation/completion meanings are specified in the unit contract, following ADR 0027: Unit names and recorded registry guidance. Optional row and located-advice omission does not remove semantic summary fields. Full joins both unit dimensions into M023 and its requested special-type/unit area once.

Selected resource formats retain the Sample report version 1.1 and its nine-area inventory. baseline.format_knowledge contains only the six facts actually consulted by that Sample request, or null if its initial consultation owner could not be established. An established empty observation array differs from initial unavailability. The borrowed Report::format_knowledge getter and each static record’s four fields follow the URI and UUID sample contract. Non-Sample operations omit this field. UUID interpretation identities share the existing interpretation array; optional presentation omission preserves both.

Selected abstract-value meaning

Sample report version 1.1 adds mandatory result.meaning.abstract_values, result.meaning.const and result.meaning.admission. The two area objects have status, basis and limitations; their statuses exactly match sample-abstract-values/1 and sample-const/1. The admission object has basis and limitations, alongside the existing authoritative result.admission. The library exposes these same finite sets through SampleResult::meaning(). Not-applicable areas have empty sets. Undetermined admission has an empty supporting set. A definite independent rejection can retain its proof while an abstract obligation remains unfinished. A complete ordinary admission includes the general Appendix C reference without making absent const applicable.

References are unique complete (kind, id, citation) triples, in stable producing order. RFC references have a precise citation and no ID. Interpretation references have an immutable ID and precise citation. Operational references have an ID and preserve an existing precise citation when one exists. In particular, the temporal-knowledge, temporal-meaning and resource-meaning limitations retain their distinct cited triples even when IDs coincide with a general establishment limitation. The producer’s 24 support tags project to at most 23 unique references: temporal exceptional-slot and leap checks share the same RFC citation in this view. Original diagnostic and temporal-knowledge identities keep their existing shapes. The limitation inventory has nine unique triples. Borrowed iterator length and size hints count emitted unique references.

SampleResult::consulted_interpretations() observes actual request consultation of byte-string-json/1 and unix-time-posix-coordinate/1. Their union also appears in mandatory baseline.interpretations. An attempted interpretation survives discarded candidates, representation rejection and later limits. Consultation does not establish final support. Recognition alone, unavailable context, null-only admission and refused input preflight do not claim use. Existing civil and resource observations retain their separate contracts.

A later whole choice or enum witness replaces earlier tentative const proof and limitations. An unknown potentially matching branch prevents universal exclusion. Independent model findings and established sample areas remain authoritative. The human report prints the same three reference sets and consulted sample IDs; its labels and prose remain presentation details. Optional row/detail/location omission never removes mandatory statuses, references, consultation or counts.

The channels and their limits follow ADR 0007: Generated SDF and sample JSON, equality follows ADR 0015: Bounded value equality in a resolved data context, and ownership follows ADR 0025: Selected numeric samples. These are information-level conclusions, without a formal CDDL or protocol binding claim. Check and inspection retain their current payloads and report version. An older Sample 1.x report lacking the additive meaning fields leaves this capability unavailable; absence does not mean not applicable or established.

Supplied source documents

Esdieff accepts explicit SDF documents and retains every acquisition attempt. Source inspection and typed source projections are available independently of completed model assessment, following ADR 0013: Shared workflow and report guarantees.

For deliberate retrieval of a pinned public GitHub file into a new local snapshot, use the separate acquisition operation. Its receipt is independent of ordinary Model checking and is never loaded automatically.

The command accepts files and one standard-input document:

esdieff check --format json model.sdf.json
esdieff check --assessment expanded-modified-v1 --format json model.sdf.json
esdieff check --assessment expanded-pattern-syntax-v1 --format json model.sdf.json
esdieff check --root product.sdf.json common.sdf.json product.sdf.json
esdieff inspect --view source --document model.sdf.json --pointer /sdfData/Temperature model.sdf.json
esdieff check --format json -

All supplied files are candidates; their order selects no model role or precedence. A root or inspection document must explicitly name a supplied input. Use -- before a filename beginning with -. Paths retain their exact filesystem identities even when their display labels need Unicode replacement. Namespace URIs do not trigger acquisition.

Direct check also accepts repeatable --directory DIR inputs. It selects immediate regular .sdf.json files, or descends with --recursive, before ordinary acquisition. Repeatable --exclude RELATIVE_PATH prunes literal files or subtrees relative to every supplied directory. See directory discovery for selection, overlap and finite-work rules and a runnable mixed collection. Discovered roots use their joined acquisition paths relative to the invocation directory. Rust inputs and saved Check plan version 1 retain their existing explicit-source contracts. esdieff diff --old PATH --new PATH compares two Model revisions supplied as two files or two directories. Directories use the same discovery rules, and each discovered document is keyed by its path relative to its directory.

The Rust library supplies the same operations:

#![allow(unused)]
fn main() {
use esdieff::{Catalogue, Class, CheckRequest, InspectRequest, SourceInput};

let catalogue = Catalogue::from_inputs(&[
    SourceInput::supplied("sensor", br#"{"sdfData":{"Temperature":{"type":"number","maximum":100}}}"#)
        .label("Sensor description"),
])?;
let id = catalogue.source_id("sensor").expect("supplied source");
let report = catalogue.check(CheckRequest::new().root(id))?;
for condition in report.diagnostics().conditions() {
    println!("{}: {}", condition.code(), condition.message());
}
let source = catalogue.source(id).expect("listed source");
let temperature = source.definitions(Class::Data).require()?.next().expect("definition").1;
let maximum = temperature.data_description().require()?.number("maximum").require()?;
assert_eq!(maximum.lexeme(), "100");
let inspection = catalogue.inspect(InspectRequest::new(id, "/sdfData/Temperature"))?;
assert!(inspection.outcome().complete());
Ok::<(), &'static str>(())
}

Condition::primary() returns the location a condition is about and Condition::related() yields its related locations in report order, both as a ReportLocation. An absent primary means the condition has no single location, and an unavailable one means the report could not establish it. Source and sample locations carry their SourceId, pointer and any available byte span. Effective locations carry the root document of their effective-document space and a pointer, with no source id or span. Author and edit request locations keep their request key, pointer and any available plan span.

Catalogue::take_inputs consumes SourceInput::owned buffers; bounded buffers move into retained storage. Oversized spare capacity is reduced before retention, and retained capacity consumes the catalogue byte allowance. Borrowed inputs are copied into owned storage once. Identity metadata is validated before copying or acquisition. Limits changes supported finite acquisition, decoding and presentation allowances; zero and unsupported configurations are request errors.

Source views distinguish Field::Absent, Present and Unavailable. They expose all six classes, nested source groups, authored Property flags, Action input/output, Event output, data types, declared defaults, required map-entry syntax, choice branches and opaque JSON. They retain the full-description or direct-item context. Authored choice branches have no implied shared-quality inheritance; sdfRequired syntax has no implied resolved declaration identities. Source access inserts no effective defaults. Wider direct-item content remains accessible as raw JSON while unsupported typed meaning is unavailable.

Source and effective data descriptions expose minimum(), maximum(), exclusive_minimum(), exclusive_maximum(), multiple_of(), minimum_length(), maximum_length(), minimum_items() and maximum_items() as borrowed exact numbers. Positive steps and nonnegative integral lengths/counts distinguish malformed shape from absent or unavailable capability, without machine-sized count limits. Named pattern(), format(), sdf_type(), unit(), content_format() and unique_items() access preserves available scalar content without claiming syntax, registry, sample or consistency assessment. Unfamiliar selectors retain their text and unsupported meaning. constant() and declared_default() retain JSON without inserting values. These guarantees follow ADR 0022: Scalar constraints and characteristic states.

Property readable_characteristic(), writable_characteristic() and observable_characteristic() return Characteristic::Declared(bool) for an authored value in the inspected view, including inheritance, or SpecifiedDefault(true) for established effective absence. Source absence remains Field::Absent. The existing Boolean methods return the same values, and provenance remains available separately. A specified default characteristic is distinct from documentary default data.

Data-description nullable_characteristic() uses the same states for null admission. Full effective absence after inheritance/overrides has the specified value true; source absence stays absent. Direct-item nullable and its implicit default retain their unresolved meaning. Nullable, mandatory presence, documentary default and const are separate, following ADR 0024: Effective alternatives and nullable characteristics.

Grouping definitions expose repetition_minimum() and repetition_maximum() as authored exact numbers. Array-data descriptions keep their own minItems and maxItems qualities. A present class keyword outside an established base containment role has an unavailable typed child projection and retained raw JSON; its spelling alone does not establish an invalid model under the extensible framework.

An exact number retains its original JSON lexeme and offers sign, integrality, checked machine conversion and budgeted exact ordering. Scalar decoding limitations preserve raw source values and independent usable views. Duplicate decoded member names are refused at every depth under A002; no first or last value wins. These guarantees follow ADR 0012: Exact numbers and JSON input policies.

Checking identifies established source Given Name, document-block, definition-map and namespace-mapping problems. Names compare case-sensitively; spaces, slashes and tildes remain usable through escaped JSON Pointers. Literal data and opaque extension content do not acquire base definition roles merely because they contain familiar spellings.

Full data descriptions at Property and sdfData definitions, Action input/output, Event output and established nested properties or choice alternatives check parameter shapes recursively: strings, Boolean flags, numeric bounds, positive multipleOf, nonnegative integral lengths/counts, nonempty string-array enum, and map-shaped properties, sdfChoice, items and named full descriptions. Direct items descriptions check the restricted base shapes: number-valued minimum/maximum, nonnegative integral minLength/maxLength, text-valued type/format, nonempty string-array enum, and map-valued sdfChoice. Explicit object items check their properties map and each Full data description within it. Item choice alternatives are also Full data descriptions, so array alternatives and ordinary array-valued properties retain their recursive checks.

Map-data required receives its nonempty string-array shape check in Full data descriptions and Direct items descriptions when a reliable explicit type:"object" establishes its base context. Missing, nonobject, extended or unavailable type and unknown member identity do not establish that context. The borrowed required_entries() accessor presents nonempty authored syntax: Present alone does not establish an applicable object constraint, resolve sdfRequired, or check sample presence. Full descriptions retain documentary syntax access independently of applicability; Direct items descriptions retain their object guard. Empty lists and unavailable decoded entries remain typed Unavailable rather than authored absence. These source and effective distinctions follow ADR 0020: Owned effective views and nearest origins.

Surviving enum and sdfChoice conflict in both established roles independently of their values’ shape; ordinary null still occupies the quality, while possible reference-patch null deletion is deferred to composition. Unavailable decoded text does not become a nonstring error. Wider direct-item array, default, nullable, nested-items and other content stays available through raw JSON; needed typed meaning remains unavailable. It does not acquire full semantics or a blanket nested-array ban. Declaration requiredness, contradictions and sample admission remain separate unfinished work. The sdfType lexical restriction and wider extension meaning remain explicitly unassessed. These recursive role and provenance guarantees follow ADR 0020: Owned effective views and nearest origins.

The Information block’s title, description, version, modified, copyright, license and $comment entries receive string-shape checks. Established definitions and full data descriptions also check description, label and $comment; Direct items descriptions check their established description and $comment metadata. String contents do not acquire a semantic-version or SPDX requirement. The explicit expanded modified request additionally checks Gregorian dates and UTC labels, independently of composition, under the modified metadata contract. Its early Information pass records a reliable nonstring modified exactly once before unrelated traversal. Reliably absent info receives a nonblocking warning, following ADR 0003: Check findings and completeness. Strict warning policy changes the outcome disposition while retaining the warning’s severity and basis.

Unfamiliar unqualified Quality Names receive spelling advice. Familiarity covers the base spellings defined in the recorded RFC, including information qualities. Initial and expanded assessments give each assessed source at most one optional-vocabulary notice summarizing recognized qualified spellings, familiar names outside their established role and unfamiliar textual type, format or sdfType selectors. Its bounded observed_occurrences argument counts the occurrences actually inspected, which can be fewer than the source contains after a work limit. Full instead names and locates each inspected occurrence in its own notice, keeping observed_occurrences: 1 for source occurrences. It leaves out oma:id at its registered positions, because it checks that Recorded extension vocabulary itself. Both optional Full notices and unfamiliar-name warnings carry the decoded name in arguments.quality, also shown in human reports. The report contract describes bounded retention and omitted locations. Qualified spelling recognition establishes neither registration nor extension meaning. Given Names, namespace prefixes, literal const/default/enum content and opaque extension subtrees are excluded from Quality Name scanning. No registry snapshot or retrieval is implied, following ADR 0002: Recorded standards baseline.

Acceptance restriction A001 rejects sdfRequiredInputData at assessed vocabulary positions with guidance toward sdfInputData and an object input’s properties and required. The condition has acceptance basis A001, rather than an RFC-invalidity claim, following ADR 0008: Reject the historical Action input quality. A source composition patch’s null member is a deletion selector. A proven surviving non-null metadata or historical quality can retain a target-independent finding at a reliably established role; this does not establish the whole Effective definition. Unknown needed context and opaque keys remain deferred. Source inspection assesses no SDF vocabulary and remains available independently.

In established definition and data-description roles, any present sdfRef or unavailable member identity conservatively leaves possible merge/deletion context. Null members then cannot establish surviving qualities, including with wider reference forms. This uncertainty proves neither a valid reference nor resolved composition. An unsupported sdfRef spelling in an Information block or document map leaves its opaque content retained and does not import reference semantics into that role. These boundaries follow ADR 0006: Scoped reference failures and RFC 7396 Section 2.

Namespace mappings use generic RFC 3986 URI syntax, including percent escapes, bracketed IP literals, queries and fragments. Syntax checking introduces no scheme, DNS or retrieval requirement, and different documents may share a namespace URI. Grouping repetition counts must be nonnegative mathematically integral numbers; their shape check proves no grouping emptiness. In a source composition patch, null deletions are deferred to effective processing, while surviving names and definite non-null map/count overrides retain independent findings.

Before emitting structural or vocabulary findings, checking establishes the document’s declared critical-feature context. Reliably absent info, or a readable information map with reliably absent features or an empty feature array, permits ordinary base checking. Other declarations and unavailable relevant identities defer this source’s structural semantics, including namespace, metadata and A001 conclusions, with an explicit limitation. A readable text list of unsupported critical features receives its own explanation; wider or unreadable declarations receive a scoped inability-to-understand condition without a closed-grammar rejection. Supplied JSON decoding, duplicate-name refusal and the top-level map envelope remain independent; unaffected companion documents continue to receive their findings. Extension meaning remains unsupported, apart from the recorded value domain of oma:id.

Effective composition copies established definition and full-data targets, processes mandatory target-root references, then applies the consumer’s JSON Merge Patch without sdfRef before resolving surviving nested references. A consumer deletion can remove an otherwise unavailable nested reference. Opaque maps, Information blocks and direct-item imports do not gain full-definition meaning through map shape alone. Missing targets, cycles and unsupported reference forms leave affected portions explicitly unavailable, following ADR 0006: Scoped reference failures. A name reference selects the element at its pointer in the target document’s resolved model, for same-document pointers and CURIEs from other documents alike, so declarations that exist only through a copy can be referenced and required. Looking up the pointer composes each sdfRef on its path before descending, on the same work, node and reference allowances. Path compositions nested inside the lookups of other path compositions stop at a fixed stack bound of 32 levels, or the reference depth when that is lower, and exceeding it leaves the affected result undetermined with operation.limit. A copied sdfRef whose target, read in the context of the document that wrote it, is the copied definition or lies beneath it by pointer tokens relocates to the corresponding position in the importing definition and selects there in the resolved model. Relocation repeats at every enclosing copy boundary, so nested copies and target root chains follow the final importer’s refinements, while other copied references keep their original target. A target that a patch deleted is missing, with no fallback to the source, and a cycle through relocation or path composition is a scoped failure at the reference, following ADR 0036: Copied reference relocation.

Supplied CURIE composition uses the reference’s original namespace mapping and literal concatenation of its binding and reference tail. A copied CURIE keeps the mappings of the document that wrote it, even when the importer maps the same prefix differently, while one written in a composition patch uses the importer’s mappings even when its text equals the inherited one. A prefix that the writing document never mapped is the unmapped-prefix error at that original reference. Esdieff establishes a supplied target by exact decoded namespace text and a percent-decoded JSON Pointer fragment, without URI normalization, relative-URL resolution or retrieval. The supported prefix subset is ASCII [A-Za-z_][A-Za-z0-9_.-]*; wider NCName characters retain an explicit capability limitation. Multiple documents may contribute different addressed definitions to one namespace. Each contributor addresses the pointer in its resolved model, and an ambiguous or unavailable import met while composing its path leaves the lookup unavailable. Multiple contributors to the same address remain ambiguous even with identical content. Reliable missing prefix mappings and established malformed reference syntax are errors; a mapped but unavailable target is incomplete. Each such error is one finding at the reference as written, however many copies or checked documents reach it, while an unavailable target is reported at each effective position it leaves unfinished. Fragment-bearing bindings retain every character during assembly, so unsupported assembled forms cannot silently select another address. These boundaries follow ADR 0023: Supplied global composition and dependency scope.

Global candidate discovery first establishes the context needed for a contribution identity. Clear-context reliable absence of defaultNamespace excludes a contribution; raw absence under unknown critical features does not. An unreadable acquisition, envelope or relevant member also remains an unavailable possible contributor. Such uncertainty can prevent a unique lookup without making that candidate an established imported dependency or assessing unrelated definitions and metadata. Catalogue checks independently assess every supplied source; selected checks independently assess roots and examine only surviving dependency content through the shared effective evaluator. Imports met while composing a contributor’s path to a global target are needed dependencies too. Explicit expanded modified assessment additionally examines info.modified once per distinct needed dependency source, without assessing its other Information qualities. All supplied attempts remain visible.

Catalogue::effective(EffectiveRequest::new(id).pointer("/sdfThing/Device")) returns an owned effective result borrowing the catalogue. Its typed definitions, groupings, affordances and data descriptions use the same established roles as source access. A selected opaque map retains generic JSON access; typed class collections require an established parent role that permits that class. Known collection entries yield (name, Field<handle>), so an unavailable entry retains accessible siblings. Generic JSON traversal preserves independently established subviews; generating a semantically incomplete containing subtree returns Unavailable. Original scalars retain exact source lexemes and locations.

InspectRequest::required_declarations(true) requests declaration relationships in the selected source or effective subtree of a Model source. Sample sources are rejected before definition lookup in either view; ordinary raw source inspection of a Sample remains available. The command equivalent is esdieff inspect --required-declarations. Report::required_declarations() is Absent by default; when requested its collection reports state(), complete(), unavailable_reason() and owners(). Owner syntax and reference/target views preserve known invalid, missing, ambiguous and unavailable relationships independently. Short names select every directly contained affordance/grouping class sharing that Given Name, including the empty name; true array entries select the carrying affordance/grouping. These relationships do not interpret map-data required or nullable as declaration optionality.

An established outside pointer target has a source Definition, a complete relationship and capability NotRequested; its effective Definition is Absent. Request Catalogue::effective explicitly to examine that target’s content. In-scope targets expose actual processed coordinates and refinements, with capability completion separate from relationship completion. An authored pointer to an outside reusable contribution does not acquire the coordinate of a copy inside the selected subtree. Pointer entries resolve at their coordinate in the resolved model in both views, so an importer’s pointer to a declaration that exists only through its copy is resolved, and a deleted one is missing. The source view reports such a target with its source Declaration contribution and capability NotRequested. The target’s source Declaration contribution survives map refinement and root data-description substitution, while content origins and importing consumer retain their existing meanings. A copied pointer whose target, read in the context of the document that wrote it, is the copied definition or lies beneath it relocates to the importing definition’s coordinate like a copied sdfRef and selects the declaration there with its own Declaration contribution. Deleting that declaration leaves the relationship missing, and a declaration reinserted at the coordinate is the one selected. Data-only requiredness can remain unavailable while independent short-name or outside-pointer siblings are resolved. Source matches remain partial when unresolved inheritance could add matching classes. These distinctions follow ADR 0026: Required declaration relationships and source evidence.

EffectiveModel::explanation(pointer) identifies nearest content contributors, including deletion. Its consumer() identifies the source importing sdfRef when a composition boundary is established, independently of content origins. A mandatory target-root chain keeps the outer consumer; a separately composed nested reference starts its own boundary. default_explanation(pointer) separately identifies established implicit Property capability and full-description nullable defaults with no fabricated source. Deleting inherited writable:false leaves the JSON member absent, retains its deletion explanation and yields the typed true default. Defaults are never inserted into source or composed JSON. Copied sdfRequired pointers in definitions keep their authored text and available typed requiredness, and relocate when their relationships are resolved; independent targets and directly contained short names remain distinguishable. Copied prefixed sdfRef and sdfRequired references are read with their authoring document’s mappings, and both relocate when they point into the copied definition. Whether a reference is copied follows its own sdfRef member or sdfRequired array. Only one written in the composition patch belongs to the importer, so patching a sibling quality such as a description leaves a copied reference copied, following ADR 0036: Copied reference relocation. A copied pointer into the copied definition from a full data description, including Action input/output and Event output, keeps the separate data-only limitation with unavailable typed requiredness, while independent constraints remain accessible. Direct-item requiredness meaning remains unestablished. These ownership and provenance guarantees follow ADR 0020: Owned effective views and nearest origins and ADR 0023.

EffectiveDataDescription::alternatives() yields (AlternativeId, Field<EffectiveDataDescription>) after actual reference composition and shared-quality inheritance. Choice names and enum occurrence indices retain identity; enum values become const alternatives without changing composed JSON. Surviving explicit qualities replace whole shared qualities. Reference-deleted branch qualities permit shared fallback, while ordinary const null remains a value. Nested collections derive after their final inheritance. Absent, known empty and unavailable collections differ from individually unavailable branches. Known partial branches retain accessible independent qualities, including inherited bounds, while inherited restricted donor qualities stay typed-unavailable until explicitly overridden. source_alternatives() remains the composed branch syntax without shared inheritance. Existing pointer selectors select composed JSON; derived branch origins use direct EffectiveJson::explanation(), quality_explanation(key) and default_explanation(key) handles. This bounded view follows ADR 0024: Effective alternatives and nullable characteristics.

Checking assesses both source definitions and surviving effective vocabulary through shared rules. Composed contexts can produce distinct effective observations, even when a contribution retains a source origin. An unchanged local source observation is skipped only with proof of completed source evaluation, identical role and clear feature context, and unchanged rule premises. Source optional-vocabulary notices retain their actually-inspected observed_occurrences meaning; effective notices omit that source-count argument. Full effective notices identify the effective position and retain the nearest source contribution as a related location.

The initial assessment retains all eight fixed areas. Full has established immutable membership: thirteen assessment areas in esdieff.full-model/1 and fifty-four model requirements in rfc9880.model/1, described in the model assessment inventory. Applicable unfinished work still limits requested completion. Source acquisition and inspection do not imply completion of a requested assessment. Effective inspection establishes only its selected view and necessary composition, without implicitly assessing Information metadata or model vocabulary. A selected inspection can pass while an acquisition outside its needed work failed; a global lookup requiring that candidate’s contribution identity retains uncertainty. Every candidate still appears in its report.

Reports use JSON report 1.0. Human and JSON output share outcome, source identities, scope, requested assessment, standards basis and policy. Checks identify A001 and A002 as their acceptance restrictions; standalone inspection identifies A002. Detail or payload omission preserves aggregate findings and semantic completion. The CLI exits with 0 for passed requested work, 1 for failed work, 2 for invocation/configuration errors, 3 for undetermined work and 4 for host/output failures.

Additional source-workflow condition codes have these stable meanings:

Input size, decoded allocation, traversal, number and diagnostic budgets are finite operation bounds. Conservative report accounting covers bounded metadata DTOs, retained conditions, serializer capacity growth and output buffers under supported internal JSON layouts. These allowances do not promise a hard process RSS ceiling.

For effective unit spelling and dated registry guidance, request Assessment::ExpandedUnits or CLI --assessment expanded-units-v1. Report::unit_guidance() retains the six fixed observation counts and completion independently of located details. Report::registry_knowledge(id) and UnitGuidance::source_edition() borrow actual-use section and raw-edition facts. An embedding may deliberately withhold recorded evidence while retaining independent spelling errors. See the unit contract, following ADR 0027: Unit names and recorded registry guidance.

For complete content-format declaration spelling, separate decimal identifier range and dated registration guidance, request Assessment::ExpandedContentFormat or CLI --assessment expanded-content-format-v1. The two added area statuses and existing requested coverage aggregates distinguish finished syntax from unknown registration or unavailable evidence. Report::registry_knowledge(id) borrows actual-use CoAP, media-type and HTTP-coding facts; RecordedRegistryPolicy::WithholdRecorded keeps independent spelling errors while honestly withholding needed evidence. Parameters have explicit excluded-meaning Notices; payload validation and protocol binding remain separate. See the content-format contract, following ADR 0029: Content-format declarations and recorded registry guidance.

Assessment::FullBaseline also checks Recorded extension vocabulary. oma:id on an sdfObject or sdfAction definition or a full data description must be a whole number in the CDDL uint domain. So 3303 and 3303.0 are admitted, while "3303", -1 and 3303.5 are extension.recorded_value_excluded errors whose basis kind is registration, citing the OMNA SDF Quality Names registry with oma:id as id. Either way Full assesses M028. Each effective coordinate is checked, including inherited and overriding values, and at these positions oma:id does not stop base meaning. Report::registry_knowledge("omna.sdf-quality-names") borrows the recorded OMNA evidence once a value was checked against it. Withholding recorded evidence lists that record as unavailable, reports no excluded value and leaves M028 undetermined. oma:id elsewhere and other oma: names stay unsupported extension vocabulary. See Recorded extension vocabulary, following ADR 0038: Recorded extension vocabulary.

For effective model pattern syntax, request Assessment::ExpandedPatternSyntax or CLI --assessment expanded-pattern-syntax-v1. Its nine-area inventory adds pattern-syntax/1 to the initial eight, with typed status independent of optional detail. Full binds the same syntax work to M047 and its pattern/format area; broader applicable meaning may remain unfinished. Other profiles, inspection and Sample retain their purposes. Limits::pattern_bytes, pattern_nesting and pattern_alternatives reduce the supported ceilings; original operation work/allocation still cover all patterns together. See the pattern contract, following ADR0014: Bounded partial ECMAScript pattern capability and ADR0028: Bounded effective model pattern syntax.

AuthorRequest::new(catalogue, request_key, generated_key, thing_name) owns an explicit composition recipe. Add namespace bindings and AuthorObject declarations selecting supplied Source IDs and decoded pointers, then call author(). AuthorRequest::from_plan accepts the same bounded JSON recipe used by esdieff author; number lexemes in refinements stay exact. AuthorResult::generated_document() exposes a candidate independently of its generation(), fidelity() and outcome(). Its catalogue() includes immutable supplied sources and a distinct Generated SDF document, ready for the ordinary check, effective and inspect operations. document_deliverable() applies the CLI’s established-fidelity and requested-check policy. Author reports use the additive author operation in report 1.1, with separate authoring and requested-check coverage. This follows ADR 0017: Reference-preserving sdfThing authoring.

An authored refinement’s ordinary EffectiveModel::explanation keeps inherited, overridden and deleted source contributors. AuthorResult::request_origin(generated_source_view) adds the exact logical recipe coordinate and an available original-plan span; typed requests have no plan span. AuthorResult::checking() exposes its optional requested assessment, outcome and coverage without reparsing JSON. The authoring unit, assessment areas, full-baseline requirements and separate inspection unit retain distinct count meanings. See the refinement and explanation examples.

EditRequest::new(catalogue, request_key, source_id, generated_key) selects one existing document. Add explicit present-member replacements or removals with with_edit, then call edit(). The result retains original source evidence separately from its active catalogue(), where the generated document substitutes for that source. Candidate bytes and editing fidelity remain inspectable independently of optional Model checking. The editing contract defines the admitted owners and qualities, exact preservation, request locations and report version 1.2.

ComparisonRequest::new(earlier, later) compares two Model revisions supplied as Catalogues with the same limits, and compare() classifies each difference between their corresponding groupings as breaking, compatible or undetermined from the Client’s side. Documents correspond by source key. The RevisionComparison result borrows both Catalogues and exposes typed differences with their Client directions, effective locations in each revision and nearest content origins. ComparisonRequest::acknowledgements(&acknowledgements) supplies Difference acknowledgements of intended differences, which keep their classifications while only unacknowledged differences decide disposition(). The revision comparison contract defines correspondence, classification, acknowledgements, the shared allowance and report version 1.4, following ADR 0039: Client-side revision comparison and ADR 0040: Acknowledged revision differences.

Catalogue::generate(GenerationRequest::new(document)) builds Generated values for every affordance description of one model document, and select(kind, pointer) narrows the request to one description. Each value aims at one Generation target, such as a minimum or a value just below it, and Sample-value checking settles it, so the GenerationResult gives each description’s values with their targets and admissions. The generation contract defines the targets, their order, the ceilings, the JSON Lines Trace entries and report version 1.5, following ADR 0041: Generated values settled by Sample-value checking.

Catalogue::check_trace(TraceRequest::new(document, trace)) checks a Recorded trace, a JSON Lines file of Trace entries, against one model document. The document is composed once and every entry is checked on its own, so a malformed line fails alone, and the TraceResult counts passing entries and lists failed and undetermined ones with their line numbers, labels and conditions located in the trace file. The trace contract defines the entry format, the outcomes, the bounds and report version 1.5, following ADR 0042: Recorded traces with independent entries.

Repeatable catalogue checks

A Check plan saves supplied files and named model checks, sample checks and revision comparisons. Run the included model-only example from the repository root.

cargo run -- check --plan examples/catalogue-check/plan.json
cargo run -- check --plan examples/catalogue-check/plan.json --format json

The example plan checks the whole catalogue and then the selected Count model with Full baseline assessment. Each case keeps its own requested scope, profile, warning policy and outcome. Initial is the default assessment and still discloses broader partial RFC coverage. A passed case establishes completion of its requested assessment. Failed checking may also be complete. Missing input and unsupported meaning, such as a Boolean sdfRef, remain explicit incomplete work.

The mixed example adds two samples of Count to those same model checks.

cargo run -- check --plan examples/catalogue-check/mixed-plan.json
cargo run -- check --plan examples/catalogue-check/mixed-plan.json --format json

Count admits 25 and rejects 101. The example exits 1 because rejection is an actual failed check. Naming a sample does not turn rejection into an expected success or establish whole-model validity.

Use your own model and samples

The thermostat plan is a runnable template for a device property. Its model describes a readable and writable target temperature from 5 through 30 degrees Celsius. The supplied value 21.5 is admitted and 35 is rejected.

cargo run -- check --plan examples/thermostat-check/plan.json
cargo run -- check --plan examples/thermostat-check/plan.json --format json

Both model checks pass. All four cases are complete, with three passed cases and one failed case. The run exits 1 because 35 exceeds the property’s maximum. The sample checks assess values against the property description. They do not send commands to a thermostat or simulate property reads or writes.

The same directory also supplies minimal, rich and deliberately limited thermostat variants with an offline Rust regression runner. See the device Catalogue for direct plans, named cases and the device-and-constraint coverage matrix.

Copy the examples/thermostat-check directory to start your own checks, then adapt the files together.

1. Replace thermostat.sdf.json with your model and update its source path in plan.json if you rename the file. Relative paths resolve beside the plan, so the directory can move as a unit.
2. Replace the sample files with one complete JSON value each. Use the value described by the selected property, such as 21.5, rather than a device protocol’s message envelope.
3. Set each sample case’s pointer to the property in your model. The template selects /sdfObject/Thermostat/sdfProperty/targetTemperature with kind: "property". Other selections are described under Plan input.
4. Give cases descriptive names. If you rename source keys, update the model case’s roots and each sample case’s document and sample references. Add or remove sample sources with their corresponding cases.

Run the copied plan with cargo run -- check --plan path/to/plan.json from the repository root. Check each case’s outcome and completion separately. A sample you intend to reject still produces a failed case and exit 1.

Compare revisions in the same run

A diff case runs a Revision comparison beside the plan’s checks, so one command and one run report cover a release. The rich door lock plan checks the rich model and compares it with the minimal one.

cargo run -- check --plan examples/door-lock-check/rich-plan.json

{
  "name": "Minimal to rich revision",
  "operation": "diff",
  "earlier": {"document": "minimal.sdf.json"},
  "later": {"document": "rich.sdf.json"},
  "acknowledged": "acknowledged-differences.json"
}

earlier and later each map a source key to a literal file. Documents with the same key correspond, and a key on only one side is a removed or added document. Use each document’s path within its revision’s directory as its key, so that an acknowledgement file written for esdieff diff --old DIR --new DIR works unchanged. Two single files compared directly share the key document, which is why the door lock plan uses it.

The comparison reads its documents only when the case runs, into two Catalogues of its own, exactly as direct esdieff diff does. They never join the plan’s sources, so check and sample cases never see an earlier revision and its definitions cannot make references ambiguous. The optional acknowledged file holds the same Difference acknowledgements that esdieff diff --acknowledged reads. The door lock file acknowledges the added jammed state and the broader credential pattern, so the case passes while its classification stays breaking.

Plan input

Plans use schema esdieff.check-plan and string version 1. Both sources and cases are nonempty arrays. Every source has exactly key, path and role. Keys are unique after JSON decoding. Role is model or sample, and at least one source must be a model. Sample-role files are retained acquisition attempts but contribute no definitions to model checks.

Each model case requires a unique name, operation: "check" and scope. Use {"kind":"catalogue"} for all model sources, or {"kind":"selected","roots":["count"]} for one or more explicit model keys. Other supplied models remain dependency candidates. assessment accepts every profile supported by direct check, defaulting to initial-v1. strict_warnings is a Boolean, defaulting to false. Recorded registry knowledge uses the native profile defaults.

Each sample case requires a unique name, operation: "sample", document, kind, pointer and sample. document names a model key and sample names a sample key. kind is property, data, action_input, action_output or event_output. pointer is the effective-definition JSON Pointer, at most 8192 UTF-8 bytes, with ordinary ~0 and ~1 escapes. Action and Event pointers select the declaration, and kind selects its input or output data description. strict_warnings defaults to false. Sample cases use the existing Sample inventory. There is no model assessment selector or expected-result field. JSON null remains a supplied sample, and no default or sample value is inserted.

Each diff case requires a unique name, operation: "diff", earlier and later, and accepts an optional acknowledged path. Each side is an object of 1 through 256 members whose names are source keys of 1 through 256 UTF-8 bytes and whose values are nonempty paths. Duplicate decoded keys are refused. scope, assessment and strict_warnings do not apply. The comparison uses the native defaults, including the recorded registry evidence. Diff documents are acquisition attempts of their case, separate from plan sources, so naming a plan source’s file there acquires it again. A plan still needs a model source, so a comparison on its own belongs to direct esdieff diff.

Paths are literal local files. Relative source, diff document and acknowledgement paths use the parent of the CLI-supplied plan path made absolute. A symlinked plan uses the symlink’s parent, not the target’s directory. There is no globbing, variable expansion, discovery, remote retrieval, plan inclusion or stdin substitution. Repeated references to one key share one acquisition attempt. Different keys remain different attempts even for the same path or bytes. Reading a plan changes no input file.

Plan mode permits --format human|json and the ordinary color controls. Direct source arguments, roots, assessment and policy options are incompatible. Directory discovery options are also incompatible. Use a separate direct check with directory discovery when source selection should follow the current collection rather than the plan’s saved literal paths. Malformed or unreadable plans, duplicate decoded JSON members, unknown fields or versions, invalid roles, aliases, profiles or pointer syntax, empty or oversized diff sides, and acknowledgement files that cannot be read or decoded are configuration errors with exit 2 on stderr and no run report.

A content-dependent selection mistake, such as a definitely absent description or an established wrong class, becomes a named case request error. Later cases continue. Acquisition/decode failures and unavailable needed meaning remain native domain results, with the ordinary dependency rules and finite allowances. A diff document that cannot be read is such a result too. Its source row records the failed acquisition, and the comparison leaves the content it would have held undetermined.

Run output

JSON is plain under every color setting. Its separate schema is esdieff.check-run, version 1.1, with plan, sources, cases and summary. Version 1.1 adds diff cases to 1.0, and every run report is emitted at 1.1. plan records its acquisition path and accepted schema/version. Source rows use the existing report contract meanings and list the plan sources only. Cases retain plan order, with name, operation, request, state: "report", native outcome, baseline and policy. Sample cases also retain native admission as admitted, rejected or undetermined. Diff cases also retain a mandatory classification, the native result.outcome of breaking, compatible or undetermined, which acknowledgements leave unchanged while the disposition in outcome follows them. That outcome also counts the comparison’s Version warnings, which never change the case’s disposition, and the native diff report keeps its own version 1.5. request is the native requested scope, selector and assessment/inventory record, or for a diff case the comparison identity and both revisions’ scopes. A whole native report is optional. A diff case’s report is the native diff report with both revisions’ sources. When it cannot fit, report_omission.reason is run-report-budget. Native diagnostic truncation inside a retained report is a separate presentation limitation. Neither form of omission changes the case’s outcome or completion.

A case with state: "request_error" has exactly name, operation, request, state and request_error. Its request records the supplied native selector and sample IDs and strict_warnings. request_error has stable operational code: "sample.request", an explanatory message and location: {"kind":"plan","pointer":"/cases/N"} using the zero-based case index. It has no native outcome, baseline, policy, admission, coverage or report. Every source attempt remains visible even if every case is a request error.

summary counts total, passed, failed, undetermined, request_errors, complete_cases, incomplete_cases and omitted_reports. Sample admission counts admitted, rejected and admission_undetermined are independent of disposition, and are zero in model-only runs. Counts describe cases, not combined RFC obligations. A diff case counts by its native disposition after acknowledgements, so an acknowledged breaking comparison is a passed case. Request errors count as incomplete. Complete and incomplete counts sum to total cases, and failed cases can be complete. The aggregate complete flag requires every case to have a complete native result. verdict follows invalid before failed before undetermined before passed, with exits 2, 1, 3 and 0. Invalid describes request configuration, not SDF validity. Host reporting or output failure exits 4 and makes no success claim for partial or unavailable output. Human output lists the same named results and coverage, with accessible findings and locations when detail fits. A diff case adds a Classification: line and the native human diff report.

Finite allowances

Plans are at most 1 MiB, with the ordinary native JSON depth, node, decoding and allocation ceilings. There are at most 64 cases and 256 declared sources across both roles. Keys and names contain 1 through 256 UTF-8 bytes. Resolved source paths, plan identity, names and repeated references undergo a separate 1 MiB control-metadata admission before copying. Diff keys, diff document paths and acknowledgement paths count there as source keys and paths do. Ordinary Catalogue input and metadata admission also applies.

The entire mandatory envelope is reserved before acquiring sources or running cases. Its conservative reserve uses six bytes per control-metadata byte for escaping, 4096 bytes per source and per diff document, 16 KiB per case for native request, outcome, baseline/knowledge, policy and classification, and 16 KiB for the fixed run envelope and summary. An envelope that cannot fit fails configuration admission. Optional detail uses only the unreserved remainder of the 8 MiB complete-output ceiling.

Each acknowledgement file is read and fully decoded during admission, after the envelope fits and before any source is acquired. A file is at most 1 MiB, and a plan’s files together are at most 4 MiB. A diff case runs on its own native operation allowance, so its comparison spends nothing of the plan Catalogue’s work. Each diff document’s control metadata covers what its revision’s Catalogue admits for it, so an admitted comparison always fits its native report envelope.

The plan’s native decoder retains its bounded original input and parsed view. Control storage adds at most the admitted metadata, bounded case/source/document slots and the acknowledgements decoded from at most 4 MiB of files. The aggregate reserves one 8 MiB output buffer. Only one native case is active at a time, with its ordinary processing and presentation allowances. A diff case’s two Catalogues are released when the case ends. One native serialization is transient, with at most 8 MiB of content and a separate 16 MiB capacity allowance for String growth. Human rendering starts after that JSON serialization is released. The source envelope is appended directly without another whole-source formatting buffer. Borrowed raw fields and whole native JSON avoid a second full aggregation JSON graph or floating-point conversion. No native work allowance is replenished within a case.

Selectors and sample aliases are included in control-metadata admission before copying. The fixed case reserve also covers request-error messages up to 1024 bytes, tagged records and locations. One case record’s DTO and encoding use a separate 128 KiB staging allowance, covering the fixed fields and worst-case escaping of the ordinary 8192-byte selector. Source-view inspection supplies the native source metadata before cases start. It uses the same transient serialization allowance and releases its report before any case executes.

Check a local model collection

Direct check can select model files from explicitly supplied directories. Run the mixed collection from the repository root.

cargo run -- check --directory examples/directory-check --format json
cargo run -- check --directory examples/directory-check --recursive --exclude draft --format json
cargo run -- check --directory examples/directory-check --recursive --exclude draft --root examples/directory-check/device.sdf.json --format json

The shallow command selects device.sdf.json and types.sdf.json. Recursion with the exclusion adds nested/status.sdf.json. The selected-root command checks the device and its needed shared type, while the nested document remains a supplied candidate. Each command emits one ordinary model report. Sample JSON, Check plans, unrelated JSON and the suffix lookalike are not selected. Recursing without the exclusion includes the deliberately invalid draft and exits 1.

Repeat --directory DIR to select several collections. Positional files and one - stdin document can accompany discovery. Explicit files need no naming suffix. Their order is preserved, followed by each directory’s selection in option order. Within each directory, accepted relative paths are sorted by exact native encoded path bytes. Ordering is repeatable for unchanged arguments and tree on the same platform. It gives no reference-resolution precedence.

Selection matches regular files whose final filename ends exactly in the case-sensitive suffix .sdf.json. Without --recursive, only immediate entries are inspected. Matching hidden files and recursive hidden directories follow the same rules. There are no implicit exclusions or content sniffing.

Repeat --exclude RELATIVE_PATH to exclude a literal file or an entire subtree. The same exclusions apply independently relative to each supplied directory, and a subtree is pruned before type inspection or descent. An exclusion must be a nonempty relative component path without a root, . or .. component. Matching is case-sensitive on native components. There is no globbing, variable expansion, regular-expression or ignore-file interpretation. A nonexistent exclusion is harmless. Explicit file inputs are unaffected.

Directories, explicit files and --root paths resolve from the invocation directory. A discovered Root document must be named by its joined acquisition path, such as models/device.sdf.json for --directory models. Roots are never chosen automatically. Missing or multiply matched roots are invocation errors. Catalogue scope checks every supplied document, including unused definitions. Selected-model scope checks explicit roots and the dependencies needed for their checks, following ADR 0004, Supplied catalogues and checking scope.

An explicitly supplied directory may resolve through a link. Its displayed acquisition paths retain that spelling. Descendant file and directory links, including platform link equivalents, and known special files are skipped. Native paths select and open files even when a display label is omitted or uses Unicode replacement.

Each supplied directory must select at least one matching file after exclusions. Discovery refuses native-file overlap with another discovered or explicit file, including aliases and hard links. Exclude the automatic duplicate or remove the overlapping input to select one attempt explicitly. Explicitly repeated file inputs remain distinct attempts. Physically different files with equal bytes remain distinct sources and can retain ordinary namespace ambiguity.

Preparation has fixed ceilings, following ADR 0009, Bounded processing and reporting.

An included subtree beyond a ceiling fails preparation. Excluded subtrees are not enumerated. The ordinary Catalogue acquisition, parse, semantic-work and report budgets still apply separately. There are no discovery tuning flags or unlimited mode.

All option validation, enumeration, overlap checks, root selection and assembled metadata preflight finish before model content or stdin is read. Missing, wrong-kind, unreadable or empty directories, inspection failures, overlaps, invalid roots and exhausted allowances exit 2 with bounded stderr and empty stdout, including under --format json. They produce no partial Catalogue report and assert no RFC violation.

After successful preparation, a selected file that cannot be read or decoded remains an ordinary source result in the report. Failed and incomplete checks, warning policy, coverage, diagnostic omissions, color and output-failure exit 4 retain their existing report contract. Directory discovery is a bounded filesystem observation rather than an atomic snapshot. It changes no original bytes and promises no cross-file content consistency.

--recursive and --exclude require a directory input. Discovery options apply only to direct check and diff. Saved Check plan version 1, inspect, sample, author and edit do not accept them. Discovery adds no Rust filesystem API, report schema, assessment inventory or standards interpretation.

Compare two collections

esdieff diff --old DIR --new DIR prepares each Model revision’s directory with these rules. --recursive and --exclude apply to both sides alike. Each side is prepared separately, with its own ceilings and overlap check, so a directory can be compared with itself. Both sides finish preparation before either one’s content is read.

A document’s source key is its path relative to its directory, with components joined by /, such as nested/status.sdf.json. Documents with the same key correspond, so a moved or renamed document reads as a removal and an addition. A relative path that is not UTF-8 or exceeds the 256-byte source key cannot pair documents and is an invocation error. The revision comparison contract describes the comparison and its report.

Pinned document acquisition

Use esdieff acquire to save one deliberately selected public GitHub file as unchanged local bytes. Select its complete commit and establish the expected raw-file SHA-256 from separately reviewed source evidence before acquisition. The resulting Acquired snapshot is an ordinary input for offline checking, inspection, editing and literal Check plans. This follows ADR 0035: Explicit pinned document acquisition.

esdieff acquire --github OWNER/REPOSITORY --commit COMPLETE_40_HEX_COMMIT \
  --path repository/relative/file.sdf.json --sha256 EXPECTED_64_HEX_SHA256 \
  --document-output snapshot.sdf.json --format json

Every required option occurs exactly once. --format human|json is optional and defaults to human. --report-output RECEIPT_FILE selects a separate native file, and omission sends the receipt to stdout. Repeated, missing, unknown and unsupported options and positional model inputs are invocation errors. The document always needs a named native file. Acquisition offers no replacement flag or request plan.

Add --report-output acquisition.json to the command above to retain its JSON receipt in a new file. Use a different name for a human receipt. Both formats retain the same acquisition outcome and 64 KiB ceiling.

The repository has an owner and repository name. The commit is a complete 40-hex identity and the expected SHA-256 is 64 hex digits. The repository path excludes empty or dot segments, backslashes, absolute paths, controls, queries and fragments. Accepted UTF-8 path segments are encoded into the fixed https://raw.githubusercontent.com origin. SDF namespace URIs never select retrieval locations.

Request validation and native destination preflight finish before retrieval. Source metadata obeys applicable existing finite Source field ceilings, and the whole request is at most 64 KiB. Preflight also reserves worst-case escaping space for every mandatory receipt identity within the complete 64 KiB receipt envelope. Identity that cannot fit is rejected rather than clipped. Named outputs must be new, distinct native filesystem destinations. Existing files, aliases and collisions are refused. Display labels never reopen paths. Native non-UTF-8 destinations retain their actual same-platform identities.

Transport and content

The operation verifies HTTPS and sends no credentials, cookies or authorization headers. It does not follow redirects or retry. It requests identity content encoding, refuses other encodings and accepts only a complete HTTP 200 body. Authentication, other origins and proxy configuration are outside this operation.

The body ceiling is 4 MiB and the total header ceiling is 64 KiB. The connection deadline is 10 seconds and the whole-transfer deadline is 30 seconds. Streaming work and transport buffers are bounded, including responses without a trustworthy length. Oversize, incomplete and deadline-exhausted responses fail acquisition.

SHA-256 covers the exact complete response bytes. The document is committed only after comparison with the independent expected digest. Acquisition never parses, repairs or regenerates JSON. Empty bytes and malformed JSON are valid acquisition results when explicitly selected by a matching digest. Their later ordinary decode and Model checking outcomes remain separate.

Bytes are staged privately beside the document with bounded writes. Commit cannot replace an existing or concurrently created destination. Task-created staging removal is attempted after failure and after commit. Cleanup failure identifies retained staging, preserves any earlier failure and discloses whether a verified document was committed. Host failure does not promise removal.

Staging identity is checked before cleanup. That check and unlink are separate filesystem operations, so a further change to the staging name can race cleanup. Cleanup is not a transaction over the mutable directory.

Acquisition pins each native destination’s parent directory during preflight. Staging, document commit and named receipt creation use that directory’s retained identity, so an ancestor alias introduced later cannot redirect a write. Destination rechecks refuse changes observed before delivery. Named receipts use exclusive creation and bounded writes. Failed receipt delivery can leave a partial file, which is disclosed through stderr and exit 4 rather than treated as complete evidence.

Acquisition receipts

Human and JSON receipts express the same authoritative outcome. A JSON receipt is an object with schema equal to esdieff.acquisition and version equal to 1.0.

Native bytes are integers from 0 through 255 and represent a same-platform path identity, not a portable path serialization. A successful receipt has status acquired, complete and document_committed true and no failures. A complete digest-mismatching body retains its actual digest and count. An incomplete body records null for both.

Stable failure phases are transport, http, limits, digest, stage, commit, cleanup and receipt. Their order preserves causes, such as document commit failure followed by cleanup failure. Human message wording is explanatory rather than a stable identifier. Mandatory outcomes and identities take priority over optional explanatory detail within the 64 KiB envelope.

Human receipts follow the shared --color auto|always|never and --no-color controls, accepted before or after acquire. In auto, a receipt on terminal stdout can be styled, while redirected stdout and a --report-output file stay plain. always can style a human receipt file, and never removes all styling. Removing the style sequences gives exactly the plain receipt. If styling would push a receipt past the 64 KiB envelope, the plain receipt is delivered instead, so no detail is lost. JSON receipts and downloaded document bytes are identical in every mode.

Every valid, destination-preflighted request attempts one receipt after acquisition success or failure. Invocation and preflight errors write explanatory stderr without a receipt or retrieval request. A failed receipt delivery can leave partial evidence. Stderr identifies the receipt failure and whether a verified document exists. The document and receipt have no cross-output transaction.

Receipt delivery failure uses stderr and exit 4 as the authoritative outcome. Written bytes alone do not establish complete delivery, including when a later identity check finds that the requested path changed. A verified document commit remains recorded even if its requested path subsequently becomes unavailable or resolves elsewhere.

Any applicable host-output or cleanup failure takes exit 4. A document already committed before receipt failure remains available. A partial receipt is not complete acquisition evidence.

Offline use and refresh

Ordinary CLI checks record their actual local file acquisition path. Library callers can explicitly provide the receipt’s URI, commit and digest through existing SourceInput::acquisition_uri, version_token and digest metadata. No operation automatically loads a receipt.

Checking selects no implied Root document, retrieves no unsupplied reference and gives repeated or overlapping contributors no deduplication or input-order precedence. These are the existing Catalogue and scoped-reference rules. A refresh deliberately selects newly reviewed revision and digest values and a different destination, leaving prior bytes available for identical replay.

The pinned OneDM example records independent source identity, retained notices and reproducible offline use. Historical interface examples with an unknown exact pre-RFC dialect are not current RFC-conformance or real-device acceptance oracles.

Model meaning assessment

FullBaseline establishes the interpretation of effective data descriptions under the immutable rfc9880.model/1 inventory. This work uses the same composition, roles and finite operation allowance as model checking. It neither requests a sample nor searches for a value satisfying the description. The distinction between assessed meaning, findings and unfinished work follows ADR 0003: Check findings and completeness.

Ordinary scalar descriptions

The scalar observations are made in the owning effective description, including the final inherited qualities of each effective alternative:

Absence of type imposes no authored type or origin. It does not prevent an otherwise established numeric parameter or ordinary scalar constant from having meaning. Independent formal numeric and literal admission belongs to M035-M037, following ADR 0032: Formal model admission and the formal admission contract. For example, exact mathematical meaning for a count of 18446744073709551616 remains established when Full separately finds its exclusion from the imported CDDL uint domain. Extension-only final constants retain unavailable extension and const meaning, even when their framework literal admission is assessed. Ordinary type or const contradictions and inverted bounds can have established meaning and existing advisory findings; meaning assessment does not prove general satisfiability.

Reference composition and final alternatives determine the context. Established nonempty Choice and Enum collections supply the final descriptions whose meaning is assessed. Their shared owner and its original quality descendants do not impose additional semantic constraints. An explicit branch quality replaces the shared quality as a whole, including properties maps; surviving inherited qualities remain needed in every final branch. A pattern or const replaced in every branch therefore requests no additional matching or denotation capability. Source grammar and existing registry guidance remain independently checked, and an owner’s documentary default remains stated. Unknown, malformed and empty collections retain their existing handling. Restricted Direct items retain their admitted scalar vocabulary; wider retained qualities and their inherited donor meaning do not become Full meaning solely because a final alternative is Full. Explicit supported overrides are assessed in that final context, following ADR 0024: Effective alternatives and nullable characteristics.

Declared Extension features, unknown values of base qualities, unavailable interpretations, origins, member identities, scalar values or numeric magnitudes leave the affected observations undetermined. Independently established descriptions retain their own observations. Required semantic work is charged before scanning the description; exhausting it leaves requested work unfinished. Diagnostic or report omission does not change established meaning.

Undeclared extension vocabulary leaves the base meaning of its description intact, following ADR 0037: Undeclared extension vocabulary. That is a qualified or unqualified Quality Name outside base SDF, such as acme:note, sdfProtocolMap or a misspelled minimun, in a document that declares no Extension feature. Full scalar and compound meaning and contextual equality are established as if the quality were absent, and so are the declared-value consistency and numeric advice of the expanded assessments. Its own meaning stays unsupported, so M028 remains undetermined wherever it occurs, and its existing notice or unfamiliar-name warning is retained. A base quality outside its role, such as a wider Direct item quality, is not extension vocabulary and keeps its unfinished outcome. So do unknown values of base qualities, documents that declare an Extension feature and definitions composed from them. Reports name the reading as described in the report contract.

Initial and explicitly expanded assessments retain their existing scopes. FullBaseline requirement statuses remain available through typed report accessors even when optional detail is omitted. Human and JSON output preserve the same completion, disposition and inventory meanings described by the report contract.

Compound descriptions

An established Full array or map selector supplies its ordinary structural meaning for M042. M050 follows every authored final item description; M053 follows every authored final property description, including optional properties. Empty or passing sample values provide no credit for these model obligations. Nested Full properties and final alternatives can describe arrays; wider Direct items retain their own vocabulary and unavailable inherited meanings.

M051 establishes inclusive exact mathematical item counts, separately from formal CDDL admission in M037. M054 establishes decoded mandatory entry names under an explicit map description. Required entries need no property description, described entries remain optional unless required, and other entries remain unconstrained. Malformed parameters retain their existing findings; understood invalidity can still be assessed work.

M052 establishes adopted contextual equality capability for ordinary items and the supported canonical byte-string, opaque UUID, Gregorian-date and dated date-time conventional domains, recursively through maps, arrays and every final Choice interpretation. False uniqueness requests no comparison capability. It does not select whichever alternative admits a value or supplies a preferred equality result. Declared Extension features, unknown base values, base qualities outside their role and unsupported abstract interpretations remain unfinished, while undeclared extension vocabulary does not affect comparator capability. Every candidate at the same projected item or property must have compatible equality meaning. A missing description supplies ordinary unconstrained meaning, so it cannot silently select another alternative’s abstract interpretation. Distinct properties can retain distinct compatible meanings. Known time or URI names do not establish complete comparison capability for every representation; generic Unix-time equality retains the negative-coordinate gap. This is model capability assessment, not a theorem that every possible pair can be decided within any configured allowance.

UUID, Gregorian-date and dated date-time comparator capability require an established Full interpretation with known effective nullability in every relevant alternative. Known absence uses the Full default of true; explicit true and false are also supported. Null equals null and differs from an established nonnull value in that compatible format. Two nonnull dates must each establish valid Gregorian denotation before comparison; the same calendar date is equal and different calendar dates differ. Dated date-times compare their established UTC instants with exact fractions and distinct inserted-second slots under ADR 0018. Model capability does not assert that every possible dated operand has available adjustment knowledge. Unavailable or restricted Direct nullability stays undetermined. Model-only capability assessment does not parse a sample or record consultation of representation facts.

Actual formatted null constants can establish M043 in compatible civil, URI, URI-reference and UUID contexts. Null/null needs no nonnull representation scan; a mixed pair needs the nonnull operand’s established denotation. Invalid or uninterpreted operands retain unfinished equality. These null cases do not fill the nonnull time or URI comparator gaps in M052. Equality remains separate from admission, including when nullability excludes the constant.

For compound M043, contextual equality examines the actual effective const and its needed subtree against itself. This establishes that stated value’s denotation and equality capability without inventing a sample, checking its admission or proving satisfiability. Invalid abstract representations remain undetermined. The shared const is superseded by final alternative constants. The rules follow ADR 0015: Bounded value equality in a resolved data context and ADR 0016: Selected samples with explicit admission and coverage.

Every description, alternative and actual const uses the original request’s semantic work, allocation, numeric and equality allowances. Fixed owner costs are reserved before the Full interpretation phase; traversal capacities and growth are charged before allocation. No child or alternative refills an allowance. Limits keep the affected work unfinished, while optional report omission preserves established observations.

Patterns and known abstract interpretations

M048 establishes available modeled Unicode, unanchored matching by compiling the surviving effective pattern with the adopted matching implementation. It supplies no subject and invokes no match. M047 owns syntax independently; a matching-only capacity can leave M048 unfinished with syntax assessed. A pattern admitting no text, such as (?!), still has known matching meaning. Original worker, allocation, engine, interrupt and duration allowances remain shared. Compilation does not guarantee runtime capacity for arbitrary future subjects, following ADR 0014: Bounded partial ECMAScript pattern capability.

M026 and M027 establish the known byte-string and Unix-time model interpretations, and M049 establishes the six known base format interpretations. These observations require no constant, sample, denotation or temporal fact. Absent type does not prevent recognition of the named model meaning. A conflicting explicit type or combined abstract selectors can leave affected interpretations unavailable without erasing independently established type or numeric meaning. Actual special constants use their borrowed contextual denotation and self-comparison for M043. An unsupported URI scheme, unavailable temporal slot or negative POSIX denotation can therefore leave M043 unfinished while the named model interpretation is assessed.

Known declarations no longer block unrelated base constraints. Byte text qualities retain their specific limit: an authored length or pattern does not establish an encoded-text or decoded-byte interpretation, so affected M046 or M048 stays undetermined. Content-format declaration meaning belongs to M024; unknown payload equality stays scoped to M043 and M052. Neither declaration recognition nor comparator-capability assessment records actual operand or external-knowledge consultation. These limits follow ADR 0007: Generated SDF and sample JSON, ADR 0018: Civil date and time sample conventions and ADR 0019: URI, URI-reference and UUID sample conventions.

Recorded extension vocabulary

FullBaseline checks oma:id, the first Recorded extension vocabulary, under ADR 0038: Recorded extension vocabulary. Its registered CDDL sockets place it on sdfObject and sdfAction definitions and on every full data description: sdfData, sdfProperty, Action input and output data, Event output data, object property entries and choice alternatives. At those positions it does not stop the base meaning of its definition, and Full checks its value against the CDDL uint domain of ADR 0032: Formal model admission. A whole number from 0 through 2^64−1, such as 3303 or 3303.0, is admitted. A string, a negative or fractional number, a number above that range or any other JSON value is an extension.recorded_value_excluded error. Its basis has kind registration, the citation OMNA SDF Quality Names registry and the id oma:id, and it is owned by M028 in full.critical-extensions/1. Either way M028 is assessed. On an sdfEvent or sdfThing definition or a Direct item, oma:id stays undeclared extension vocabulary, and so does every other oma: name. The check covers value admission only, not whether an ID names a real LwM2M Object or Resource.

Like unit checking under ADR 0027: Unit names and recorded registry guidance, the check visits each final effective coordinate, including inherited values at every consuming definition, the importer’s overriding value and final alternatives. An excluded inherited value is reported once for each definition that copies it, and an importer’s whole-number override clears it. A null deletion removes the value from the effective definition. An unavailable value, an unfinished composition or exhausted work leaves M028 undetermined. The full-baseline optional-vocabulary notice leaves out oma:id at its registered positions. Initial and expanded assessments neither check it nor list its record, and their notice still counts it.

Where a FullBaseline check consulted the recorded evidence, a conclusion that set oma:id aside relies on no further reading. Where a report did not consult that evidence, such a conclusion relies on undeclared-extensions-ignorable/1 from ADR 0037: Undeclared extension vocabulary, and the report names it as the report contract describes. That covers the numeric advice and declared-value consistency of the expanded assessments and a FullBaseline check that withholds recorded evidence.

The check consults Recorded registry evidence omna.sdf-quality-names and lists it in baseline.registry_knowledge once a value was compared with the recorded domain. A caller that withholds recorded evidence gets that record as unavailable with reason caller_withheld, no value is reported as excluded and M028 stays undetermined. The evidence combines two sources, both retrieved on 16 October 2026. The IANA SDF registry XML was retrieved at 2026-10-16T08:38:44Z. Its SDF Quality Name Prefixes registry holds one record, oma, dated 2026-05-12 and referring to the OMNA registry. The XML’s SHA256 is 0fdb79625d83a034b53ef15a007bb07a0e695bb58a60996866641acb5c06333e, and its raw bytes are a test fixture. The OMNA SDF Quality Names registry page was retrieved at 2026-10-16T08:38:45Z, with server modification date 2026-10-15 and raw SHA256 98098ac43cd36acca64e73e95b78bc3caca10f9c9d174f431c935d413423a62f. The site’s terms leave the raw page out of the repository. Its introduction, registry table and CDDL are kept as extracted text of 810 bytes with SHA256 42c8be5e61ce56b45529160ec4e51d9cdaa4780cd5099948209f8c61c5b80b2f. Extraction policy esdieff.recorded-extension-vocabulary/1 writes one row per registered Quality Name, name<TAB>sockets<TAB>type<LF> with sockets in CDDL order and no header. The single oma:id row occupies 79 bytes with SHA256 58b2e81f1a27e35f2156f79c3361dc4fcd57d353831d3e62d466dec021392656, which is the record’s digest. Its snapshot is omna.sdf-quality-names/2026-10-16/58b2e81f1a27e35f, its scope oma-quality-names and its entries_count 1. The raw_digest and source_updated describe the OMNA page. A test compares the recorded positions, value domain and canonical bytes against both captured sources. Production reads neither.

The sixth record grows the full-baseline registry reserve. One more record map and its text add 4608 bytes to the Full extension bound, so D is 62792 and 2D+208=125792=4E with E=31448. Six synthetic all-cap records occupy 3175 bytes, and the projected fixed wire of 7271 bytes fits the new 7680-byte ceiling. The six actual records occupy 2647 bytes, the OMNA record 453 of them. Two generations, growth and owners of the actual maximum graph use 73732 of 125792 available bytes.

Formal model admission

FullBaseline checks M035-M037 of rfc9880.model/1 against the imported domains in RFC 9880 Appendix A, following ADR 0032: Formal model admission. Formal admission is grammar membership, separate from model meaning, actual const denotation, sample admission and general satisfiability. Initial and expanded assessments, source inspection, unchanged generated-token preservation and selected-sample workflows keep their existing exact-decimal contracts.

Number and count domains

number admits every JSON number, as an exact decimal without a precision or range limit. uint is the integer interval 0 through 2^64-1. Integrality is a mathematical property: 10, 10.0, 1e1 and 100e-1 have the same membership. Negative zero is zero. No decimal is rounded into a machine value for either check.

These results apply to successfully decoded exact numbers with sufficient work allowance. An operand beyond the 512-digit decoding capability leaves membership undetermined. It does not establish exclusion. Exact mathematical processing and retained source tokens remain governed by ADR 0012: Exact numbers and JSON input policies.

M036 checks the numeric parameters admitted in Full descriptions and Direct minimum and maximum entries. M037 checks Full lengths and array counts, Direct lengths and grouping repetition counts. A JSON number always satisfies M036. A known nonnegative integral count above 2^64-1 in a colon parameter produces a definite formal grammar error. Its owning requirement is assessed, and independent exact bound, type or count meaning remains assessed. Completed work can therefore have a failed disposition.

Object and Thing repetition entries use =>, allowing fallback to framework extension content. Full treats a known negative, fractional, nonnumeric or too large repetition value as admitted grammar: M037 is assessed, while M032 base repetition meaning and M028 extension meaning are undetermined. These cases produce no Full grouping-count grammar error. Initial and expanded grouping checks retain their narrower behavior.

Declared literals

Full const and default use allowed-types, including an any feature alternative. M035 is assessed when either base or framework-extension membership is established. The base alternatives are JSON numbers, decoded text, Boolean, null, homogeneous arrays of numbers, text or Boolean, and text-key maps with unrestricted values. An empty array is base-admitted.

An extension-only default remains documentary and is not inserted. An extension-only const overridden by every final alternative does not constrain those alternatives. An extension-only const in an optional property still prevents claiming that property’s complete model meaning. Framework admission does not establish a registered extension interpretation or successful contextual equality. Unknown decoding, feature or effective context leaves needed membership undetermined.

Scope, limits and evidence

Formal checks examine effective definitions in their actual roles. Source patch nulls that delete an inherited parameter impose no final constraint. Selected root requests exclude unrelated supplied definitions; catalogue requests retain their wider scope. A finding on an inherited operand names the effective consumer and relates its original source span, preserving the authored number token.

All operands and phases share the original semantic, numeric and allocation allowances. Count comparisons avoid expanding authored exponents. No operand, child or replay replenishes a counter. Capability or work failure leaves only affected work unfinished. Human and JSON output share the same mandatory error and completion totals; omitted diagnostic detail does not erase established findings or make assessed membership unfinished.

Model coverage boundaries

Esdieff requests the whole recorded base-model scope through --assessment full-baseline. The model assessment inventory contains 54 obligations, grouped into 13 assessment areas. The clause-family trace also records sample, processor, converter, registry and operator duties that do not belong in that model count. This separation follows RFC 9880, including its normative Appendices A and C.

A complete report establishes the requested work for the supplied model. It does not establish that every SDF model is supported. For example, the combined ordinary model in tests/fixtures/model-meaning/ordinary.sdf.json exercises available scalar, compound, pattern, format, special-type and content-format meanings. An empty document, a Boolean sdfRef or an unavailable comparison interpretation has different applicable obligations.

The default Initial assessment retains its narrower scope. Choosing Full requests more conclusions; it does not supply missing interpretations or knowledge. Completion, findings and validity remain separate under ADR 0003: Check findings and completeness.

Available comparisons

The shared contextual equality contract supports exact ordinary numbers, decoded text, Boolean and null values, and supported maps, arrays and alternatives. Its specialized domains include canonical byte strings, opaque UUIDs, Gregorian dates, dated UTC instants and established nonnegative POSIX coordinates. Nullable UUID, Gregorian-date and dated date-time comparator capability includes known absent, true and false Full nullability. Dated instant comparison follows the existing civil denotation and recorded adjustment knowledge boundaries.

Null compares with null and with an established nonnull value in compatible date, date-time, time, uri, uri-reference and uuid contexts. A malformed or uninterpreted operand does not establish a difference. Identical established nonnull time and URI representations can establish equality, while their general nonnull comparison capability remains unavailable. Established date-times compare by UTC instant with exact fractional seconds and distinct inserted-second slots, after every relevant interpretation is compatible. These rules follow ADR 0015: Bounded value equality in a resolved data context, ADR 0018: Civil date and time sample conventions and ADR 0019: URI and UUID sample conventions.

Retained gaps

Each entry retains its affected obligations, actual unfinished outcome, reason and condition for reconsideration. These are capability boundaries, not another runtime status or a change to the immutable inventory. Where the reason is an RFC ambiguity, the retained outcome is deliberate Esdieff policy. Esdieff does not wait for author clarification. It adopts its own RFC interpretation, recorded in an ADR, when a real model or caller needs one, and treats any later author guidance as evidence. An affected model can also have independent assessed findings. The exact status depends on the final effective context and all applicable occurrences, as described in the model meaning contract.

Missing or ambiguous supplied dependencies, effective expansion cycles and exhausted operation budgets can also prevent conclusions. They are assessed through the existing scoped failure and finite-work contracts, rather than promising automatic acquisition, recursion or unlimited processing. See ADR 0004: Supplied catalogues and checking scope and ADR 0009: Bounded processing and reporting.

For unsupported vocabulary, Full conditions name each retained quality and its source location. Composed observations also identify the effective position. These details help locate the cause of unfinished work, including draft vocabulary and base qualities used outside their supported role. They do not provide the missing meaning. The report contract describes their bounded retention and omission reporting.

Scope beyond model checking

Whole interaction scenarios, protocol bindings, ecosystem conversions, device behavior, existing-document editing and separately specified extensions are additional workflows. General satisfiability and unrestricted refinement proofs are additional analyses. They do not silently increase this model inventory or become prerequisites for completing an ordinary supported model assessment.

Selected sample checking establishes outcomes for the actual supplied values. A passing sample does not discharge model obligations, and an available model interpretation does not guarantee every future sample’s denotation or processing capacity. The sample contract records that separate scope.

RFC 9880 model assessment inventory

The immutable fine-grained inventory rfc9880.model/1 contains 54 finite model obligations. It covers RFC 9880, including normative Appendices A and C. Appendix B is informative; Appendix D contains examples and Appendix E historical changes. Imported definitions apply only where a clause uses them. Each obligation counts once across the requested model scope, regardless of how many occurrences or supporting citations it has.

The Full request retains assessment and baseline identity rfc9880/base-1. Its area inventory esdieff.full-model/1 has 13 members. Initial retains its eight narrower areas and existing exclusions. Successful Initial assessment always discloses broader partial coverage. These identities follow ADR 0011: Machine-readable report contracts and ADR 0013: Shared workflow and report guarantees.

Completion and applicability

An obligation is assessed only when all applicable occurrences and subdimensions have been assessed, including definite invalidity. Established absence is not applicable. Missing implementation is unassessed; unknown needed meaning, context, knowledge or traversal is undetermined. Joining repeated observations uses undetermined before unassessed, then assessed, then not applicable. One finished occurrence cannot hide an unfinished sibling. Errors, warnings and notices remain independent of completion and of optional detail retention.

Full broader completion describes these54 model obligations. Requested outcome completion describes all13 selected areas, including the separate advisory area. All model work may therefore finish while advice remains incomplete. Assessed errors still constitute completed work; neither completion value certifies validity or universal capability. Full does not emit an optional omitted-areas list whose absence could be mistaken for completion.

Full establishes capability and meaning for the supplied model. Sample admission is a separate operation; a successful sample never completes a model obligation. Device behavior, protocol bindings, conversion, registry administration, operator duties and general satisfiability are outside this model denominator. Unknown extensions are retained without guessing their meaning or universally rejecting them.

Each subclause has one counting owner. The clause ownership table names supporting dependencies separately. The clause-family trace preserves all132 body/grammar/characteristic/process families and the explicit comment obligation with their model owners or excluded roles. These are traceability rows, not another denominator. For example, nullable belongs to M029, special-type selector admission to M025 and Property flags to M031; they do not also earn M022 credit. M022 owns only unit and content-format string shape. Direct-item container shape belongs to M040; Full properties and Choice descendants retain M038 and M030. Grammar family G013 therefore supports M039 for pattern/format/uniqueness shape and M040 for the restricted items container.

Obligations

IDs below expand to rfc9880.model.M001/1 through rfc9880.model.M054/1. The capability column describes current checking and limitations. Runtime status comes from the report, not this table.

The model coverage boundaries collect retained gaps with their current outcomes, reasons and conditions for reconsideration.

Formal CDDL number membership is separate from mathematical decimal decoding. Appendix A imports the RFC 8610 domains: uint 0 through 2^64−1, nint −2^64 through −1, their int union, and binary16/32/64 floating-point values. Full admits every JSON number as number, following RFC 8610 Appendix E’s description of JSON numbers as decimal and RFC 9880’s own Figure 5, which uses 5e-2. Full checks uint as integral values from 0 through 2^64−1, without rounding. Numeric literals, bound parameters and count parameters have distinct owners M035, M036 and M037. Exact lexemes such as 0.1, 10.0, 18446744073709551616 and 1e400 remain inspectable. Colon entries reject established out-of-domain counts. Grouping counts use no-cut fallback and known literal extension alternatives remain framework-admitted, with their unavailable semantics scoped separately. Initial, expanded and selected-sample contracts remain unchanged. See ADR 0032: Formal model admission and the formal admission contract.

Full area membership

The fixed areas are document syntax, model roles, metadata, namespace/reference, composition/requiredness, critical extensions, data grammar, formal numbers, scalar meaning, pattern/format, compound meaning, special type/unit, and the four advisory classes. Their exact IDs are the distinct area entries in the table above plus advisory-four/1. The advisory area counts once in the 13 areas and contributes no extra RFC obligation to the 54 denominator.

Both unit subareas join once into M023. Both content-format subareas join once into M024. Modified metadata joins into M012 and pattern syntax into M047. Each resulting obligation joins once into its Full area. Producing condition IDs remain modified-date-time/1, unit-spelling/1, unit-registry-guidance/1, content-format-syntax/1, content-format-registry/1, pattern-syntax/1, inspection for required relationships, or advisory-four/1. Optional coverage_owner identifies their requested Full area without changing the producing assessment_unit. Generic findings use actual field and role context.

Roles outside model assessment

The following audit identities do not enter model counts. They distinguish standards duties from the model obligations above.

Consumer contract

The mandatory existing request.inventory identifies the immutable area membership. esdieff.full-model/1 also binds the 54-member rfc9880.model/1 inventory, even when every new optional section is absent. Historical Full reports with null inventory and coverage.inventory_unavailable mean unknown membership, never an empty inventory.

The borrowed descriptor and typed status accessors do not render or allocate a report. Full returns all 54 known descriptors and authoritative statuses; an unfamiliar requirement ID is absent. Other operations do not request this inventory. Optional wire aliases, summaries, rows and ownership detail may be omitted under presentation limits. Consumers preserve mandatory aggregates and surviving diagnostic facts, accept unknown additive fields and human wording changes, and validate unique retained identities and linked omission counts. See the report contract.

Modified metadata assessment

Revision metadata can be assessed through Catalogue::check(CheckRequest::new().assessment(Assessment::ExpandedModified)) or esdieff check --assessment expanded-modified-v1 .... The immutable esdieff.expanded.modified/1 inventory contains the unchanged eight areas of esdieff.initial/1 and modified-date-time/1. Initial requests continue to check ordinary Information strings without interpreting modified date content. Complete full-baseline membership remains unavailable. This boundary follows ADR 0021: Explicit modified metadata assessment.

The ninth area checks info.modified directly, independently of reference composition. Its normative RFC 9880 Appendix A production is full-date ["T" partial-time "Z"]: four ASCII year digits, Gregorian month/day, optional hour/minute/second with a dot-plus-digits fraction, and UTC Z termination. ABNF literals admit lowercase t/z under RFC 5234 Section 2.3. Numeric offsets, including +00:00, space separators and date-free clock forms fall outside this metadata grammar. Data sample conventions remain separate under ADR 0018: Civil date and time sample conventions.

Catalogue scope checks every supplied document. Selected scope checks every root and each distinct source needed by surviving composition once, including mandatory target-root chains. Dependency metadata uses the same source preflight and modified scanner without independently assessing unrelated Information qualities or definitions. Candidate uncertainty or unfinished dependency discovery prevents a roots-only NotApplicable conclusion. Effective construction and inspection request no metadata-date assessment. This scope follows ADR 0023: Supplied global composition and dependency scope.

Years 0000 through 9999 use Gregorian arithmetic, including the four/100/400 leap-year rule. Hours are 00..23, minutes 00..59 and seconds 00..60 subject to exceptional-second meaning. Fractions keep every digit. Checking introduces no library year range, host date/timezone, fixed fractional precision, version-string scheme, SPDX requirement or live source retrieval. Source bytes, escapes and unrelated exact numbers remain unchanged.

Dated exceptional seconds reuse the recorded IERS C72 knowledge and byte identities in the civil-time contract. A possible adjustment minute is UTC 23:59 on the final Gregorian day of any month, following RFC 3339 Section 5.7. Second 60 elsewhere is a definite error without consulting leap knowledge. At possible slots within the inclusive interval 1972-01-01 through 2026-12-31, recorded insertions admit 60 and other dates reject 60; no negative adjustment is recorded, so 59 is established. At possible slots outside that interval, 59 and 60 remain undetermined. Seconds 00..58 need no leap knowledge. Snapshot expiry does not extend the recorded interval.

Reports include optional baseline.temporal_knowledge when the interval or insertion facts are consulted, including an outside-interval query. Its id, inclusive from/through, transition_sha256 and bulletin_sha256 fields identify the actual knowledge used. This record is separate from vocabulary-registry knowledge and survives omission of every diagnostic and coverage row. Merely having the snapshot available does not mean a check used it.

Report::assessment_area_status("modified-date-time/1") exposes semantic status independently of presentation. An expanded request returns Field::Present(AssessmentStatus::Assessed), NotApplicable or Undetermined. Assessed includes established errors. NotApplicable requires reliable absence across every requested document. Any needed unavailable source, member identity, text, critical meaning, leap fact or work makes the one aggregate area Undetermined while independent definite findings remain. Initial and inspection return Absent. Full binds modified work to M012 and full.metadata/1, preserving the producing condition ID while the standalone expanded area is outside Full membership. requested_coverage() sums to nine for expanded modified, eight for Initial and13 for Full.

Shared source preflight establishes critical-feature context and reliable Information/member identity before dependent conclusions. Its early metadata pass records existing metadata.string exactly once for reliable nonstring modified. Later unrelated work exhaustion or omitted detail cannot erase that aggregate error or its semantic area status. Unknown critical meaning defers dependent conclusions. Definite findings refer to original source pointers/spans; unsupported text, needed knowledge and exhausted work yield operational incompleteness. The finite check/report/pointer controls follow ADR 0013: Shared workflow and report guarantees.

Critical/member uncertainty and work exhaustion retain their shared conditions. Exhaustion of modified’s own text work reports operation.limit with assessment_unit:"modified-date-time/1"; ordinary source structural limits keep their existing attribution. A nonstring retains metadata.string; it does not acquire a duplicate modified-syntax finding. These conditions explain one aggregate ninth area rather than creating one requested unit per source or finding.

Unit names and recorded registry guidance

Unit work follows ADR 0027: Unit names and recorded registry guidance. Authors opt into Assessment::ExpandedUnits or esdieff check --assessment expanded-units-v1. The immutable profile esdieff.expanded.units/1 consists of the eight initial areas plus unit-spelling/1 and unit-registry-guidance/1. Initial, expanded modified, inspection and sample requests retain their inventories. Full joins both unit dimensions into M023 and full.special-type-unit/1 once, preserving producing condition IDs. Completing unit work does not complete other unfinished Initial or Full areas.

#![allow(unused)]
fn main() {
use esdieff::{Assessment, Catalogue, CheckRequest, SourceInput, RecordedRegistryPolicy};
let catalogue = Catalogue::from_inputs(&[SourceInput::supplied("fixture", br#"{
  "info": {}, "sdfProperty": {"Temperature": {"type":"number", "unit":"Cel"}}
}"#)])?;
let report = catalogue.check(CheckRequest::new().assessment(Assessment::ExpandedUnits))?;
let units = report.unit_guidance().require()?;
assert_eq!(units.known_primary(), 1);
assert!(units.complete());
// An embedding can exclude this recorded edition under its evidence policy.
let withheld = catalogue.check(CheckRequest::new()
    .assessment(Assessment::ExpandedUnits)
    .recorded_registry_policy(RecordedRegistryPolicy::WithholdRecorded))?;
assert_eq!(withheld.unit_guidance().require()?.unavailable(), 1);
Ok::<(), &'static str>(())
}

The corresponding CLI option is --registry-knowledge recorded|withheld. Both explicit values require a registry assessment; they are refused for initial, modified, inspection and sample requests. The additive report field is only policy.recorded_registry, with use_recorded or withhold_recorded. No arbitrary snapshot input, automatic network lookup, refresh or symbol rewrite is performed.

Decoded JSON text remains exact. Ordinary kg and Cel have recorded SenML positives, ms and /100 have secondary positives, and cel remains a scoped unknown. % retains its legacy ratio meaning, distinct from /100 percentage. A URI containing a colon is checked against generic full URI syntax, without validating resource content or scheme-specific meaning. Recognizable urn:ietf:params:unit:kg is prohibited; urn:ietf:params:unit:m%2Fs represents m/s and is also prohibited. urn:ietf:params:unit:example%3Aratio establishes the colon exception only, without certifying membership or assignment. %253A decodes once to %3A and supplies no represented colon. A slash written directly in the unit index is a Section 7.3 spelling error. Case-conflicting markers and percent-encoded markers retain separate uncertainty diagnostics.

unit_guidance() is Absent when not requested. Present complete or partial retains every established count independently of optional diagnostics. A reliable no-unit result is complete with six zeros and no registry observation; partial zeros do not prove absence. Nontext unit shape has an independent error and no invented registry query. Fixed semantic owner admission failure is outer Unavailable and wire state: unavailable, counts: null, reason: owner_limit.

Within recognized unit URNs, an empty or non-pchar-first r/q component is unit.urn_components_syntax, an RFC 8141 Section 2 error. An ordinary first top-level question mark is unit.urn_delimiter_advice, notice/advice with the same citation and its code as basis id, preserving the SHOULD processor recommendation. Literal index slash retains unit.index_syntax and its Section 7.3 basis. Valid component questions and fragments remain data; malformed URI escapes fail the generic URI check first. These component classifications can finish with URI count1, all query counts0 and no registry record. Completed classification does not establish URN conformance, represented-symbol meaning, definition or assignment. Other successful queries keep their own actual-use metadata.

The six counters describe final effective Full unit-quality coordinates within the requested roots. An independently checked provider root and each consuming copied coordinate count separately. Selected unused providers do not contribute observations. Overrides use the surviving unit, deletions contribute none, opaque Direct donors and critical/unresolved contributors supply no invented meaning. Alternative refinements are distinct effective coordinates; raw source preflight and replay frequency add no observations.

Only the first four are disjoint query outcomes. Neither their sum nor any counter asserts valid unit URN assignment. source_edition() returns borrowed raw edition facts when at least one section was consulted, even if later work stopped. It is Absent before any consultation or needed withholding, and Unavailable for needed withheld evidence. registry_knowledge("iana.senml-units") and registry_knowledge("iana.secondary-units") expose borrowed section-specific observations. Available means actual consultation, not match or completion. Needed withheld records contain only registry, state unavailable, snapshot null and reason caller_withheld. Before the first key comparison an operational stop produces no record; after it, the actual consulted section remains available. An unvisited secondary table stays Absent.

The raw IANA SenML XML was retrieved at 2026-10-05T16:49:51Z, with XML update date 2026-02-02. Its SHA256 is 3eff03640c5a5d2abd09e330488aeb9fae0b2766ea69b1114295bbec5c44e754. Raw bytes and section canonical bytes are retained as test fixtures. Canonical section extraction preserves XML row order and writes symbol<TAB>true|false<LF> with no header. Primary 67 rows occupy 630 bytes, SHA256 6246352c590e933b72c25ef9f363171e40fea347bb7e23d08b04f9436894ed34; secondary 39 rows occupy 398 bytes, SHA256 de5c5c009ffbc61aa66e71ee55065f95108709575906c6ec7cd64a2bbc7e173b. entries_count describes the extracted section, while raw_digest describes the common full XML edition. Generated Rust tables and public exact-name controls are checked against every captured row, flag and canonical byte. Production does not parse XML.

Before effective or registry scanning, Catalogue::check requires the existing source/scope reserve C plus E to fit report_bytes, after Catalogue acquisition and decoding. E is 21448 for expanded units and 31448 for full-baseline registry work; the separately prepared content contribution is 19116. These are ownership-derived reserves, not minimum wire lengths or measured resident-memory claims. A single supplied source key fixture contributes seven metadata bytes, giving C=20522 and exact unit admission 41970; 41969 refuses before checking work. At that cap every optional coverage row and diagnostic can be omitted without losing errors, counts or consulted evidence.

The fixed unit owner is bounded by 128 bytes and shared control by 16. Two complete extension DTO generations plus owners receive 4E; independent output and old/new buffer growth receive another 4E. Units D=42824 and owners144 imply 2D+144=85792=4E. Full registry composition has six possible records at array capacity8, D=62792 and owners208, giving 125792=4E. Shared parents, policy, profiles, arrays and control are paid once. Existing mandatory source/scope owners remain in C; optional detail and scratch use only the positive R-(C+E) remainder, preserving the existing total 8R accounting. No per-name mandatory graph is retained.

Qualification guards word<=8, String<=24, Value<=128, Map<=256 and alignment<=8. Up to ten entries fit a default BTree leaf or the qualified IndexMap growth from7 to14 dense buckets and8 to16 index buckets. Old/new controls include both bucket counts and group tails, 248 bytes on the qualified 8-byte-word backend; the guarded per-map bound4024 fits4096. Static record text has fixed safe ASCII caps and no caller strings. Synthetic simultaneous field caps produce a conservative 530-byte record bound including array punctuation; actual finite literals are qualified independently. The six-record synthetic array is3175 bytes and the projected full fixed wire7271 fits7680. This is a requested-capacity and source-specific accounting argument, not a portable allocator-overhead guarantee. Dependency or graph changes require renewed qualification.

Every new visited source row, node, member, ancestry/alternative step and examined key byte is precharged on the original operation allowance. Unit text receives a finite32-times-byte allowance for URI, markers, suffixes, pchar, UTF-8 and optional exact replacement passes; each registry comparison then precharges its row and both examined key lengths. No replay or per-value refill changes counters. With at most100000000 work units, each checked u32 observation count is bounded below u32 maximum. Optional replacement allocation is charged to diagnostic storage after the spelling premise and its copy work are admitted; detail omission cannot retract a prohibition or lookup result.

Content-format declaration contract

Assessment::ExpandedContentFormat, selected by CLI --assessment expanded-content-format-v1, requests the fixed inventory esdieff.expanded.content-format/1. It adds content-format-syntax/1 and content-format-registry/1 to the unchanged eight initial areas, following ADR 0029: Content-format declarations and recorded registry guidance. The initial, modified, unit and sample inventories keep their existing membership. FullBaseline additionally assesses the bounded declaration meanings below within M024 of its immutable model inventory, following ADR 0033: Content-format model meaning.

The population is final effective Full data descriptions at distinct consuming coordinates, including properties, reusable data, Action input/output, Event output, map properties and established alternatives. Reference overrides and deletions determine the surviving value. A selected check excludes unused donor declarations; a catalogue check independently includes reusable definitions. Each inherited consumer remains a distinct observation with an effective primary location and its nearest source contribution as related evidence. Raw bytes, authored case and coding order remain unchanged. Ordinary scalar getters and initial string-shape checks retain their meanings.

Direct items and opaque donor content do not acquire Full semantics from a familiar spelling. Deleted values and reliable absence are NotApplicable. Unavailable effective content, decoded text, member or role identity, donor meaning and critical-feature context prevent dependent conclusions. A known nonstring value receives the existing data.string error once; it is not invented lexical text. Independently established errors survive uncertainty elsewhere.

Complete spelling and separate range

RFC 9880 Appendix A note 2 references RFC 9193 Section 6. The complete string must follow that grammar. A decimal number is 0 or a nonzero digit followed by zero or more ASCII decimal digits, without a grammar digit ceiling. Signs, leading zeroes, whitespace, fractions and exponents fail spelling. A fully decimal spelling outside 0 through 65535 has a separate Section 3 range error under recorded interpretation I-CF-RANGE-1. Whole classification precedes range: 123456/application is a media name, not a decimal range error. Arbitrarily long decimal strings are compared by exact spelling and length, without machine-integer overflow.

Media type and subtype each contain 1 through 127 ASCII bytes. Their first byte is alphanumeric; remaining bytes may also be !#$&-^_.+. A single slash separates them. Wildcard media components, non-ASCII bytes and %, apostrophe, backtick, pipe or tilde in a media component fail this narrowed grammar. Registry comparison ignores ASCII case while retaining the original text.

Parameters follow optional ASCII SP, semicolon, optional SP, a nonempty tchar name, equals, and a nonempty tchar value or quoted value. tchar adds !#$%&'*+-.^_ followed by backtick, pipe and tilde to ASCII alphanumerics. There is no whitespace around equals. A quoted value may be empty; ordinary quoted bytes are SP, !, and ASCII ranges # through [ and ] through ~. Backslash pairs accept ASCII SP through ~. Tabs, controls, DEL and non-ASCII quoted bytes fail, including escaped forms. @, semicolon and equals inside quotes are data. Only SP before a following parameter semicolon is admitted; leading or trailing whole-string whitespace is not.

Each content coding is @ followed by a nonempty tchar token. There may be zero or more ordered tokens, including duplicate tokens. Comma lists, empty tokens, quoted tokens, whitespace and coding parameters fail spelling. An absent coding adds no implicit lookup. The explicit token identity passes spelling but has reserved meaning outside this inventory.

ExpandedContentFormat excludes parameter meaning, including duplicate-parameter meaning, and discloses this with a Notice. This permits completion of its advertised declaration inventory when syntax and dated queries finish. FullBaseline has the additional bounded meaning rules below. Neither operation establishes payload decoding, sample validity or a protocol binding.

Bounded Full model meaning

Established nonempty Choice and Enum collections request declaration meaning from their final inherited alternatives. Superseded shared declarations and their original descendants do not request an additional model interpretation. The existing spelling and registry-guidance passes retain their population and actual-use metadata; an unsupported declaration inherited by any final branch still leaves its meaning unfinished.

An available numeric Content-Format identifier designates its complete recorded CoAP tuple: content type including registered parameters, and its optional coding. All 119 captured positive tuples are retained exactly and independently checked against the canonical source records. No separate media or coding registry query is inferred for a numeric declaration. Withheld CoAP evidence cannot be recovered through another table.

Explicit media names use these supported rules:

Media and parameter names compare without ASCII case. The supported charset values also compare without ASCII case; token and quoted spellings, including decoded quoted pairs, are equivalent under RFC 9110 Sections 5.6.6 and 8.3.1. Other media rules, parameters, charset meanings and duplicate parameters remain Unassessed, with content_format.model_meaning_unassessed as an Incomplete condition. A registered name such as multipart/mixed does not establish that required parameter knowledge is available. Unsupported meaning creates no invented definite RFC error.

Positive coding tokens denote their designated transformations in authored application order, including repeated occurrences, following RFC 9193 Section 3. No @ means no transformation and no coding query. Unknown codings and explicit reserved identity remain Undetermined; no HTTP negotiation meaning or header prohibition is silently imported. Raw case, parameter text, coding order and source origins remain intact.

Actual admitted consultation of these Full rules is recorded as content-format-model-meaning/1, independently of successful establishment or optional diagnostics. A numeric tuple consultation needs its available recorded evidence. A normative media-rule consultation may occur while a separate registration query is withheld. Neither fact hides unfinished registration or meaning.

Evidence and statuses

RecordedRegistryPolicy::UseRecorded is the default evidence policy for relevant checks. WithholdRecorded deliberately withholds recorded evidence according to an embedding’s trust decision. The CLI uses --registry-knowledge recorded|withheld; both explicit values require the content, unit or full-baseline assessment. Initial, modified, inspect and sample requests refuse that option. Reports emit one policy.recorded_registry=use_recorded|withhold_recorded value, without a competing request field.

Statuses aggregate the entire requested effective population. An unfinished required pass remains Undetermined; a condition’s omission cannot make it Assessed. An unknown query cannot be relabeled an unavailable table. Current registration, available evidence and completed lookup are separate facts. The existing requested coverage counts remain authoritative even when every optional area row and located condition is omitted. Other unfinished Initial work can keep an expanded outcome incomplete. Full joins spelling, range, registration and bounded declaration meaning into M024 and full.pattern-format/1 once, preserving their producing IDs. One unsupported or unknown sibling keeps that obligation unfinished.

Report::registry_knowledge(id) borrows actual-use facts for coap-content-formats, media-types and http-content-codings. Before the first admitted key comparison, unavailable operation work fabricates no table consultation or entry. After a comparison, that table remains available even if lookup later stops. An unneeded table is Absent. Needed withholding produces registry, state unavailable, snapshot null and reason caller_withheld, without digest, dates or entry counts. Failure to admit the semantic metadata owner returns Unavailable for requested registry IDs. Existing wire states remain available and unavailable.

Recorded primary editions

All three raw XML editions were retrieved at 2026-10-05T16:55:20Z. Exact raw bytes and canonical extracted JSON are retained in tests/fixtures/content-format. Production uses static Rust key/flag projections, with no XML parser, network access or implicit refresh. Metadata scope is relevant_dated_positive_records; extraction policy is iana-content-format-positives/2.

Canonical bytes are compact JSON arrays with fixed field order and one terminal LF. Numeric rows are sorted by exact u16 identifier and contain id, content_type, coding, flags, temporary_annotation and temporary_expires. Thirty-six Reserved/Unassigned records or ranges are excluded from 155 raw CoAP rows; all three temporary positives retain their dated annotations. Empty coding is null, without inventing identity. Media rows contain key, canonical, template and flags; coding rows contain key, canonical and flags. Each flags object orders obsolete, deprecated and temporary. Name keys are sorted ASCII lowercase solely for comparison. Media retains 24 obsolete and eight deprecated flags; HTTP retains two deprecated flags and excludes the reserved identity row from its 13 raw rows.

For media identity, a template file’s explicit name attribute takes precedence; otherwise its text is the identifier. The file text is also retained separately as the template target. Thus deprecated image/x-emf and image/x-wmf remain separate identifiers targeting image/emf and image/wmf. Display text is used only for dated status flags, without a guessed identifier-stripping rule. Global case-insensitive duplicate checks merge only fully identical records; conflicting canonical fields or flags stop extraction rather than choosing a winner. Every generated product key and flag is tested against all captured canonical rows, including both aliases.

Finite ownership and work

After Catalogue acquisition, check admission requires the existing source/scope reserve C plus E before new scanning. Econtent is19116, Eunits21448 and combined Full31448. C depends on actual caller metadata: one supplied key authored has eight bytes, C20528 and exact content admission39644;39643 refuses. Seven-byte fixture has C20522 and39638;39637 refuses. Applicable existing role and selector reserves remain independent.

Two complete extension DTO generations and fixed owners receive4E; independent encoding and old/new growth receive another4E. With the recorded extension record, the Full extension bound D62792 and owners208 give 2D+208=125792=4E. Its six registry records use array capacity8. The complete report may have eleven interpretations: four registry interpretations, civil representation, Byte and Unix conventions, both UUID interpretations, copied reference relocation and undeclared extension vocabulary. This grows the interpretation Vec from8 to16; an old8 backing may coexist with new16 and the registry8 backing. Qualification charges all32 Value slots plus eleven40-byte text caps against the existing combined array share1536. On the compiled32-byte Value backend this is1464. It also exercises both complete actual DTO generations, retained-result fallback and wholly omitted optional details at the original admission cap. The actual maximum extension graph bound is36634 bytes; two generations, growth and owners use73732 of125792 available bytes. The private content owner, its maximum alignment padding and borrowed view still fit64 bytes. These are source-specific ownership bounds, without a portable ABI, allocator-overhead or resident-memory claim. No existing allowance grows automatically.

Every visited source, effective node, member/key, ancestry, alternative and examined text byte is precharged on the original operation allowance, including excluded Sample rows. Whole borrowed classification pays a finite32-times-byte coefficient plus one; lookup separately precharges each compared row and both byte lengths, conservatively paying the complete static key maximum before reading a name row. No per-declaration refill, allocated lowercase copy or mandatory per-name graph is used. Four checked u32 counts remain bounded by the100000000 maximum work allowance. Optional finding capacity and retained unit replacement strings keep their already consumed diagnostic storage; beginning the content module cannot renew that credit. Presentation omission preserves errors, requested aggregate counts and actual-use evidence.

One shared borrowed walker first completes the eligible grammar/range population and then replays the already derived effective coordinates for registry queries. Candidate/classified observations, spelling/range findings and parameter-exclusion Notices occur once in the first pass; query/unresolved observations occur only for actual second-pass attempts. An interrupted first pass never starts registry replay. Operationally finished traversal is distinct from monotonic unknown meaning: a completed traversal with an unknown donor or critical premise may still query a different reliable coordinate. Every second-pass stop preserves the first pass’s syntax status, including any previous Undetermined state.

A finished first pass with no reliable query-needed bits omits replay, preserving earlier unknowns and fabricating no consulted or withheld facts. Otherwise replay pays traversal and full borrowed classification again from the same remainder, without re-composition, new arenas or a replenished allowance. This permits later independent grammar/range findings to survive lookup exhaustion. The ordinary cost is additional finite work and later first consultation: a tight request can stop before a table formerly reached. Work thresholds are source-specific capability observations, not public constants or a runtime-doubling claim. Under Full, the unit module still runs before content on the same allowance; this scheduling separates content grammar from content lookup.

Effective model pattern syntax

Model authors can request Assessment::ExpandedPatternSyntax or use esdieff check --assessment expanded-pattern-syntax-v1 model.sdf.json. This immutable profile is esdieff.expanded.pattern-syntax/1: the initial eight assessment areas plus pattern-syntax/1. It checks the syntax of effective string-valued pattern qualities. The reasons are ADR 0014: Bounded partial ECMAScript pattern capability and ADR 0028: Bounded effective model pattern syntax.

Syntax follows RFC 9880 Appendix C.2 and ECMA-262 2025 Section 22.2.1, with Unicode u semantics. The suggested portable subset is not a restriction on permitted syntax. A private pinned regress 0.12.0 parser uses Unicode mode with optimization disabled. This partial capability independently guards active Unicode escape spelling, escaped name terminators and decimal quantifier endpoints; an unverified parser rejection does not establish an RFC error.

Full descriptions at Property, sdfData, Action input/output, Event output, nested properties and final choice/enum alternatives are eligible. An explicit type:"string" is unnecessary for model syntax checking. A present nonstring retains its ordinary data.string shape error and supplies no string syntax operation. Restricted Direct items retain opaque pattern vocabulary; their eligible Full properties and alternatives are checked. A Direct donor’s unavailable pattern meaning stays unavailable in a Full receiving branch until a surviving explicit Full override establishes that quality.

Composition precedes this rule. A surviving inherited pattern is assessed at its consumer’s effective path with the nearest authored source token related. A surviving override uses its own authored token; a merge-patch null deletion removes the quality. Ordinary source null remains an ordinary nonstring value. Source structural replay does not cover syntax and cannot suppress this rule. Unknown needed critical context, role, member, contributor or text leaves affected work unfinished while available siblings remain usable. Source content is never substituted for unavailable effective meaning.

Catalogue checks independently root every model source, including unused definitions. Selected checks assess surviving content of their selected roots and needed imports. Listing a dependency does not separately assess its unused, overridden or deleted patterns. Source/effective inspection and other explicit assessment profiles retain their purposes. Selected sample checking checks needed pattern syntax as a model parameter before matching; it does not request the expanded model-syntax assessment or change that assessment’s inventory.

Every retained pattern condition has assessment_unit:"pattern-syntax/1". Fixed messages keep private parser text out of reports. Optional condition, coverage-row or pointer omission preserves established errors and semantic status. Failure to retain a finding after proving invalidity omits its detail without creating a semantic limit. Several unsupported patterns still leave only this one requested area undetermined.

FullBaseline also runs this available rule, owning M047 in full.pattern-format/1 of its fixed13-area inventory. Producing conditions retain pattern-syntax/1; optional coverage_owner identifies the Full area. Syntax completion is separate from the modeled matching capability M048. The report contract separates findings, requested coverage and broader coverage.

Only three syntax capacities are configurable: Limits::pattern_bytes at most 4096 UTF-8 bytes, pattern_nesting at most 64 group levels, and pattern_alternatives at most 512 total alternatives. Defaults are these ceilings; zero or larger values are configuration errors. Decimal quantifier endpoints at or above 1,000,000 exceed capability; reversed decimal bounds independently establish invalidity without machine-integer conversion. Capture-name length, matching capture slots and named-scope limits are matching capacities, not syntax restrictions.

Traversal, guard scans, decoded-name storage, comparisons, parser admission and pattern finding capacity use the original operation’s remaining work/allocation counters. Sources, branches and patterns receive no fresh allowance. Before its first worker, syntax reserves one logical 4 MiB stack slot from that original allocation allowance and retains it for sequential reuse. One worker is created lazily for the allowance and joined when it is dropped. Guards, parsing, emission and destruction stay inside it, and no engine object escapes. A lowered allocation limit unable to admit that slot leaves syntax unfinished.

Work accounting counts logical byte visits and admitted dependency invocations. Finite input/structure admission does not measure every parser/emitter instruction, bound its private heap, enforce cancellation or promise total resident memory or a wall-time deadline. The library owns the lifecycle, so embeddings need no executable discovery, caller runtime or regex-engine types.

Report admission adds 171 bytes to the existing applicable mandatory reserve for either invoking profile, before composition or syntax work, and subtracts the same amount from optional presentation space. Mandatory owners, optional owners and encoding/output buffers keep their existing independent partitions. This reserve adds no engine manifest or complete-conformance claim.

Model matching meaning

FullBaseline establishes M048 only when the surviving effective pattern can be compiled by the adopted Unicode, unanchored matching implementation. It supplies no subject, performs no match and does not seek a satisfying witness. A pattern such as (?!) therefore has established matching meaning despite admitting no text value. M047 independently owns syntax errors.

Compilation reuses the selected sample matching implementation, including its runtime allocation probe, matching-only capture/name/scope guards and original operation allowances. Syntax can be assessed while M048 remains undetermined because matching capacity is unavailable. Zero remaining interrupts or duration, worker/runtime capacity, unsupported interpretation and invalid syntax also leave matching meaning unfinished. The compiler uses the same paid sequential worker stack slot and configured heap reservation as sample matching. No new allowance is assigned to a pattern or alternative.

Byte-string model interpretation does not establish whether an authored text pattern constrains encoded text or byte data. That affected M048 meaning stays undetermined under ADR 0007: Generated SDF and sample JSON; the independently known byte interpretation, base type and pattern syntax retain their own observations.

This establishes the adopted modeled interpretation and available compilation capability. It does not promise that every future subject fits the subject, allocation, interrupt or duration allowance. Parsing and compilation retain the finite supplied-size guards and lack external cancellation, as documented in ADR 0014: Bounded partial ECMAScript pattern capability.

Selected sample matching

Catalogue::check_sample and the sample command apply Unicode u matching to needed ordinary nonnull string values. Matching is unanchored unless the authored pattern supplies anchors. Unicode escapes, character classes, lookaround and backreferences use the pinned ECMAScript engine selected by ADR 0014; the suggested portable subset is not imposed as a restriction.

A definite mismatch is sample.pattern, a sample-domain error with RFC 9880 Appendix C.2 as its basis. Its primary location is the actual sample value, with an original span for byte input and a null span for a typed input. Related locations identify the effective consumer pattern and nearest authored source token, including imported and overridden patterns. A mismatch can coexist with independent length or const failures. Optional diagnostic, witness and pointer omissions do not change the established rejection or its counts.

A malformed needed pattern remains a pattern.syntax model error. Its sample matching conclusion is undetermined; the malformed model alone does not prove a sample mismatch. A complete good choice alternative can admit the sample and finish the text area while the independently established model error still fails the operation. Nontext samples and null do not request text constraints. Opaque Direct items and inherited unavailable meanings remain unfinished.

Unsupported matching produces pattern.unsupported; finite matching work, subject, engine compilation, allocation or stack exhaustion produces operation.limit. Both use operational pattern-matching-capability and identify sample-text-boolean/1, preserving independent findings. Neither is a syntax violation or a sample acceptance restriction. The fixed nine-area esdieff.sample/1 inventory remains unchanged. Supported matching also feeds selected choice witnesses and declared-value consistency; documentary defaults are never inserted as sample data.

The supported controls are Limits::pattern_subject_bytes at most 1 MiB, pattern_heap_bytes at most 16 MiB of configured engine allocation, pattern_stack_bytes at most 256 KiB, pattern_interrupts at most 10,000 polls and pattern_deadline at most one second of accumulated cooperative engine time. Defaults are 1 MiB, 16 MiB, 256 KiB, 100 polls and 25 milliseconds. Subject, allocation and stack settings must be nonzero; zero polls or duration gives a work limit. Each engine call spends one entry poll, and engine interrupt callbacks spend the same shared remainder. Short matches therefore spend allowance even if the reused runtime does not reach its internal callback interval. The engine allocation setting excludes allocator rounding and overhead and is not a resident-memory guarantee. A minimal-limit runtime probe checks gross enforcement, including feature-unified embeddings. Pattern size, nesting and alternatives retain the syntax ceilings above.

Matching-only capacities are 124 decoded UTF-8 capture-name bytes, 254 explicit captures and 256 alternatives when any named capture occurs. These limits are applied after syntax admission and leave matching incomplete. Syntax and matching share the original operation work/allocation and one paid worker stack slot; the engine reservation, polling allowance and cooperative duration are retained across values, alternatives and declared-value candidates. Parsing and compilation remain finitely admitted but have no externally enforced cancellation. One runtime and context are initialized lazily and reused within the allowance. Each call compiles its own expression, clears pending exceptions and collects garbage. Request text is copied only after admission against the original work and allocation counters. The runtime is destroyed on its owning worker when the allowance is dropped.

Explicit numeric contradiction advice

Select Assessment::ExpandedNumeric or CLI --assessment expanded-numeric-v1. The request, inventory and requested-coverage identity are esdieff.expanded.numeric/1. It contains the Initial eight areas plus advisory-numeric-three/1, counted once across the selected model scope. This follows ADR 0030: Bounded numeric advice.

Conditions have Warning severity, Advice basis, their warning code as basis ID, and RFC 9880 Appendix C.1 as the constraint citation. Strict warnings changes disposition while preserving severity, counts and completion. Failure to find a warning establishes no general satisfiability, sample admission or restrictive refinement. Initial, other expanded profiles and Full keep their existing scopes.

Final meaning and applicability

Only established effective Full data descriptions are evaluated: Property and sdfData definitions, Action input/output, Event output, properties entries and derived Choice alternatives. Direct items themselves are excluded. A receiving Full role does not upgrade unresolved Direct donor meaning. Surviving established overrides supply their own meaning and original token provenance. Enum text occurrences remain distinct existing alternatives; they are not parsed as numbers. Choice and Enum owners receive no union emptiness proof.

Exact arithmetic and limits

The original exact number token is retained. Signed zero and equivalent decimal notation compare by mathematical value. Endpoint quotient rounding accounts for sign, remainder and exclusive integral endpoints. For positive decimal step p/q in lowest terms, integer values use the common lattice pZ. For example, integer [1,2] with step 1.5 has a gap, while number [1,2] includes 1.5.

Virtual long-division numerator/denominator widths are bounded at 1024 digits; adjusted quotient buffers allow 1025, and finite coefficient factor storage 513. A small-magnitude quotient shortcut precedes virtual-width admission. Large matching exponents can cancel; a large unmatched exponent can be unsupported. The integer intersection uses the numerator of the reduced decimal step. Thus integer [1,2] with step 0.6 has no admitted value, while step 0.2 admits both integers. A valid source number can exceed the derived quotient width without being a malformed model parameter. These are implementation capabilities, not restrictions on the standard’s mathematical numbers. No exponent-sized buffer or exponent-counting factor loop is used. The original numeric-work and derived-allocation remainders are shared across classes, models and alternatives, including input work already consumed.

Relevant unavailable meaning, magnitude, work or storage makes the one area Undetermined. A supported attempt is Assessed even without a warning; complete traversal with no eligible class is NotApplicable. An operational proof.numeric_capability_unavailable condition uses basis expanded-numeric-capability, its class and reason, and no citation key. The undetermined area uses expanded-numeric-establishment; completed and not-applicable area rows use Advice basis advisory-numeric-three/1.

The additional mandatory report reserve is zero. Coverage rows and located conditions can be omitted at the original report admission floor; exact nine-area counts, statuses and outcome remain available. Four operand positions preserve the existing first three meanings and add step/null-guard provenance where needed. Presentation omissions do not discard established warnings or hide unfinished siblings. See the report contract.

Initial contradiction advice

Esdieff explains four kinds of constraint contradiction in established effective Full Data Descriptions. Each proven contradiction produces warning advice with a stable proof.* code and assessment_unit:"advisory-four/1". This follows ADR 0003: Check findings and completeness, ADR 0009: Bounded processing and reporting, and ADR 0013: Shared workflow and report guarantees.

For example, type:"number", nullable:false, minimum:2, exclusiveMaximum:2 admits no numeric value. The warning explains the conflicting effective bounds, their nearest source contributors and the importing reference when present. Composition repairs and deletions are applied before proofs; the original source bytes remain available.

Owners with enum or sdfChoice are excluded, including malformed selectors. Established derived alternatives and nested full properties have their own guards. Direct item descriptions themselves are excluded; inheriting a direct-item quality into a Full alternative does not establish a meaning that was unavailable in its donor. The effective alternatives contract preserves these distinctions.

Guard uncertainty affects only proofs that depend on it. Unrelated default, requiredness, unit, contentFormat or opaque descendants do not veto independent ordinary numeric bounds. Unsupported sdfType, byte-string, unix-time and unknown format meaning leave dependent conclusions unfinished. Recognized abstract formats alone do not establish nonnull primitive const compatibility from a conventional JSON representation. Unavailable roots, named entries, collections or traversal also defer the advisory area while independently established warnings remain available.

Acquisition spends numeric work across all supplied sources. Each check starts one counter from the immutable remaining acquisition budget and shares it across descriptions, inherited instances, classes and pairs. Exact comparison charges the longer normalized coefficient length plus one before comparing. Integrality premises charge one unit each. Exponent gaps do not allocate expanded numbers, and normalized powers do not reapply raw exponent limits. A failed numeric precharge leaves an unproved conclusion unfinished and produces operational operation.limit with the advisory area, proof class, comparison or integrality operation, and affected Quality Names. Independent nonnumeric proofs can still warn. Repeating a check uses the same immutable acquisition remainder.

These numeric limit conditions use Operational basis advisory-numeric-work. Their bounded arguments include proof_class with the corresponding proof.* code, operation with compare or integrality, and qualities with the one or two affected Quality Names in operand order. Available effective/source locations and optional exact lexemes follow the same witness bounds as warnings. Unavailable input meaning remains a separate establishment limitation; omitting a witness for presentation limits does not create another unfinished semantic check.

Optional witnesses retain at most eight locations: the effective description, up to three effective contradiction operands, their nearest source contributors and an importing consumer. Type is also a bounded argument. Numeric argument values retain original lexemes as strings when at most 1024 bytes; no floating conversion is used. Enum const contributors point to their actual authored occurrences. Count, byte and pointer limits can omit these details without changing aggregate warning counts or semantic coverage.

The fixed initial inventory has eight areas. These proofs determine advisory-four/1 independently of the seven structure/composition areas. The first three classes require established nullable false before becoming applicable; declared or specified-default true excludes them. Relevant uncertainty makes the advisory area undetermined once across the whole requested scope, regardless of how many specific numeric limits are reported. Full includes this same advisory area once alongside its12 model areas. Inspect does not perform these proofs. Absence of a warning does not establish general satisfiability. Strict warnings affect disposition, preserving warning severity and counts.

Declared-value consistency

Use Assessment::ExpandedConsistency in the library or esdieff check --assessment expanded-consistency-v1 in the command. The requested identity esdieff.expanded.consistency/1 contains the unchanged Initial eight areas and const-consistency/1 and default-consistency/1, counted once across model scope. Other assessments retain their membership, including Full’s fixed model inventory. See ADR 0031: Bounded declared-value consistency and the shared report contract.

const restricts data to a stated value. default is documentary data that may be used when interaction data is absent; base SDF defines no insertion process. This assessment checks stated values against their final effective data description. It does not modify either model or sample input, infer absent data, prove restrictive refinement or perform general satisfiability analysis.

Candidates and alternatives

Formatted-null equality follows ADR 0015 across the six base string formats. Null equals null and differs from an established nonnull formatted value; an invalid or uninterpreted nonnull operand leaves the comparison unfinished. Nullability can independently exclude a null constant or default. A null default can be excluded by a nonnull constant and vice versa without inserting any value. The same contextual comparison supports actual compound candidates, preserving one advisory warning per definitely excluded candidate and scoped uncertainty.

An ordinary description contributes its surviving const and default values. Choice overrides replace shared qualities, so each final alternative contributes its const candidate; an Enum occurrence is distinct even when two occurrences have equal text. A shared owner default is checked once against the complete Choice or Enum. An introduced or overridden branch default is checked separately. A branch reference introducing a donor default is local to that branch even when its source origin is inherited. Deleted branch overrides fall back to the surviving shared quality according to ADR 0024: Effective alternatives and nullable characteristics. Distinct importing consumers are assessed in their own effective contexts.

An alternative must admit the entire candidate. Constraints from different alternatives cannot supply different pieces of one witness. If one alternative admits it, the candidate is not excluded. If an unknown alternative could admit it, exclusion remains undetermined.

Supported reasoning and limits

The shared selected-value evaluator handles established ordinary scalar root kinds, null admission, exact numeric integrality and bounds, positive steps, Unicode scalar text lengths and supported Unicode ECMAScript patterns, map required entries and present properties, array counts, applicable items and contextual uniqueness. Equality preserves exact numbers, decoded text and structural values under the resolved description. Defaults are also checked against a surviving const restriction.

The same rules apply inside compound candidate values and nested named alternatives, including required presence, exact inherited/overridden numeric fields, compound const, contextual uniqueness, Unicode patterns, the six base string formats and the byte-string/POSIX conventions. A warning still belongs to one excluded declared-value candidate, with its actual decisive leaf and effective constraint. A sample mismatch remains a sample error in the separate sample operation. Documentary defaults do not fill missing required sample entries.

Civil date, time and date-time denotation follows ADR 0018: Civil date and time sample conventions through the same evaluator. An invalid civil candidate can supply established exclusion advice; unavailable leap meaning leaves consistency unfinished. Actual convention and C72 use are recorded even when an independent length restriction already excludes the candidate or a branch result is discarded. Under a common compatible format, established dates compare by calendar date and dated date-times by UTC instant with exact fractions and distinct inserted-second slots. Date-free time retains the identical-valid-representation boundary.

Unsupported needed pattern matching, other special formats or types, extension meaning, Direct item meaning, reference interpretation, unavailable data and finite semantic, numeric, equality or allocation limits leave the affected area unfinished. An empty array does not require unused item meaning, and an absent optional map property does not request its value constraints. Established independent restrictions can still produce advice while other work remains unfinished. Completing consistency does not complete Initial or other requested work.

Pattern matching follows the pattern contract. A malformed pattern actually consulted for a candidate is an independent model syntax error, recorded once per effective pattern even across const and default candidates or discarded alternatives. A complete admitting alternative can finish consistency while that model error still fails the operation. A dormant pattern without a candidate, or a constraint on an absent optional candidate entry, is not requested. The model-condition identity remains separate from optional diagnostic retention.

An established alternative collection may remain incomplete because some branch meaning is unfinished. Its owner candidate can still be evaluated when that deferral only summarizes the established branches. Every possible branch must independently exclude the entire candidate; a potentially admitting branch prevents advice. Local owner failures, unavailable candidates and unknown applicable constraint premises retain their existing limits. Aggregate deferral never makes the enclosing operation complete or supplies meaning to an unknown branch.

Each area uses assessed, not_applicable, unassessed or undetermined with shared status meanings. Assessed includes established exclusions. No applicable candidate after complete traversal is not applicable. Needed unsupported or unavailable evaluation makes the area undetermined. A completed or not-applicable row has Advice basis; an unfinished row has Operational basis without an RFC citation. The requested denominator stays ten when rows or condition details are omitted. Unavailable candidate-bearing containers also leave both areas unfinished when their descendants cannot be traversed. This includes hidden Full descriptions in Direct item properties or alternatives; it does not assess a Direct item’s own default or give unavailable descriptions evaluation capability. Established subtree overrides and opaque content retain their existing role boundaries.

Findings and provenance

consistency.const_excluded and consistency.default_excluded are advisory warnings, one per excluded candidate. They never add sample errors or turn advice into an RFC violation. Existing Initial warnings retain their producing identity and count: type: "boolean", const: 1 can produce the existing primitive contradiction and one const consistency warning, for two warnings in total. Strict warnings change disposition only. Aggregate counts survive zero diagnostic detail.

The source primary identifies the real decisive candidate leaf, or the real container when absence or structure is decisive. Related locations include actual effective description/constraint operands, paired values for uniqueness, a branch identity when needed, original contributions and the importing consumer. Composed values never claim a fabricated original Sample source or a donor’s whole compound token. Location or condition omission is explicit and preserves aggregate advice.

One request owns the remaining equality, numeric, semantic and allocation counters across all candidates and final alternatives. No per-candidate allowance, refill, refund or source-as-effective fallback is introduced. Existing mandatory report owners hold the two area aggregates; no added mandatory reserve is required.

Selected-sample operation contract

This extends the shared workflow and report contract under ADR 0016: Selected samples with explicit admission and coverage. It specifies observable behavior for the library, command, and versioned report. API spelling remains replaceable until implementation. Standards meanings follow the recorded baseline, RFC 9880 Sections 4.7, 5.2, 5.3, and 5.4, and normative Appendix C. This contract does not introduce a generic JSON Schema validator or a protocol payload binding.

The numeric workflow and typed projection boundary follow ADR 0025: Selected numeric samples. An ordinary Rust caller registers both roles together:

#![allow(unused)]
fn main() {
use esdieff::{Admission, Catalogue, SampleKind, SampleRequest, SourceInput};

let catalogue = Catalogue::take_inputs(vec![
    SourceInput::supplied("model", br#"{"sdfProperty":{"level":{"type":"number","maximum":100}}}"#),
    SourceInput::supplied("sample", b"101").sample(),
])?;
let report = catalogue.check_sample(
    SampleRequest::new(catalogue.source_id("model").unwrap(), SampleKind::Property,
        "/sdfProperty/level").sample(catalogue.source_id("sample").unwrap()),
)?;
assert_eq!(report.sample_result().unwrap().admission(), Admission::Rejected);
Ok::<(), &'static str>(())
}

For typed input, JsonBuilder constructs bounded values and SourceInput::typed registers their owned projection as a Sample source. Catalogue::take_inputs consumes inputs; Catalogue::from_inputs preserves the borrowed-input interface with bounded copies. Source::sample_value and SampleResult::sample_value expose the dedicated value view, whose span is optional. Source::has_original_bytes distinguishes original bytes from a projection, and Source::json returns unavailable for a typed projection because it cannot supply original-source spans.

Declaring selector identity is retained under a bounded metadata allowance, independently of displayed pointer limits and an older handle owner’s derived storage. Its ceiling is 8192 bytes; an Action/Event suffix can extend the internal description pointer to 8206 bytes. Mandatory sample reporting reserves 163930 additional wire bytes and a separate ownership/DTO share within the existing report allocation model. Exact requested string, ancestry and single-result capacities are precharged. Exhausted semantic storage, work, nodes or reference applications produce an unfinished domain result rather than losing the mandatory selector. The accounting and fixed-field inventory are recorded in ADR0025.

Conventional abstract samples

sdfType: "byte-string" selects canonical unpadded base64url decoded JSON text. Empty text is valid; padding, non-URL alphabet, whitespace and nonzero unused tail bits are rejected without repair. sdfType: "unix-time" selects exact numeric POSIX coordinates. Nonnegative fractions, large coordinates and -0 are supported within the existing exact-number capabilities. Negative nonzero numbers remain usable inputs with unfinished abstract denotation, rather than representation errors. Independent integer, null and other constraints retain their own conclusions. These conventions follow ADR 0007 and do not establish formal CDDL or protocol-payload admission.

Both const operands must establish their denotations in a common compatible context before equality or difference is concluded. Const, enum, compound values, uniqueness and consistency use that shared comparator. Applicable byte length or pattern qualities remain unfinished where their abstract interpretation has not been established; no decoded-byte length is invented from a text bound. Compatible POSIX numeric constraints use the original exact arithmetic allowance.

SampleResult::meaning() and mandatory result.meaning distinguish final abstract-values, const and admission support from their actual limitations. SampleResult::consulted_interpretations() records actual Byte/POSIX attempts, including discarded branches and failed work. A complete whole witness replaces tentative sample proof while preserving consultation and independent model findings. The shared report contract specifies reference identity, iterator length and optional-detail omission. For a decisive compound const difference, final proof retains the decisive rule and its established enclosing containers, excluding completed sibling meanings. Equal and undetermined pairs preserve complete or partial aggregate support; independent abstract-value support remains separate.

Selection and inputs

Catalogue::check_sample(request) selects exactly one description. A request carries one supplied model-document identity, an effective definition pointer, and one of five kinds: property, data, action_input, action_output, or event_output. The pointer names the Property, sdfData definition, Action, or Event, not an arbitrary nested constraint. For Action and Event selectors the kind selects its sdfInputData or sdfOutputData subdescription. For example, an action_input selector points to /sdfObject/Sensor/sdfAction/reset; its selected description is that effective Action’s sdfInputData. No Event-input or grouping selector exists. A typed effective description handle can construct the equivalent request without pointer reconstruction. The handle is bound to its owning catalogue/result and content identity; cross-owner or stale handles are request errors.

The selected document is the single model root. Other supplied model sources remain lookup candidates, with no position-based precedence or implicit fetching. Context includes the dependencies needed to establish that selected effective description and its constraint meanings. Catalogue source identities remain visible, including acquisition failures. An unrelated failed candidate does not alone obstruct sample admission. An unavailable candidate that could affect a needed contributor or ambiguity does obstruct the affected conclusion. Selecting a known absent definition or absent Action/Event description, the wrong class, an invalid pointer, an unknown root identity, or a nonmodel source as root is a request error. A selection that cannot be established because needed acquisition, decoding, composition, or interpretation is unavailable is a domain result with admission undetermined, rather than guessed absence or an error for an unknown selector.

Sample input is one whole supplied conventional JSON value, with a distinct request-local SourceId and source role sample. A conventional-JSON input owns immutable bytes and acquisition metadata; it must contain one JSON text without trailing second values. Exact original bytes remain available, including after decoding or A002 refusal. A typed Esdieff JSON value has null, Boolean, decoded scalar text, exact-number, array, and map constructors/accessors. Number construction accepts a checked JSON numeric lexeme or an exact checked machine conversion; it never rounds through a float. Map construction rejects duplicate decoded names under A002. Typed data is retained as owned values or immutable sharing and has a conventional JSON projection preserving accepted number lexemes. The projection is not an original source text: its sample locations have pointers, with span:null unless original supplied bytes and their token spans exist. Conventional byte strings and unix-time retain the representations in ADR 0007: Generated SDF and sample JSON; typed JSON is not an alternative binary/time encoding.

Missing sample input is a request error. A supplied JSON null has a value and is checked under ADR 0005: Nullability and presence, including const and choice constraints. No root-value omission or whole-interaction scenario is modeled. Required map entries are evaluated inside the supplied value; absent entries are not populated from default. Property readable/writable/observable and declaration sdfRequired remain model characteristics; choosing a Property sample does not simulate a read/write/notification or impose those capabilities as value constraints.

All model/sample/generated attempts share the 256-attempt and 1 MiB metadata preflight in ADR 0013: Shared workflow and report guarantees. The sample consumes one attempt and the shared acquisition/parsed-node/number/decoding budgets: 4 MiB per source, 32 MiB aggregate, depth 64, 100,000 nodes per source, 500,000 nodes per request, the exact-number token/coefficient/exponent/work caps, and shared checked semantic-work, derived-storage, location, diagnostic, and report limits. Sample acquisition is not an extra unlimited channel. Typed builders precharge nodes, text/key bytes, numeric tokens, and owned storage before copying or traversal. The same sample/effective evaluation shares the 10,000,000 work units and applicable equality/pair/pattern limits; repeated alternatives and nested values are charged. Default selection is at most 8 KiB of decoded JSON Pointer bytes; it is validated without clipping. Physical stack limits are supported bounds, never removed by raising a numeric configuration. A mandatory sample-report reserve includes both selectors, source roles, all nine area counters, admission, outcome, and omissions before acquisition. Presentation omissions preserve admission and aggregate counts; exhausted semantic work leaves affected admission or coverage unfinished.

Admission and conditions

A typed constructor shares one remaining decoding-work allowance across aggregate metadata visits, duplicate-name comparisons, decoded key/text scans, projection copying and decoding. Each traversal is charged before it runs; a new phase or key does not replenish the allowance.

The three conclusions are:

The evaluator records the constraint/interpretation basis and sample/model locations. It does not create a synthetic RFC error solely from missing capability. Invalid JSON or A002 refusal is an input finding with admission undetermined; an invalid needed model parameter is a model finding with affected admission undetermined. Definite independent conditions survive scoped limitations.

Choice alternatives can overlap. A known matching branch is sufficient despite unrelated unknown alternatives when they cannot alter that complete witness. An unknown potentially matching branch blocks rejection when all known branches reject. Per-area successes from different branches cannot be combined into a fabricated witness. Effective inheritance and overrides are established before matching; a shared maximum overridden in one alternative cannot supply a proof against every alternative. Unavailable common/surrounding meaning that could invalidate the witness prevents admission. Known unknown branches irrelevant after a witness do not create unfinished requested units merely because they were not traversed. Their existence and witness basis can be explained without selecting an equality meaning.

Scalar and compound const compare ordinary values under ADR 0015: Bounded value equality in a resolved data context. Thus 10, 10.0 and 1e1 compare equal, escaped text compares after JSON decoding, and composed and combining text remain distinct. Different ordinary JSON kinds compare different without coercion. Arrays compare in order; maps compare decoded key sets and corresponding values without member-order significance. A definite ordinary length, key-set or sibling difference survives unavailable child meaning when the enclosing structure is established. Const contents are data: keys such as sdfRef or type inside a constant do not become vocabulary or reference instructions.

Before each const comparison, the evaluator establishes common meaning for that sample and effective constant across relevant local and enclosing final alternatives. Nested const and uniqueness retain those contexts through established ordinary array and map structure. An absent child description permits ordinary comparison after that structure is established; an unavailable child description leaves the affected comparison unfinished. A successful comparison or branch admission cannot establish an interpretation. Unknown or unavailable meaning blocks the affected equality proof. A conventional text-format branch can be irrelevant when an operand is an ordinary nonnull nontext value and the branch’s text representation domain is independently established; unfamiliar formats, unavailable type meanings and null do not supply that exclusion. A complete branch with no equality obligation can still admit independently of another branch’s unavailable equality. Each explicit const override creates its own obligation; it does not restore a replaced shared constant as a constraint on every branch. Enum retains each authored occurrence as a separate effective text-const alternative.

An established absent type adds no authored type constraint. For an ordinary nonnull number, applicable bounds and multipleOf still run; for ordinary nonnull text, scalar lengths and applicable unfinished pattern work still apply. A Full ordinary array or map with no authored items, properties or required can complete its structural family using the supplied kind, independently of const or uniqueness. Authored child qualities still require established applicable structure. Untyped unavailable count parameters remain unfinished, including beside assessed uniqueness. The evaluator uses the supplied kind without adding an effective type quality. Unknown explicit type, unsupported structural interpretation and unavailable inherited meanings retain their affected limitations. A matching const never bypasses another applicable constraint. Null retains nullable independently, and a nonnull const can exclude null even when nullability otherwise permits it.

Sample admission is independent of the shared disposition. A rejected sample emits at least one sample-domain error for its established violated constraint. Undetermined requested units contribute incompleteness, not a rejection error. Model-domain findings required to establish the selected context retain their original codes and bases. Strict warning policy can produce failed while admission is admitted. A definite rejection alongside an unfinished applicable constraint produces failed, complete:false, and admission rejected. Without blocking errors or strict warnings, unfinished requested work produces undetermined. Detail truncation changes none of these.

No whole-model assessment runs implicitly. result.context identifies selected-view availability and the needed model findings, independently of sample conclusions; it does not certify model validity. An explicitly performed catalogue or selected-model check remains a separate operation/result, reusable internally where source content, configuration, and baseline match. Its unrelated error does not become a sample rejection or a required sample error. Acquisition attempts remain visible in sources, even where their unrelated findings are outside the sample request.

Numeric sample types and bounds use the information-level meanings in RFC 9880 Appendix C.1, including mathematical integrality for tokens such as 10.0. They do not import Appendix A’s CDDL number/uint model-parameter grammar as a blanket sample-number width restriction. ADR 0012: Exact numbers and JSON input policies separately limits claims about formal model-parameter representability: exact access to a count parameter such as 18446744073709551616 does not certify that grammar. The sample result can establish an ordinary mathematical constraint conclusion without certifying the whole model’s grammar. Any actual needed uncertainty about the effective parameter or abstract data meaning leaves that affected sample work undetermined. Neither a failed machine conversion nor unassessed formal model-grammar work alone establishes that a supplied sample is rejected.

Ordinary string and Boolean admission uses the same selection, effective context, input locations and report. Boolean values require no coercion. Text minLength and maxLength are inclusive Unicode scalar counts under RFC 9880 Appendix C.2: "é" and "𝄞" each have length one, while "e\u0301" has length two. No Unicode normalization changes the supplied value. Count parameters retain the exact nonnegative mathematical meanings in ADR 0022: Scalar constraints and characteristic states, including counts larger than machine integers. Scalar traversal precharges decoded UTF-8 bytes against the work remaining after selected composition and checking, and both comparisons share the numeric allowance remaining after input parsing. Exhaustion leaves the affected area undetermined.

Length and pattern parameters are needed for an ordinary nonnull string. A different base type or a supplied null does not perform text matching; null still retains every other applicable obligation, including const and choice work. Documentary default never supplies a value. Supported Unicode ECMAScript matching follows the pattern contract. An unavailable matching capability or exhausted allowance keeps that work undetermined, while an independent established length violation can still reject the string. Needed format, abstract or alternative uncertainty prevents affected text proofs rather than being ignored. Unavailable Unicode scalar decoding remains a sample-input limitation even when no length bound is present.

Ordinary map samples

An established ordinary type: "object" follows RFC 9880 Appendix C.5. properties constrains described entries that are present; other entries remain unconstrained. required names mandatory entries, including names with no property description. Its whole nonempty list must have decoded names before any absence proof. Duplicate required names request presence once. Whole sample member identities must be available, including keys after a matching member. Unknown enclosing map meaning prevents structural admission or missing-entry rejection.

A present described entry uses its final composed description, real sample value and applicable scalar, null, map, array and alternative rules. An absent optional entry requests no child reference, invalid scalar parameter, array or format work. Neither default nor declaration sdfRequired supplies an entry. Unavailable equality context, unsupported format meanings and declared Extension features retain scoped limitations. Undeclared extension vocabulary does not, as described under Undeclared extension vocabulary. An independent missing entry or known sibling violation still supplies a rejection while another needed child remains unfinished.

Every map alternative needs a complete whole-map witness. A child’s known choice admission returns to its containing map, and different branches cannot supply different required entries for one fabricated witness. Raw branch roots settle before their final whole-quality overrides and present child references. Parameter finding storage, semantic work, derived storage and one numeric remainder remain shared across all pairs without refunds or resets.

For an Action input selected at /sdfAction/configure, an object requiring mode rejects {} at the sample map pointer "", with its real original span and the model’s /sdfAction/configure/sdfInputData/required/0 relation. A present null satisfies presence and is checked separately against the child’s nullable meaning. Required absence at a nested map uses that existing parent location; no missing-child location is invented. A wrong present scalar uses its own entry pointer and token span, or span:null for a typed projection. A declaration or payload key named sdfRequiredInputData remains an ordinary name; assessed legacy vocabulary retains the A001 restructuring guidance.

Ordinary array samples

An established ordinary type: "array" follows RFC 9880 Appendix C.4. minItems and maxItems are inclusive exact nonnegative mathematical counts, including authored counts larger than machine integers. Every actual element requests its established items description. Supported direct items include ordinary numeric, string, Boolean and object descriptions, and choices whose Full alternatives may contain nested arrays. Full object properties can also contain arrays. Wider direct-item array types, nested items, defaults, nullable meanings and reference imports retain the limits in ADR 0024: Effective alternatives and nullable characteristics. Unsupported needed item meaning prevents admission; an independent known count or child violation can still reject.

An empty array requests no element description. It can satisfy established outer array constraints even when the deferred item subtree has opaque meaning. This does not establish that subtree’s meaning or capability. A supplied element, including an empty inner array, requests its own actual item context and cannot use the outer array’s empty-case conclusion. For uniqueItems: true, one established equal pair disproves uniqueness, even beside other unknown pairs; proving uniqueness requires every necessary pair to differ. Empty and singleton arrays compare no pairs. False or absent uniqueness imposes no comparison obligation. Item checks and other constraints remain independent.

Const and uniqueness share the request-wide equality-pair ceiling, original structural/string/key work, numeric remainder and derived allocation allowance. The default pair ceiling is 100,000; Limits::equality_pairs can reduce it to a nonzero value. Every actual scalar or compound const and uniqueness pair spends one pair before comparison across nested values and alternatives. Work or representation exhaustion leaves the affected conclusion undetermined without refunding prior work. A duplicate condition uses the second element as primary, retains its real effective/source relation and appends the first element as related sample evidence. A const mismatch uses the real decisive leaf or structural root. Typed inputs have null spans; rendered pointer omissions preserve these conclusions.

Each element’s choice returns to the containing array conjunction. Different elements may satisfy different item alternatives, while a whole-array choice requires one complete whole-array witness. Shared item roots and final alternatives retain one identity and their real origins; present optional interests accumulate across elements. Absent optional entries never erase an earlier present interest. Common model conditions and newly needed parameter families are checked once per final description, including malformed conditions, without resetting work or finding storage. Inclusive count failures use sample.count with arguments.constraint naming minItems or maxItems, located at the actual array with its authored bound as related model evidence.

Combined compound descriptions

Compound descriptions combine these same rules recursively. Map entries and array elements can request named choices whose Full alternatives describe maps, arrays, ordinary scalars or supported abstract values. Shared qualities apply until an alternative explicitly replaces the whole quality. A complete alternative must establish the entire selected value; successful checks from separate alternatives cannot be assembled into one witness. Const and uniqueness still require a common established equality meaning under ADR 0015: Bounded value equality in a resolved data context, independently of which branch admits a value. Inherited object properties under an explicit array alternative can keep that common equality meaning unavailable. Nullable, required presence and documentary default remain separate.

The supported combination includes exact numeric fields, required map entries, contextual compound const and uniqueness, Unicode ECMAScript patterns, all six base string formats (date-time, date, time, uri, uri-reference, uuid), and the byte-string and POSIX conventions. These meanings use their existing representation contracts at every needed nested location. An inherited field can keep its donor minimum while a consumer overrides its maximum; findings identify the actual sample leaf and the effective constraint, with the applicable original contribution related. A missing required entry is located at its existing parent.

One known admitting compound alternative supplies a witness. A potentially admitting unresolved alternative prevents rejection by the other branches, while an independently violated enclosing or sibling constraint can still reject with unfinished coverage visible. Restricted Direct donor meaning stays unavailable when copied into a Full alternative until an explicit establishing override. Decoded-byte lengths, incompatible or unknown equality interpretations, declared Extension features and matching capabilities retain their existing scoped limits. All values, alternatives, equality pairs and matches share the original finite request allowances. Combining implemented capabilities does not establish whole-model conformance or general satisfiability.

Undeclared extension vocabulary

Undeclared extension vocabulary does not stop sample checking, following ADR 0037: Undeclared extension vocabulary. That is a qualified or unqualified Quality Name outside base SDF, such as acme:note, sdfProtocolMap or a misspelled minimun, in a document that declares no Extension feature. A selected Property, sdfData, Action input or output, or Event output description carrying it admits or rejects a sample on its base description, as if that quality were absent. The same holds for nested object properties, Direct items and choice alternatives. Const and uniqueItems comparisons use that base meaning too, so 7.0 matches const: 7 beside acme:note. Recorded extension vocabulary at a position its registration names, such as oma:id on a Property under ADR 0038: Recorded extension vocabulary, is set aside the same way. Sample checking does not check its value.

The extension’s own meaning stays unsupported, and a model check still reports the vocabulary’s notice or unfamiliar-name warning. A base quality outside its role, such as a wider Direct item quality, is not extension vocabulary and keeps its scoped limitation. So do unknown values of base qualities, such as format: "email", documents that declare an Extension feature and descriptions composed from them.

baseline.interpretations lists undeclared-extensions-ignorable/1 whenever a sample context set aside undeclared extension vocabulary and the sample conclusion went on from the base description. A Sample report omits it when the vocabulary lies outside every description the sample reached, for example on the enclosing Object or in an absent optional entry, and when a base quality outside its role or an unknown base value already stops the affected conclusion. Recorded extension vocabulary that a sample context set aside names it too, because a Sample report never consults recorded registry evidence. SampleResult::consulted_interpretations() still records only Byte and POSIX attempts.

Immutable requested coverage

FullBaseline separately establishes known byte-string and Unix-time model interpretations as M026 and M027. It supplies no synthetic value, decodes no bytes and assigns no time coordinate. The canonical unpadded base64url and exact POSIX numeric conventions above continue to govern actual constants and selected values. Model interpretation does not establish decoded-byte length, negative POSIX denotation, leap-instant representation or general satisfiability.

The default and first supported profile is esdieff.sample/1, requesting all applicable base-SDF admission obligations in the following nine areas. Membership is independent of implementation. Each area contributes exactly one status to the requested aggregate; applicable recursive constraints, values, alternatives, and limitations are summarized within that area and may have bounded per-location detail. A whole-model RFC inventory is not this inventory.

An area’s assessed status means its requested obligations have been established satisfied or violated; findings are compatible with assessed. not_applicable requires established irrelevance for the selected sample context, not an absent implementation. unassessed means needed applicable work has not run; undetermined means work was attempted but a needed conclusion remains unavailable. All nine statuses sum to nine. Requested completeness requires each area assessed or not applicable, even if an independent rejection already exists. If the context is unavailable, dependent membership cannot be declared not applicable. A profile may gain implemented checks under the same identity; new membership, standards meaning, or guards require a new profile identity. New profile identities are explicit caller choices, not silent aliases for whatever is currently supported.

Ordinary scalar descriptions, including scalar const, supported Unicode patterns, enum and nested choices with complete effective witnesses, can complete this profile when their other areas are established inapplicable. Needed unavailable equality, pattern, compound or abstract meaning keeps requested work unfinished. Pattern outcomes and their finite matching controls follow the pattern contract. Later implementations fill the existing obligations rather than silently replacing their meaning. Broader model-baseline coverage retains the shared partial/undetermined state and inventory availability; a sample pass supplies no model conformance claim.

Versioned report extension

Sample finding and rejection-witness bases identify the producing work: numeric type and arithmetic conclusions use RFC 9880 Appendix C.1, ordinary string type and scalar length conclusions use Appendix C.2, Boolean type conclusions use Appendix C.3, const uses Appendix C, alternatives use Section 4.7.2, and rejection of null by nullable:false uses Section 4.7 Table 4. Relevant established coverage carries the same type basis; combined type/null coverage cites Section 4.7 and Appendix C. Admission witnesses retain Appendix C and identify the complete alternative when applicable. Tentative branch failures become sample errors only when every potentially admitting alternative has been excluded; independently needed model conditions retain their own counts and bases. Context establishment uses sample-establishment, and applicable unimplemented work uses sample-implementation, including unfinished pattern work alongside an independent length rejection. Needed sample decoding limitations retain their original cause, domain and available location; optional omission does not remove them from diagnostic counts. Unrelated Model parser leaves do not become requested sample findings.

A const finding and its rejection witness cite Appendix C even when contextual equality uses Byte or POSIX meaning inside a scalar or compound value. The const coverage row summarizes established equality work and can instead carry the specialized Byte or POSIX interpretation when it is the sole abstract interpretation in the final const proof. Complete meaning.const and meaning.admission references retain that interpretation and any necessary container support alongside Appendix C. Consulted interpretations record actual use, including work that does not survive as final proof. These fields serve distinct purposes; a single finding or coverage basis does not replace the complete meaning references.

The sample report is schema:"esdieff.report", version:"1.1", operation:"sample". Check and inspect contracts, fields, units, values, null meanings, and exit rules remain unchanged. A reader supporting only check/inspect rejects the new operation before interpreting its payload. Existing shared objects apply unless specified below; these tables define the sample operation’s additional required fields and closed tags. IDs are compact nonzero u32; Count/Bytes retain shared checked-u32/nonnegative-byte meanings. All strings and details consume shared metadata/report budgets. Missing required fields are invalid reports.

SampleSource metadata uses the shared Source object. A typed input has acquisition supplied, conventional retained bytes if a bounded projection is retained, and no fabricated byte spans. Sample spans for byte input refer to its original immutable bytes. Pointer rendering omissions keep the source ID and available spans. The sample pointer root is ""; malformed/partially decoded nested input can have pointer null and span when available. Effective description locations use the selector root and the selected description path, including input/output suffixes; they claim no source span. Related source locations explain inherited and overriding constraints when available.

Witness arrays and diagnostic/coverage rows are optional-detail collections bounded by the shared limits; omitted witnesses do not change retained admission or counts. Omissions explicitly identify their report paths and reasons. Human output states selected kind, sample identity, admission, shared disposition/completeness, scope/coverage, and relevant sample/model locations. It derives these from the same result as JSON. No human wording or array order becomes the stable interface.

Adding optional sample fields/codes within 1.x follows the shared rules. Changing required field types, these null/tag/unit meanings, or admission semantics requires a major report version or a newly explicit operation/profile contract as appropriate. Rust builders/accessors keep private fields and extensible result enums; wire DTOs do not serialize internal enum layouts.

Civil date-time, date and time use the civil-time contract. Their denotation fills sample-abstract-values/1 without changing the nine-area inventory. Ordinary string lengths remain independent. Two established Gregorian dates compare equal for the same calendar date and different for different dates, independently of JSON escape spelling. Compatible established date-times compare by UTC instant, excluding offset annotations and preserving exact fractions and distinct inserted seconds. Date-free time retains equality for identical denoting representations and unavailable comparison for differing representations. Invalid or unavailable denotation supplies no temporal equality or difference. Unknown or incompatible meanings across alternatives remain explicit.

Command acquisition

The proposed command is esdieff sample --document MODEL --kind KIND --pointer POINTER --sample SAMPLE [--strict-warnings] [--format human|json] MODEL_INPUT.... MODEL must match one explicit model input; KIND is one of the five selector tags. SAMPLE is an explicit file path or -; model inputs also allow - for one stdin document. Only one total stdin use is permitted across model and sample acquisition, so a sample - excludes a model -. Duplicate stdin, missing sample/model/kind/pointer, unknown model roots, wrong known selector roles, invalid options, and malformed pointer are invocation errors with exit2. No default sample is invented and no default document is selected by input position.

The command registers all acquisition attempts before reading and applies shared limits. The sample gets its own identity even if its path equals a model path; roles remain separate, with bounded role-qualified opaque caller keys. Non-UTF-8 paths retain exact filesystem identity with safe bounded labels. File/stdin acquisition or decoding failures are structured domain results. They never make a definitely missing sample silently null. Exactly one chosen report and trailing newline goes to stdout; stderr contains invocation/host-output failures. Shared exits apply: 0 passed, 1 failed including strict warnings or established sample rejection, 2 invocation/configuration error, 3 undetermined without blocking errors, 4 report/host-output failure. Failed plus incomplete uses1 and retains complete:false.

Concrete observations

Temperature describes number, nullable false, minimum -50 and maximum150. Sensor.temperature inherits Temperature. Device.ambient overrides its Property maximum to100; its changed Event output retains maximum150. For the owned byte sample 101:

• Property selector /sdfThing/Device/sdfObject/ambient/sdfProperty/temperature gives rejection at sample source root pointer "", span [0,3]; its effective /maximum is100, with source explanation at the Device override. Its initial numeric work can be complete if all other applicable sample obligations are assessed/not applicable.
• Event-output selector /sdfThing/Device/sdfObject/ambient/sdfEvent/changed selects its /sdfOutputData; the same sample admits under maximum150. Source Temperature and Sensor bytes and source maximum150 remain unchanged. The Event result is independent of the rejected Property result.
• A model warning relevant to the usable Event description with strict warnings yields admission admitted, disposition failed, complete true, warnings1/errors0. This is not a sample constraint rejection.
• An independent violated established Property maximum plus an unsupported equality-changing const yields admission rejected, disposition failed, complete false, errors1 and one unfinished const area, only when that unsupported meaning cannot change the numeric rejection proof. If it could alter the applicable numeric meaning, this fixture would be undetermined instead.
• A previously performed catalogue check can fail on an unrelated unused source while the selected sample still admits. The attempted source remains visible, but that separate check’s error is not counted as a sample condition. Unavailable needed composition gives context unavailable/partial and sample undetermined; dependent areas are not reported inapplicable.
• A complete ordinary choice alternative admitting 101 establishes admission despite another unresolved potentially matching alternative. If the known alternative rejects and the other may match, admission is undetermined. An unresolved surrounding meaning that could invalidate the known witness also gives undetermined.

These observations guide implementation at the public domain boundary. Exact byte spans are supplied by parsing original inputs; expected effective outcomes in a contract exercise are supplied acceptance fixtures and are not evidence that a resolver or sample validator has executed.

Civil date and time sample contract

This specifies the conventional representation and established temporal meaning portion of the selected-sample operation, under ADR 0018: Civil date and time sample conventions. It applies after the selected effective data description, applicable format, conventional JSON value and decoded scalar text have been established. It does not select an alternative, acquire model data, infer a date from neighboring sample fields, or certify the whole model. RFC 9880 Appendix C.2 supplies abstract data meanings; RFC 3339 Section 5.6 names their conventional productions.

FullBaseline can establish the known date, date-time and time model interpretations without a supplied value. This M049 observation neither invokes the temporal evaluator nor consults leap-second knowledge. Actual constants and selected values still require their own established denotation under the rules below. An unavailable exceptional slot can leave constant meaning unfinished while the named model interpretation remains established.

Conventional values and calendar

Every numeric component uses ASCII digits and the displayed fixed widths. Source year is 0000..9999; month 01..12; day 01 through its Gregorian month limit; clock hour 00..23 and minute 00..59. February has 29 days when the year is divisible by 4, except a century not divisible by 400. The same rule applies to source year 0000, as the published RFC 3339 Section 2 and Appendix C arithmetic specifies. Gregorian arithmetic is used across the four-digit range without a historical local-calendar cutover. Offset subtraction may use an adjacent internal year outside that textual range; that intermediate result alone does not reject an otherwise permitted source date.

Seconds are 00..59 ordinarily, with 60 and a missing 59 governed below. A fraction is a dot followed by one or more ASCII digits. All digits remain exact; there is no fixed decimal scale, float conversion, nanosecond rounding or truncation. A long fraction may exhaust supported work, which gives undetermined rather than an invalid-format finding. Conventional source bytes and their JSON escape spelling remain retained separately from decoded text and temporal projection.

Z/z and signed offsets +HH:MM or -HH:MM are admitted, including both zero signs and offset hours through 23 with minutes through 59. The UTC coordinate is local clock minus offset, following RFC 3339 Section 4.2; a real-world timezone database is unnecessary. -00:00 denotes known UTC time while the local offset is unknown. Under the recorded RFC 3339 Section 4.3 baseline, Z/z and +00:00 carry the preferred-UTC-reference annotation. Preserve these annotations even though all three spellings use the same zero coordinate for leap-slot checking.

RFC 9557 Section 2 changes the Z annotation, while leaving UTC coordinate and this admission unchanged. That update is not implicitly adopted; a later deliberate baseline update must state it. Bracketed IXDTF timezone/calendar suffixes are not selected representations here. Neither an absent offset nor a timezone name supplies the RFC 3339 full-time offset. The date format has no offset suffix.

T/t is the selected date-time separator. The RFC 3339 note permits applications to choose another separator, so a space-separated timestamp fails this selected conventional representation without a claim that its abstract instant cannot exist or that every application forbids that syntax. ISO 8601 week dates, ordinal dates, expanded years, compact forms, comma fractions, hour 24, reduced precision and offset seconds are likewise outside these selected named productions. Malformed JSON, A002 duplicate-key refusal and unsupported escaped scalar decoding remain their existing input/context outcomes; temporal checking does not reclassify them as invalid dates. A supplied nonstring is not coerced. Null and conflicting effective type are evaluated under the existing nullable/type/choice contract rather than an unconditional nonstring format rejection.

The metadata quality modified has its own RFC 9880 Appendix A grammar allowing full-date or Z-terminated date-time, described by RFC 9880 Section 3.1. It does not make these sample formats UTC-only. A model metadata timestamp is not a default date or timezone for a sample.

Exceptional seconds and recorded knowledge

RFC 3339 Section 5.7 makes seconds conditional on leap adjustments and shifts the insertion point by the supplied offset. UTC 23:59 on the final UTC day of a month is the possible adjustment minute. June and December are historical and preferred opportunities, not a silently hardcoded universal sample grammar. Negative adjustments remove second 59; positive adjustments insert second 60. Fractions refer to the represented second and never roll it into the following minute.

For a date-time, derive the UTC minute and UTC date by subtracting the offset, including a change of day, month or year. The source date can be the following local day, such as 2017-01-01T05:44:60+05:45, whose leap slot is 2016-12-31 UTC.

Seconds 00..58 remain available independently of adjustment knowledge. A syntactic second greater than 60 rejects. An impossible insertion slot rejects even outside the recorded knowledge interval because the independent slot rule is established.

Initial deliberately recorded leap knowledge is IERS Bulletin C72, issued 2026-07-06, together with its Leap_Second.dat transition table and Bulletin C72 text. The inclusive knowledge interval is 1972-01-01 through 2026-12-31 UTC. Each listed +1 transition identifies an insertion on the preceding date; the initial 1972-01-01 offset is not an insertion event. No negative adjustment is recorded there. The bulletin explicitly establishes no insertion at the end of December 2026. The snapshot’s 2027-06-28 expiry is not a no-leap promise through that date. Before the interval and after it, needed adjustment facts remain unavailable. Processing never fetches a replacement implicitly. Record the snapshot’s byte identity in the standards knowledge basis; adopting new knowledge changes that basis deliberately, following ADR 0002: Recorded standards baseline.

The recorded knowledge identity is iers-bulletin-c72/2026-07-06. Snapshot SHA256 identities are 6cb6f5d4b819f2e568e25db4b0b26d89dedf031fdffb18bc94d40f4e94e268d7 for Leap_Second.dat and 310e172eadacacca3adf92cb9bd646fcc0d6320e35e996a106d2644ede3b52f0 for Bulletin C72. Its 27 positive insertion dates are:

1972-06-30  1972-12-31  1973-12-31  1974-12-31  1975-12-31
1976-12-31  1977-12-31  1978-12-31  1979-12-31  1981-06-30
1982-06-30  1983-06-30  1985-06-30  1987-12-31  1989-12-31
1990-12-31  1992-06-30  1993-06-30  1994-06-30  1995-12-31
1997-06-30  1998-12-31  2005-12-31  2008-12-31  2012-06-30
2015-06-30  2016-12-31

A date-free time has no UTC date by design. Ordinary seconds 00..59 are admitted as date-free clock coordinates without asserting occurrence on every calendar day. A possible inserted-second label 60 at UTC 23:59 is undetermined because its eligible leap-label interpretation is unestablished. This is not a missing required date field and does not establish invalidity. Second 60 at any other offset-adjusted UTC minute rejects. This is an explicitly selected conservative interpretation of RFC 3339 full-time as imported by SDF. An existential some-valid-date interpretation could admit eligible 60, but the RFC does not select that quantifier, so that alternative is deliberately deferred. The evaluator does not use a host date, a model metadata date or an unstated sample sibling. Date-free comparison, normalization modulo a day and recurring-schedule semantics are not established here.

Sample results, locations and finite work

The temporal obligation belongs to sample-abstract-values/1, keeping the immutable nine-area esdieff.sample/1 inventory. It is assessed when temporal admission or an independent representation/calendar/slot rejection is established. An unavailable needed interpretation or capability leaves that area undetermined. Applicable decoded JSON, scalar text length and patterns, const equality, nullable/type and alternatives keep their own areas. An established ordinary JSON string type does not complete abstract-values by itself. One complete admitting alternative can supply a witness; rejection still needs proof covering every potentially admitting alternative.

A rejected temporal form contributes an error in the sample domain with primary sample location and a related effective format constraint location, with source contributor locations when available. Its basis distinguishes selected representation convention from an established calendar/slot requirement and recorded leap knowledge. The space-convention condition must not assert an RFC-invalid abstract date-time. Undetermined leap or work contributes incompleteness with its reason and affected locations, not an invented rejection error. The versioned condition catalogue below preserves these distinctions.

For a supplied root JSON string, sample pointer is "" and its half-open span is the complete original JSON token, including quotes. Nested values use their actual sample pointer and original byte span. Effective location is the selected effective description’s applicable /format path; it is not a fabricated source location or byte span. Typed JSON inputs have a pointer and span:null unless genuine original bytes exist. Inherited or overridden format source locations are related explanations, not replacements for the sample identity. Presentation omissions preserve available identity/span and aggregate conclusions.

The implemented condition codes and bases are:

Each specialized incomplete condition identifies sample-abstract-values/1. It replaces the generic coverage detail for that same cause, including when optional detail is omitted. Independent const, alternative or other unavailable meanings retain their own details; each requested area is still counted once. Incomplete conditions never supply rejection witnesses or sample errors.

baseline.interpretations records ADR0018-selected-representation when the convention is consumed. baseline.temporal_knowledge carries the C72 identity, interval and both snapshot digests only after an actual adjustment query, including outside-interval queries and discarded branches. Dates, ordinary seconds 00..58, second 59 away from a boundary, date-free time and independently impossible insertion slots do not consult C72. Established null and wrong-kind constraints exclude temporal grammar and record neither use flag.

The evaluator precharges 2 * decoded_length + 256 original semantic-work units for the borrowed representation scan, bounded calendar/offset arithmetic and at most 27 recorded insertion comparisons. Both const operands and every potentially relevant branch use that same remaining request allowance. No additional temporal counter, refill, owned fraction or normalized temporal value exists. Metadata modified keeps its separate Z-only wrapper and existing precharge.

These projections assume exactly one effective full description with type:"string", nullable:false, one temporal format and no additional constraints. The four assessed areas are context, type/null, text/Boolean and abstract-values; the five remaining areas are established not applicable. The work-limit projection assumes only the temporal consumer’s budget is exhausted after the independent areas complete. They are expected contract observations, not executed product reports. A definite independent constraint rejection plus unavailable temporal meaning gives admission rejected, failed, complete false only when the unknown temporal meaning cannot change that proof. Strict warnings can fail disposition with admitted temporal/sample meaning. Detail truncation never changes admission, counters or aggregate errors.

All source, decoded text, parsed nodes, recursive alternatives, semantic work, location and report limits remain shared under ADR 0012: Exact numbers and JSON input policies, ADR 0013: Shared workflow and report guarantees and ADR 0016: Selected samples with explicit admission and coverage. Charge before scanning, copying or building exact fractions, offset projections and locations. Format capability is bounded independently of JSON source acquisition; raising one cap removes no other bound. No additional unbounded precision, live lookup, timezone database or calendar dependency is selected.

Representative observations and remaining scope

Under a common established civil format, null equals null and differs from an established nonnull civil value in either operand order. Malformed or uninterpreted nonnull values leave comparison undetermined. Null/null consults neither the nonnull representation convention nor leap knowledge; mixed pairs record only the nonnull interpretation and knowledge actually used. Null admission remains independent, including when nullable:false excludes it. Two nonnull dates with established Gregorian denotation compare by calendar date. The same date is equal and different dates differ, including day, month and year boundaries across the four-digit source range. The fixed-width convention permits validated decoded text to supply this comparison without a normalized retained value. JSON escape spelling does not matter; identical invalid dates do not establish equality and differing invalid dates do not establish a calendar disagreement.

Two nonnull date-times with established denotation compare by UTC instant under ADR 0018. Subtract the numeric offset with Gregorian day/year rollover, keeping UTC dates outside the source-year edges representable internally. Compare exact fractional digits after removing trailing zeros; absent and all-zero fractions are equal. An inserted second keeps its own slot, distinct from second 59 and the following day’s second 00. Offset annotations, letter case and JSON escapes do not distinguish instants. The RFC 3339 example 1996-12-19T16:39:57-08:00 equals 1996-12-20T00:39:57Z; .1 equals .100; an established Z value equals its +00:00 and -00:00 spellings. Invalid forms and absent needed adjustment knowledge prevent either an equality or a difference conclusion. Differing nonnull date-free time representations retain unavailable comparison meaning.

Temporal denotation alone does not establish sample admission when other constraints remain unfinished. ADR 0015: Bounded value equality in a resolved data context applies separately: invalid or unresolved strings do not denote a temporal value merely because their representations match. Gregorian-date and dated date-time equality supply constant checks, supported compound comparisons, uniqueness and declared-value consistency through that one contract. Actual date comparison records the selected convention without consulting leap knowledge; dated date-time comparison records only actual slot consultations. Model-only comparator capability uses no operands and records no representation consultation. Nonnull date-free time comparison beyond established identical representations, epoch conversion, ordering, duration arithmetic, physical clock correctness, recurring schedules and additional representations remain outside this scope.

URI and UUID sample contract

This contract follows ADR 0019: URI, URI-reference and UUID sample conventions. It extends the selected-sample operation contract without changing the nine-area esdieff.sample/1 inventory, report version 1.1, selection, ownership or disposition rules. The adopted scope distinguishes representation, applicable URI scheme meaning, opaque UUID values and context-dependent equality.

FullBaseline establishes known uri, uri-reference and uuid model interpretations without supplying a value or invoking a representation check. This M049 observation asserts no scheme admission, target identity, constant denotation or comparator capability. Constants still need their actual contextual denotation; an unsupported URI scheme can leave M043 unfinished while the named model interpretation is established. Model selector recognition alone does not record consultation of the sample facts listed below.

Meanings and conventional inputs

Primary definitions are RFC 9880 Appendix C.2, RFC 3986 Sections 3 and 4 and RFC 9562 Section 4. Conventional text is assessed after JSON decoding; alternate JSON escape spellings do not themselves change its content. This adds no alternative binary protocol representation.

URI generic syntax and scheme-specific semantics are separate. A generic representation conclusion names its syntax basis; abstract-format admission also needs an established compatible meaning, including applicable scheme requirements. HTTP(S) requires authority form and a nonempty host under RFC 9110 Sections 4.2.1 and 4.2.2. For example, https:device and https:// match generic grammar but fail those scheme requirements. An established scheme failure supplies rejection on its own cited basis, even when generic syntax succeeds. A finite HTTP/HTTPS identity-syntax capability supports ordinary cases without requiring an exhaustive scheme registry or communication behavior. Unknown schemes do not trigger an invented rejection allowlist. An unavailable needed scheme interpretation stays undetermined, and its abstract-values area remains unfinished. Relative references can be admitted as expressions without target resolution; needed base or inherited scheme meaning is separate. No network request, name lookup, existence check or retrieval is performed.

URI text retains supplied characters and percent encodings. Reject malformed percent escapes, spaces, backslashes, literal non-ASCII characters and invalid generic components; do not trim, repair, percent-decode before parsing or silently convert IRIs. Percent-encoded non-ASCII octets can satisfy generic grammar without establishing a particular scheme’s character encoding. IP literals and authority/path delimiters require their actual RFC 3986 grammar. Arbitrary bracket content is not an IP literal. Numeric port syntax does not by itself certify a protocol’s usable port range. Registered-name grammar is broader than DNS labels. A first relative path segment cannot contain a colon, while ./this:that can be a relative reference.

UUID text decodes to bytes in displayed/text order. Upper, lower and mixed-case hex name the same bytes. Esdieff interprets the base format as an opaque 128-bit value without a version/variant allowlist. This does not assert that every finer layout is defined or interoperable, certify uniqueness or randomness, validate timestamps, introspect application fields, or prove a generation algorithm. Nil and Max are ordinary representable sentinel UUID values, independent of JSON null. Requested layout-specific meaning must assess applicable variant requirements from RFC 9562 Section 4.1 and corresponding version/layout requirements. Unavailable needed layout meaning stays undetermined, even when the opaque representation is available. Alternate UUID formats are outside this conventional channel; describe that input failure with its convention basis instead of calling an abstract UUID universally invalid.

Equality and additional constraints

Use ADR 0015: Bounded value equality in a resolved data context for const and uniqueItems. In a common established UUID context, both bare representations must first denote UUID values; compare their 16 bytes. Case differences can establish equality, and a differing byte establishes difference. Invalid strings, unavailable interpretation, incompatible choice meanings and exhausted work stay undetermined, including identical text. A comparison result does not establish admission under every other constraint. Supplied output text is preserved; byte comparison does not mandate rewriting it.

No URI normalization or equivalence comparator is adopted. Differing case, percent spelling, paths or relative forms remain undetermined for value equality, even where a future purpose-specific comparator could prove equality. Identical valid representations establish equality only when their common compatible deterministic interpretation is known. If equality asks whether relative references identify the same target, an explicit applicable base is needed; it is never inferred from an SDF namespace, source path or acquisition URI. Expression admission requires no target resolution. A separately requested JSON representation comparison can report text differences without claiming different abstract identifiers.

Unicode scalar length and pattern constraints still apply to the conventional decoded text when their established meaning is needed. Constraints inherited through references or choices retain their effective meaning and overrides. A complete matching alternative can admit; unrelated unfinished alternatives cannot invalidate its established witness. Potentially matching unknown alternatives prevent unjustified rejection. These rules do not add URI-specific composition, a general scheme registry or a new interpretation of restricted item vocabulary.

Findings, locations and coverage

In an established common compatible context, null equals null and differs from an established nonnull URI, URI-reference expression or UUID. An invalid or uninterpreted nonnull operand leaves comparison undetermined. Null/null does not consume nonnull representation facts; mixed pairs retain the facts actually consulted for the nonnull value. Equality is independent of null admission. Full UUID comparator capability supports known absent, true and false nullability without operands, while restricted or unavailable meaning remains unfinished. These cases do not supply general nonnull URI equivalence or target identity.

A definitely invalid conventional representation rejects only under an established applicable format/context. Record a sample-domain constraint finding and the conventional/RFC generic grammar basis actually used. An unknown critical feature, unknown equality-changing extension, unavailable needed scheme/base interpretation or exhausted semantic work produces an affected undetermined conclusion instead. Invalid JSON or unusable decoding remains a context/input finding with sample admission undetermined. Unsupported decoded scalar content is not relabeled malformed URI text. Independent definite findings remain available only when unavailable meaning cannot change their proof.

Format denotation and needed external knowledge belong to sample-abstract-values/1; text lengths and patterns belong to sample-text-boolean/1; const and array uniqueness retain their own areas. Inapplicability requires an established reason. Full sample admission still requires every applicable area. A format success alone never claims sample completeness or model conformance. A definite representation rejection can coexist with unfinished independent pattern work: admission rejected, disposition failed and complete:false only when that unavailable work cannot change the representation rejection.

For data selection /sdfData/Uri, a format finding refers to effective location /sdfData/Uri/format in the selected document and to sample source pointer "". For supplied JSON "../device", the sample token span is [0,11] in its immutable source bytes. Related source locations identify the declared or inherited format where available. Typed sample input has pointer "" and span:null unless original supplied bytes exist. Const cases additionally identify effective /const; array uniqueness identifies the two item sample pointers. Nested map entries or array items use their actual sample pointers and selected effective description suffixes. No source span is invented for effective content.

Finite acquisition, decoded text, structural/pair, number, semantic work, derived storage, location and report limits remain those of ADR 0012: Exact numbers and JSON input policies, ADR 0013: Shared workflow and report guarantees, ADR 0015: Bounded value equality in a resolved data context and ADR 0016: Selected samples with explicit admission and coverage. Precharge representation scanning, decoding, comparison and repeated choice work before traversal or allocation. Avoid percent-decoded copies, target resolution and implicit fetching. Budget exhaustion leaves affected work undetermined. Pointer/report presentation omissions preserve established conclusions and aggregate counts separately. A parser’s own tighter capability must be disclosed, not treated as an RFC rejection. Algorithm improvements may change implementation, never these semantic boundaries.

Examples

Each ordinary case uses an available sdfData description with type: "string", nullable: false, the stated format and no extra constraints. HTTP(S) cases use the supported authority and host requirements under RFC 9110. Other needed scheme meaning remains unavailable.

With an established matching UUID const whose hex case differs, the equality obligation succeeds; a one-byte difference supplies a const mismatch. uniqueItems:true in established UUID item meaning rejects mixed-case duplicate values. Identical malformed UUID operands give equality undetermined rather than a false equal proof; definite sample format rejection can still be independent. uri const operands differing by host case, or reference operands "device" and "./device", give equality undetermined under this contract. Identical valid relative-reference expressions can satisfy a constant under the same expression meaning. Target identity would additionally need an applicable base; Esdieff performs no target resolution. An independent matching choice retains an admission witness; unresolved surrounding meaning can prevent it.

Human, typed and JSON results agree on these conclusions, bases and locations under the selected-sample contract. Format findings use sample.uri_representation, sample.http_identity, sample.uuid_representation or sample.resource_meaning_unavailable for their distinct reasons. Required work exhaustion uses operation.limit.

Consulted format facts

Report::format_knowledge(id) returns a borrowed FormatKnowledgeView with static id, rfc, sections and scope text. Sample records the facts actually used by its request, including visited alternatives and constant comparisons. A later unfinished branch or omitted optional detail preserves earlier consultations. The six identities are:

An unknown identity is absent. Non-Sample operations omit format_knowledge and return absent through this getter. Sample’s baseline field is an array of the consulted four-field records; an admitted consultation owner with no used facts produces []. Initial inability to establish that owner produces null and known getter identities are unavailable. Late work exhaustion retains the array of facts already consulted. These are request observations, not a capability inventory or evidence of external resource acquisition.

UUID findings identify uuid-bare-json/1 or uuid-opaque-value/1 as the selected interpretation. Their actual use also appears in baseline.interpretations. URI generic grammar and HTTP(S) identity findings retain separate RFC bases. Human output presents the same consulted facts and interpretations as JSON.

Generated values

Esdieff generates sample values for a selected effective data description, so firmware and app teams can test their code against a model without writing payloads by hand. Each Generated value aims at one Generation target, such as a minimum, a value just below it or a wrong type, and Sample-value checking settles it against the description it was generated for. Its admission, not its target, says whether the description admits it. The rules follow ADR 0041: Generated values settled by Sample-value checking, and the terms Generated value, Generation target, Representative value, Sample-value checking, Effective data description and Nullable come from the domain language.

#![allow(unused)]
fn main() {
use esdieff::{Admission, Catalogue, GenerationRequest, SampleKind, SourceInput};

let catalogue = Catalogue::take_inputs(vec![SourceInput::supplied(
    "model",
    br#"{"sdfProperty":{"level":{"type":"integer","minimum":10}}}"#,
)])?;
let request = GenerationRequest::new(catalogue.source_id("model").unwrap())
    .select(SampleKind::Property, "/sdfProperty/level");
let result = catalogue.generate(request)?;
let level = result.descriptions().next().unwrap();
let below = level.values().find(|value| value.target() == "below_minimum").unwrap();
assert_eq!((below.to_json(), below.admission()), ("9", Admission::Rejected));
Ok::<(), &'static str>(())
}

The generation contract identity is esdieff.generation/1. It binds the Generation targets, their order and the rules that build their values, so a release that changes any of them gets a new identity and a report keeps its meaning. Generation is deterministic, with no randomness or seed, so the same model and request give the same values in the same order.

Command line

esdieff generate --document MODEL [--kind KIND --pointer POINTER] [--format human|json|jsonl] MODEL_INPUT... generates values for descriptions of the model document MODEL, which must match one explicit MODEL_INPUT. Inputs are file paths, and - reads one document from standard input. --kind and --pointer select one description as esdieff sample does, with KIND one of property, data, action_input, action_output and event_output, and they come together or not at all. Without them every affordance description of the document is selected, as described under Selection. From the repository root, generate values for the rich thermostat model:

cargo run -- generate --document examples/thermostat-check/rich.sdf.json examples/thermostat-check/rich.sdf.json

--format human gives the human report, json the JSON report and jsonl the JSON Lines Trace entries. The shared color controls style the human report. Generation reports no model findings, so it exits 0 when generation completed for every selected description and 3 otherwise, including when any value stays undetermined. A missing --document, --kind without --pointer or the reverse, an unknown kind, format or option, a selector that selects nothing, a document that is not a supplied input and a second - are invocation errors that exit 2 with empty stdout. A report that cannot be written exits 4. The CLI contract states the shared rules.

Library operation

Catalogue::generate(request) performs one generation. GenerationRequest::new(document) selects every affordance description of a model document, and select(kind, pointer) narrows it to the one description that Sample selector selects. An unknown or non-model document, a malformed or oversized pointer, a selector whose definition is absent or has another kind, and a report allowance too small for the mandatory report envelope are request errors.

GenerationResult owns every value and borrows the Catalogue for its report. descriptions() yields each selected GeneratedDescription in selection order, and descriptions_omitted() counts selected descriptions beyond the ceiling or left out because their details did not fit the report byte limit. count(admission) counts the kept values Sample-value checking settled with that admission. selection_complete() is false when a grouping or affordance of the document could not be read, so some descriptions may be missing. complete() is true when the selection is complete, no description was omitted and every description is complete. disposition() is passed then and undetermined otherwise, never failed. document() and selector() echo the request. to_json(), to_json_lines(), to_human() and to_human_with_style(style) render the outputs below.

Each GeneratedDescription has its Sample selector kind() and pointer(), its state(), its kept values() in target order and values_omitted(), the distinct values left out beyond the ceiling, because they did not fit the report byte limit or because their Trace entry would be longer than a trace line. Its state is:

• Complete when every applicable target was generated and every kept value is admitted or rejected.
• Partial when generation ran out of the description’s allowance, values were omitted beyond the ceiling, for the report byte limit or for the trace line limit, or Sample-value checking left a value undetermined, including one whose check ran out of its own allowance.
• Unavailable when the description’s effective meaning could not be established, so no value was generated.

Each GeneratedValue has its target(), its to_json() text, in which each number keeps the spelling it was generated with, its admission() and its codes(), the distinct condition codes behind a rejection, at most 8, such as sample.bound.

Selection

With a selector, generation covers the one description that Sample-value checking would select for that kind and pointer, including an sdfData definition. Without one, it covers every Property, Action sdfInputData, Action sdfOutputData and Event sdfOutputData reachable from the document’s top-level groupings and affordances, including nested groupings. They are taken in document order, and an Action’s input comes before its output. sdfData definitions are generated only when selected explicitly, and Event input and groupings have no description to generate. A description whose effective meaning is unavailable is listed as unavailable, and a grouping, Action or Event that cannot be read leaves the selection partial.

Generation targets

Each description’s targets come in four groups, in this order. A target that does not apply produces no value, and so does one whose value would exceed the value capabilities, such as a string longer than a document may be or a value nested deeper than the depth limit. pattern has no target in this contract, since Esdieff does not synthesize strings that match a pattern.

The first group is the Representative values of ADR 0039, with their number, string, map and array rules:

The second group holds boundary values, which lie on an edge of the admitted range:

The third group holds values just outside the admitted range:

Array items

The items of an array value are copies of the first Representative value of its items description, or null without one. When the array requires unique items and holds two or more, its items are distinct instead: the Representative values of items in order, then further values that continue from the first of them. Numbers continue one unit at a time, strings vary their last character through a to z and then longer suffixes, and a boolean continues with the other boolean. Without an items description the items are the numbers from 0. When no such sequence has enough distinct items, such as for an items description with only a const, the target gives no value.

Nested targets

The fourth group holds the targets of each properties entry, in order, and then of items. Each is generated by these same rules for that nested description, including its own nested targets, and its value is placed where the nested description stands:

• inside the map its entry belongs to, beside the first Representative value of every other entry that map requires, so the enclosing constraints still apply
• among the items of its array, repeated as often as the array’s minItems requires and at least once, or beside other distinct items when the array requires unique items

A nested target is named after the path to it, as <entry>.<target> or items.<target>, so a minimum inside the level entry of settings data is level.minimum, and one inside the items of an array inside the readings entry is readings.items.minimum. With {"type":"object","required":["mode","level"],"properties":{"mode":{"enum":["off","heat"]},"level":{"type":"integer","minimum":5}}}, level.minimum is {"level":5,"mode":"off"} and level.below_minimum is {"level":4,"mode":"off"}. A nested value is often the same value as an earlier one, such as the map of Representative values, and is then kept once under the duplicate rules, which favor the nested boundary target. With {"type":"array","minItems":2,"uniqueItems":true,"items":{"type":"integer","minimum":3,"maximum":9}}, items.maximum is [9,3]. A Direct items description has no Nullable characteristic, so items never has a null target. Nested descriptions are followed only while their values can nest within the depth limit, and a value whose enclosing value cannot be built, such as one whose sibling entry has no Representative value, is not generated.

A unit follows the rules of the numeric bounds witnesses: it is 1 where the coefficient digit limit allows, and otherwise one of the bound’s last significant digit. So a maximum of 20.50 gives an above_maximum of 20.6, and a maximum of 1e600 gives 2e600, since adding 1 would need more digits than the limit allows. A count that is not an exact nonnegative integer within the value capabilities, and a step that is not a positive exact number, give no target.

Settlement and duplicates

Sample-value checking settles every kept value against the selected description, as it would a value supplied for that Property, sdfData definition, input or output. A target name never overrides admission. A below_minimum value that another constraint also rejects is just rejected, and a type value that a pattern rejects is rejected too. A value the checker cannot settle, such as one beside an unsupported pattern or one for map or array content without a type, is undetermined and leaves its description partial.

Each value is settled as soon as it is kept, so the admissions already settled stand when later generation runs out of the description’s allowance. Two targets can produce the same value, and it is then kept once. Values are the same when their JSON texts are, apart from the order of the entries in any map, so {"level":5,"mode":"off"} and {"mode":"off","level":5} are one value, while numbers compare by their exact spelling, so 10 and 1e1 are two. A duplicate is kept under the target with the highest precedence, so that a label names the constraint a value probes:

1. Boundary and outside targets, every target of the second and third groups apart from all_entries, rank above the Representative-value targets const, enum, default, type, alternative and null, and above all_entries.
2. Within each of these two classes, a nested target, <entry>.<target> or items.<target>, ranks above a top-level one.
3. Between targets of equal rank, the first in contract order keeps the value.

The value stands at the place of the target that keeps it and shows that target’s text. So a typed description with a minimum of 10 lists 10 as its minimum rather than as its type, a const of 3 beside a minimum of 3 lists 3 as the minimum, a const of 0 beside a type of integer lists 0 as the const, and an array of at least two unique integer items with a minimum of 0 lists [0,1] as items.minimum rather than as min_items. In a map that requires a mode enum starting with "off" and a level with a minimum of 5, the type map {"mode":"off","level":5}, the first mode.enum value and the level.minimum value are one value, listed once as level.minimum with the text {"level":5,"mode":"off"}.

Bounds

One description keeps at most 64 distinct values, and one request selects at most 1024 descriptions. Distinct values beyond the first ceiling are counted in values_omitted and leave their description partial. Descriptions beyond the second are counted in descriptions_omitted, have no values and leave the operation undetermined. These two ceilings keep a request finite under ADR 0009: Bounded processing and reporting and ADR 0013: Shared workflow and report guarantees.

Each piece of work has an allowance of its own, with the work, allocation, numeric and equality limits that one esdieff sample request receives against the same Catalogue, as ADR 0041: Generated values settled by Sample-value checking states. Composing the document and finding its descriptions spend the request’s allowance. Building one description’s values spends that description’s allowance, and running out of it stops generation of that description and leaves it partial. Each kept value is checked with an allowance of its own, and a check that runs out leaves that value undetermined and its description partial. So one heavy description or value never leaves the others unsettled.

Checking a value against an enum or a choice costs work roughly linear in its number of alternatives, so even an enum of thousands of values settles within one check’s allowance. Values whose checks are costlier, such as long unique arrays, can still run out of that allowance and stay undetermined.

The values a request keeps always fit the report byte limit, Limits::report_bytes. After the Catalogue’s mandatory report reserve and the generate envelope’s own, every description is charged the bytes its details need before its values are generated, and every kept value is charged the bytes its largest rendering needs, as a JSON report record, a JSON Lines Trace entry or a human report line, before it is kept. The charge assumes the longest target name the description can give, so when a target of higher precedence later takes the value under the duplicate rules, its name always fits. A description whose details do not fit is left out, counted in descriptions_omitted with a report_limit record, and leaves the operation undetermined. A distinct value that does not fit is left out, counted in values_omitted with a byte_limit record, and leaves its description partial. So every output format fits the limit, whatever the model asks for, such as many strings with a maxLength of millions. A value whose Trace entry would be longer than 1 MiB, the longest line a Recorded trace accepts, is left out the same way, also charged as if under the longest target name, so every JSON Lines entry replays through esdieff trace.

Report 1.5

The JSON report is schema:"esdieff.report", version:"1.5", operation:"generate", extending the shared report contract with these fields:

baseline.interpretations names the value interpretations that the checks relied on, as model reports name them. Every source stays in sources. Description details are written in selection order within the report byte limit, and any that do not fit are counted, never silently dropped. The human report shows the disposition, the value counts, then each description with its state and one line per value with its admission, its target padded to at most 40 characters, its value and its rejection codes. It is written one description at a time and gives the JSON report instead as soon as it would not fit the report byte limit.

JSON Lines

--format jsonl and to_json_lines() write one Trace entry per admitted or rejected value, each a JSON map on its own line ending in LF: {"kind":KIND,"pointer":POINTER,"value":VALUE,"expected":ADMISSION,"label":TARGET}, with the description’s Sample selector, the generated value, its settled admission as expected and its target as label. A target longer than 256 bytes, which only a long nested entry name gives, is left out as a label rather than shortened. Undetermined values are left out, and the exit code still reports them, as it does values left out for the report byte limit or the trace line limit. A run without settled values writes nothing at all.

The output is a Recorded trace, so esdieff trace replays it as regression vectors, as the trace contract describes. Replayed against the same model, every entry passes, because each expectation is the admission Sample-value checking settled. Replayed against a later revision, exactly the entries whose admission changed fail, such as a former maximum that a narrowed maximum now rejects. The output is byte-identical for the same model and request, so the vectors can be kept under version control.

Recorded traces

Esdieff checks a Recorded trace, a JSON Lines file of Trace entries, against one model document, so device QA can find every logged value that a model rejects in one run. Each entry names a Sample selector, carries a value and may carry an Expected admission and a label. The document is composed once, each distinct selector is resolved once, and every entry is checked on its own, so one bad line never stops the run. The rules follow ADR 0042: Recorded traces with independent entries, and the terms Recorded trace, Trace entry, Expected admission, Sample selector and Sample-value checking come from the domain language.

#![allow(unused)]
fn main() {
use esdieff::{Admission, Catalogue, TraceOutcome, SourceInput, TraceRequest};

let catalogue = Catalogue::take_inputs(vec![SourceInput::supplied(
    "model",
    br#"{"sdfProperty":{"level":{"type":"integer","maximum":10}}}"#,
)])?;
let trace = concat!(
    r#"{"kind":"property","pointer":"/sdfProperty/level","value":7}"#, "\n",
    r#"{"kind":"property","pointer":"/sdfProperty/level","value":11,"label":"spike"}"#, "\n",
);
let request = TraceRequest::new(catalogue.source_id("model").unwrap(), trace.as_bytes());
let result = catalogue.check_trace(request)?;
let spike = result.entries().next().unwrap();
assert_eq!((spike.line(), spike.label()), (2, Some("spike")));
assert_eq!(spike.admission(), Some(Admission::Rejected));
assert_eq!(result.count(TraceOutcome::Passed), 1);
Ok::<(), &'static str>(())
}

The trace contract identity is esdieff.trace/1. It binds the Trace entry format and the rules that settle each entry’s outcome, so a release that changes either gets a new identity. A Recorded trace adds no sequence meaning, timing or protocol binding. Line order is presentation only, and the checks add nothing to any Model requirement inventory.

Command line

esdieff trace --document MODEL --trace FILE [--format human|json] MODEL_INPUT... checks the Recorded trace FILE against the model document MODEL, which must match one explicit MODEL_INPUT. Inputs are file paths, and - reads one document from standard input. FILE is a file path, or - for standard input, and standard input may be used only once across the model inputs and the trace. From the repository root, check a trace of thermostat readings:

cargo run -- trace --document examples/thermostat-check/rich.sdf.json --trace readings.jsonl examples/thermostat-check/rich.sdf.json

--format human gives the human report and json the JSON report. The shared color controls style the human report. The run exits 1 when any entry failed, otherwise 3 when any entry is undetermined, and otherwise 0, as check does. A missing --document or --trace, an unknown format or option, a document that is not a supplied input, a second -, a trace file that is missing, unreadable or larger than 64 MiB, a line over 1 MiB and more than 100,000 entries are invocation errors that exit 2 with empty stdout. The trace is read before any model input. A report that cannot be written exits 4. The CLI contract states the shared rules.

Library operation

Catalogue::check_trace(request) checks one Recorded trace. TraceRequest::new(document, trace) names the model document and the trace bytes. The trace becomes a source with role sample and the key trace, numbered after the Catalogue’s sources. key(key) gives it another caller key, label(label) a display label, such as its path, and omit_label() records that its label was left out, as for a path too long to show. An unknown or non-model document, a trace over TraceRequest::FILE_BYTES, a line over 1 MiB, more than 100,000 entries, a key over 256 bytes or equal to a Catalogue key, a label over 512 bytes, a Catalogue that already holds the most source attempts and a report allowance too small for the mandatory report envelope are request errors. A malformed entry is never a request error.

TraceResult owns every listed entry and borrows the Catalogue for its report. count(outcome) counts the entries that settled with that TraceOutcome, and admissions(admission) counts the checked entries that Sample-value checking settled with that admission. entries() yields the failed and undetermined entries in line order while they fit the report byte limit, and entries_omitted() counts those that did not. Passing entries are counted, not listed. disposition() is failed for any failed entry, otherwise undetermined for any undetermined entry, otherwise passed. document() echoes the request and trace_source() gives the trace source’s identity in the report. to_json(), to_human() and to_human_with_style(style) render the outputs below.

Each TraceEntry has its line(), counting from 1, its label(), its selector() when it names a valid kind and a pointer string of at most 8192 bytes, whether or not that selects anything, its expected() admission, its admission() when its value was checked, its outcome() and its conditions(), at most eight, with conditions_omitted() counting the rest. Each TraceCondition has its code(), severity(), message(), its pointer() within the entry’s JSON map, such as /value/mode, and its span(), the byte range in the trace file.

Trace entries

The trace is split into lines at each LF, and a CR before an LF is ignored. The last line may omit its LF, and an empty last line is no entry, so a file holding one empty line has no entries. Every other line, including an empty one, is one Trace entry, and lines are numbered from 1 in file order.

Each entry is one JSON map with these members:

Each line is decoded on its own under the ordinary JSON input policies of ADR 0012: Exact numbers and JSON input policies. Numbers keep their exact values, so 9007199254740993 stays distinct from 9007199254740992, and a repeated member name anywhere in the line is refused, including inside the value. Each line has the decoding allowances one Sample source would have in the same Catalogue, so its depth, node count and number sizes have the shared limits.

Entry outcomes

Each entry settles on its own, in this order:

1. A line that is not valid JSON, or repeats a member name, fails with its json.syntax or input.duplicate_name condition. A line that is not UTF-8 or exceeds a decoding limit cannot be read and is undetermined.
2. A line that is not a JSON map fails with trace.entry. An unknown member fails with trace.unknown_member, a missing required member with trace.missing_member and a member with an invalid value with trace.invalid_member. Every such member is reported.
3. A selector that selects nothing fails with trace.unselectable. That covers a malformed or oversized pointer, a definition that does not exist, and a definition of another kind, such as an Event pointer with kind property. A description whose meaning cannot be established, such as one behind an unavailable reference, leaves the admission undetermined with trace.unavailable.
4. Otherwise Sample-value checking settles the value against the selected description. The entry passes when the value is admitted and nothing else was expected, or when its definite admission equals expected. It fails when the value is rejected and nothing was expected, or when its definite admission differs from expected, which adds a trace.expected condition. An undetermined admission leaves the entry undetermined whatever was expected.

The conditions of a failed or undetermined entry explain its outcome: the decoding issue, the member conditions, trace.expected, and the conditions behind a rejection or an undetermined admission, such as sample.bound, in that order.

Composition and allowances

The selected document is composed once, on the request’s own allowance, as esdieff generate composes it. Each distinct selector, a kind and a pointer, is resolved once against that composition, and later entries reuse its resolution. Each entry is checked with an allowance of its own, with the work, allocation, numeric and equality limits that one esdieff sample request receives against the same Catalogue, as ADR 0042: Recorded traces with independent entries states. A check that runs out of its allowance leaves only that entry undetermined, with an operation.limit condition.

Bounds

A Recorded trace holds at most 64 MiB, 100,000 entries and 1 MiB per line, apart from its line ending, under ADR 0009: Bounded processing and reporting. Going beyond any of them is a request error before any entry is checked, so a run never reports a partial file.

The report fits the report byte limit, Limits::report_bytes. After the Catalogue’s mandatory report reserve and the trace envelope’s own, each failed or undetermined entry is charged the bytes of its larger rendering, as a JSON report record or human report lines, in line order. The first entry that does not fit, and every failed or undetermined entry after it, is counted in entries_omitted with a report_limit record and is not listed. Counts, the outcome and the disposition always cover every entry.

Report 1.5

The JSON report is schema:"esdieff.report", version:"1.5", operation:"trace", extending the shared report contract with these fields:

baseline.interpretations names the value interpretations that the checks relied on, as model reports name them. Every source stays in sources. diagnostics.items is empty, since every condition belongs to an entry. The human report shows the disposition, the entry and admission counts, then each listed entry with its line, selector and outcome, its label, its admission and Expected admission, and one line per condition with its severity, code, pointer and byte range. It gives the JSON report instead if it would not fit the report byte limit.

Replaying Generated values

esdieff generate --format jsonl writes one Trace entry per admitted or rejected Generated value, with its settled admission as expected and its Generation target as label, as the generation contract describes. So its output is a Recorded trace. Checked against the same model, every entry passes. Checked against a later revision, exactly the entries whose admission changed fail, so last release’s values become regression vectors for the next.

cargo run -- generate --document examples/thermostat-check/rich.sdf.json --format jsonl examples/thermostat-check/rich.sdf.json > vectors.jsonl
cargo run -- trace --document examples/thermostat-check/rich.sdf.json --trace vectors.jsonl examples/thermostat-check/rich.sdf.json

Generation leaves undetermined values out, so a replay never expects an admission that checking did not establish. It also leaves out any value whose Trace entry would be longer than the 1 MiB line limit, so every line it writes replays. The selectors keep their pointers, so a revision that renames or removes a definition fails its entries with trace.unselectable.

Composed sdfThing authoring contract

This contract specializes ADR 0013: Shared workflow and report guarantees for Model authoring under ADR 0017: Reference-preserving sdfThing authoring. Domain terms come from the domain language. SDF composition follows RFC 9880 Sections 4.4 and 6; namespace identity follows Sections 3.2 and 4.2. Patch deletion follows RFC 7396 Section 2. Resource, output and API limits below are toolkit capabilities.

Request and library ownership

A private-field authoring builder accepts an owned Catalogue, one generated-source key and optional bounded label, a new sdfThing Given Name, an explicit namespace map with an optional chosen default prefix, and a nonempty list of sdfObject declarations. Each declaration has an exact new Given Name, a supplied source ID plus decoded pointer selecting an sdfObject, an explicit output namespace prefix for that sdfObject’s established global namespace, an owned JSON map Composition patch, and an explicit declaration-requiredness flag. The sdfThing can also have caller-supplied common qualities and information-block metadata. New generation creates one document; existing-document editing, nested sdfThing recipes and flattened export are later capabilities.

The sdfObject selector never selects by display label, filename or input order. Unknown IDs, malformed/overlong pointers, a present non-sdfObject selector, repeated declaration names, duplicate namespace prefixes with different bindings, duplicate generated keys and conflicting builder settings are request errors. A selector whose source/definition is unavailable produces scoped domain incompleteness; an established missing pointer is a request error. Prefixes and Given Names compare exactly after JSON decoding, contain no colon and receive no case folding or Unicode normalization. The toolkit bounds each newly supplied Given Name or prefix to 1,024 UTF-8 bytes, requires a nonempty prefix for its authored CURIE capability, permits at most 256 sdfObject declarations and 256 namespace bindings, and bounds each selector to the shared 8 KiB semantic-pointer cap before copying. These are new-request capabilities rather than RFC restrictions on source names; larger source names remain accessible.

The required flag authors an entry in the new sdfThing’s sdfRequired. Under RFC 9880 Section 4.5, an abbreviated Referenceable name excludes # and :; Given Names can contain #. When the declaration’s Given Name is a valid abbreviated name, emit that exact decoded name without JSON Pointer escaping. Otherwise, preserve the Given Name and emit a correctly encoded same-document SDF pointer reference to the newly authored declaration. Form decoded RFC 6901 tokens first, escaping token ~ and / as ~0 and ~1, then UTF-8/percent-encode the URI-fragment representation. An internal # becomes %23 in that fragment, not a second fragment delimiter. Decoded source/effective pointers retain the literal #. Inherited internal sdfRequired content is unchanged unless explicitly refined; this generation rule does not rewrite copied absolute pointers, which relocate during composition under ADR 0036: Copied reference relocation.

The explicit output prefix must already map to the selected sdfObject’s established global namespace URI. Authoring constructs the CURIE from that prefix and the selected definition’s namespace-rooted pointer; it does not copy a source prefix spelling. The target must be unambiguous in the supplied/generated catalogue. A requested generated namespace/global name that collides with an existing contributor is refused with author.identity_collision; no coalescing or precedence applies. Multiple bindings to the same URI are allowed; one prefix cannot denote two URIs. A missing source default namespace leaves reuse by this operation unsupported with author.local_only_object, rather than assigning a new source namespace or diagnosing an RFC violation. Namespace URI spelling and declared source identities remain unchanged; no network retrieval occurs.

The patch is SDF-authored JSON, not a generic mutable graph. It excludes an authored top-level sdfRef, since the builder owns that reference. sdfThing common-quality input excludes structural declaration groups and sdfRef; the builder owns declaration names and sdfRequired. Bad JSON and duplicate decoded names use the shared input/acceptance policies. Patch null retains its Merge Patch deletion meaning; it is not coerced into an explicit model value. Nested introduced references remain authored in the generated document’s explicit namespace context, while copied source references retain any interpretation limitation. Ordinary supported composition does not wait for interpretations that are irrelevant to its selected definitions.

The operation owns accepted request metadata, patch content and raw source bytes. Views borrow its owned result. Callers can retrieve a generated document’s bounded JSON bytes, the generated Catalogue, typed source/effective views and explanations using the same check/inspect operations as supplied models. Every generated source has a new compact SourceId and unique caller key; it does not reuse a supplied identity. Supplied raw bytes, names, number tokens and metadata remain unchanged. Authored declaration identities belong to the new sdfThing, while available origins point to selected reusable sources and request patches. This does not promise complete provenance history.

Fidelity, checking and failures

Generation state is complete, partial or unavailable. complete establishes a complete readable JSON document whose requested assembly is finished; partial means some requested assembly is unfinished even when a structurally complete candidate JSON exists. A candidate’s content_complete only describes its bytes. A fidelity state established or undetermined is independent: established requires all requested known-semantic/name/number and permitted opaque-structure preservation established, with no unresolved context meaning. A proven loss is an error and cannot yield faithful success. Preserving unknown extension JSON alone cannot establish preservation of its meaning after containment or reference context changes. Independent known observations and retained opaque content remain inspectable with affected locations and reasons.

Generated known JSON values preserve meaning; unchanged accepted numbers preserve their raw lexemes, including lexical exponent-boundary tokens. New patch numbers preserve their accepted request tokens. Mathematical number fidelity does not establish formal normative CDDL number admission, which remains a separately assessed requirement under ADR 0012: Exact numbers and JSON input policies. Names preserve decoded scalar values, without promising original escape spelling. Output is readable UTF-8 JSON with indentation and a trailing newline. Source whitespace, member order, original escape spelling and byte-for-byte regenerated documents are outside the guarantee. The operation introduces no computed numeric normalization that would cross the accepted output limits.

Checking is explicitly not_requested or requested with initial-v1 or full-baseline and the shared strict-warning policy. A requested check applies to selected generated-document roots and needed dependencies; every supplied input remains visible. It uses the same immutable inventory and baseline as ordinary checking. Its completion/findings remain separate from generation/fidelity. Checking can fail while generated content is available, or be incomplete while fidelity is established. Requested broader omissions cannot become a pass. No sample checker or every specialized validator is a prerequisite for established authoring. No general proof that a patch is a Restrictive refinement is promised.

Overall author disposition is failed for established errors or selected strict warnings, otherwise undetermined if generation, fidelity or requested checking is unfinished, otherwise passed. complete means that this one requested authoring operation, including fidelity and requested checking, finished; independent errors can coexist with complete work. Top-level author incomplete_checks counts this one unfinished authoring unit at most once. The separately represented checking outcome counts its own assessment units, never added to author coverage counters. Detail omission alone changes neither completion nor fidelity.

Sources unavailable, global contributor ambiguity, effective cycles, Boolean or short-name sdfRef without processing meaning, unknown critical features and semantic work/output limits are conditions with their existing basis or the author’s operational reason. author.local_only_object is an operational unsupported capability; author.identity_collision is an authoring assembly conflict, not an invented RFC rule; author.fidelity_unknown names affected unknown context; author.generation_limit is operational unfinished work. Unknown request selectors and invalid output configurations are request errors before generation. Sources and useful candidate views survive failures.

Limits and locations

All model, sample and generated attempts share the 256-attempt ceiling. Reserving one generated identity reduces available supplied attempts to 255. All caller metadata, including request keys, new names, prefixes, URI strings and repeated source selectors, consumes the shared 1 MiB pre-copy budget and worst-escaping mandatory-report reserve. Source key/label/URI/version/digest bounds remain unchanged. New semantic identities are never clipped. The accepted plan is owned only after preflight.

The CLI author plan is one bounded JSON request text, at most 4 MiB, with the shared decoding, duplicate-name, depth and numeric policies. Its parsed nodes and storage share the request’s 500,000-node/64 MiB parsed allocation budgets. It has no SDF source role or namespace identity. Builder requests have the same new-name, patch-depth/node/byte and metadata charges. Raw plan bytes are additional bounded request storage, not an unbounded metadata escape.

Raw generated bytes share the 4 MiB/document and 32 MiB catalogue ceilings with supplied content. Before appending emitted bytes, the writer checks emitted UTF-8 bytes, including escaping, indentation and newline, against remaining output/input and derived-allocation budgets. Generated representation shares 250,000 effective nodes/64 MiB derived allocation, ancestry and 10,000,000 work units with composition and requested checking. Already charged immutable content can be shared, but traversal still charges work. No phase resets the 2,000,000 numeric units or report/location limits. Request configurations cannot disable finite caps. Exhaustion yields explicit operational incompleteness; a partially built buffer is never a completed generated SDF document or ordinary CLI output.

Source and effective locations retain the shared meanings. Author-request locations add a distinct kind:"author_request", request key, decoded pointer and optional original-plan byte span. A typed builder has a pointer into its logical request shape and a null span because no textual offsets exist. A CLI span belongs to the retained plan text, never a generated source. A generated-source span belongs to its emitted candidate bytes. For a refined maximum, the effective location names the generated root, with related locations in the original sdfObject and /objects/0/refinement/sdfProperty/temperature/maximum of the author request. A deletion can identify an absent effective quality. Pointer/detail truncation keeps compact identity and explicit omission reasons; it does not invent a source span.

Author report JSON 1.1

The author operation extends the shared supported wire contract in minor version 1.1 with a new tag. Check/inspect readers continue rejecting this unknown operation before reading its payload; existing 1.0 tags, units, fields and null meanings do not change. The following additions apply only to operation:"author". Count, Bytes, SourceId, Outcome, Scope, Coverage, Basis and diagnostic omission types retain the shared bounds and meanings. There is no mandatory embedded generated SDF payload in the report.

Rust result enums use stable accessors/private fields with future-compatible variants. Existing check/inspect readers are not required to understand author-request locations. A known operation’s meanings cannot silently change within report 1.x; breaking fields/tags/units require a major version. The author DTO is independent of parser, graph and Rust serialization layout.

CLI and destinations

The command is 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.... Repeat the two-argument --source KEY PATH option for each explicit supplied model path; keys use the shared bounded unique caller-key contract. Paths supply candidates, not declaration roles. PLAN is an explicit path or -, distinct from SDF inputs. At most one input/plan uses stdin. --document-output is required; report defaults to stdout. Each DEST is an explicit file or -. Document and report cannot both use stdout or name the same filesystem target. No directory discovery, parent-directory creation, source mutation or implicit writes occur.

The JSON plan contains key, generated_key, optional generated_label, thing_name, namespace map, optional default_namespace, optional info and thing_qualities maps, and objects array. Each object contains name, source (the exact supplied KEY, solely for source selection), pointer, prefix, refinement map and required boolean. CLI acquisition associates each key with its explicit raw filesystem path, then translates selectors to the same library request. This supports non-UTF-8 paths without placing them in JSON or deriving identity from labels. Plan source selectors must exactly select one supplied key; file aliases under distinct keys remain distinct contributors and never silently coalesce. Duplicate plan members are refused. New names/namespaces are deliberate request data, not inferred filenames.

Before generation, the adapter validates destinations and source aliases. The plan path is a protected input alongside every supplied model path. An existing output requires its corresponding replacement flag and a regular, non-symlink file; the flag does not authorize an input alias. A replacement option for stdout is a configuration error. Existing destination identities are compared to input identities and each other, including hard links and resolved parent-directory aliases; source overlap is refused. Absent paths use resolved parent identity plus exact basename to detect aliases. File commits recheck identity/collision policy and use create-without-replacement or explicit replacement of the validated destination. Unexpected changes cause a host failure rather than overwriting a newly appeared path. No portability claim of preventing every adversarial filesystem race is made; stronger platform primitives are separate implementation choices.

Only generation complete, fidelity established and a passed requested check permit ordinary document delivery. When checking is not requested, established generation/fidelity permits delivery. Failed or undetermined authoring emits its report and exits 1 or 3 with no generated document write. Library candidates remain available for explicit inspection; this first CLI has no flag that presents an uncertain candidate as ordinary output. Domain failures do not erase source attempts. Invocation/configuration errors exit 2; host acquisition/output failure follows the shared distinctions, including reportable input acquisition conditions versus exit 4 when an output cannot be emitted. Strict warnings can prevent document delivery without changing semantic fidelity.

For files, output is staged under a bounded temporary file in the existing destination directory and committed only after successful generation and policy checks; abandoned staging is cleaned up. Each file commit is atomic where the platform supports it, without a two-file transaction or stdout rollback guarantee. A permitted generated document is delivered before emitting the passed CLI report. The report’s domain outcome does not itself assert host delivery; successful process status establishes delivery of both requested outputs. If the report later fails, exit 4 and stderr identify any document already delivered. A stdout document may be partially emitted on host failure and cannot be withdrawn; exit 4/stderr make the failure explicit. Reports go to their separate destination with a trailing newline and equivalent human/JSON conclusions. No report prose is mixed into document stdout.

Ordinary acceptance fixture

The reusable source contributes Sensor / indoor in https://example.com/esdieff/capabilities, with inline temperature Property data: type number, nullable false, minimum -50, maximum 150, multipleOf 0.10, a maxLength of 18446744073709551616 that FullBaseline reports outside the CDDL uint domain, unit Cel, writable false; an inline Action input/output and Event output contain no references. It also declares sdfRequired:["temperature"] and a source description. An additional inline reusable Switch sdfObject provides a Boolean enabled Property in the same document. The reusable source remains byte-identical.

The request chooses sdfThing Room / Monitor, declarations ambient / sensor and switch, explicit reuse binding to the source namespace and product default namespace https://example.com/esdieff/products. The temperature refinement deletes the sdfObject description with null and overrides maximum with the accepted token 1e2; the source maximum remains 150 and Event-output maximum remains 150. ambient / sensor is required, switch optional. Generated sdfRef uses reuse:#/sdfObject/Sensor%20~1%20indoor, the URI-fragment spelling of the pointer whose decoded token is Sensor / indoor. The effective maximum is mathematically 100 with raw patch lexeme 1e2; minimum -50, step 0.10, nullable false and writable false are inherited. The generated effective path is /sdfThing/Room ~1 Monitor/sdfObject/ambient ~1 sensor/sdfProperty/temperature/maximum.

A second supplied acceptance variant names the required declaration ambient#sensor and selects the reusable sdfObject Sensor# / indoor. The decoded source selector is /sdfObject/Sensor# ~1 indoor; its generated CURIE is reuse:#/sdfObject/Sensor%23%20~1%20indoor. The new sdfThing’s sdfRequired entry is #/sdfThing/Room%20~1%20Monitor/sdfObject/ambient%23sensor, not the invalid abbreviation ambient#sensor. The decoded effective declaration pointer is /sdfThing/Room ~1 Monitor/sdfObject/ambient#sensor. Inherited sdfRequired:["temperature"] remains exact. The slash/space control ambient / sensor remains a valid exact abbreviated name, without ~1 or percent encoding in that abbreviated entry. These are supplied, unexecuted semantic acceptance expectations, not evidence of a current emitter defect. Copied absolute pointers relocate under ADR 0036: Copied reference relocation without being rewritten.

Acceptance checks the generated catalogue with explicit generated roots and inspects the effective Property and required declarations. Comparison uses these independently worked semantic observations and exact values, not whitespace/key order. A permitted optional opaque quality remains structurally retained but leaves affected fidelity undetermined when its new containment meaning is unknown. A copied Boolean or short-name sdfRef, which has no processing meaning, likewise leaves only affected composition/fidelity incomplete. A generated global-name collision, a duplicate declaration name, a 256-supplied-plus-generated attempt request, a too-small generated-byte budget and conflicting CLI destinations have explicit failure expectations. These are contract acceptance obligations; a supplied expected fixture is not evidence that product composition has executed.

Using the authoring operation

The library accepts explicit source selection and retains the complete result for inspection:

#![allow(unused)]
fn main() {
use esdieff::{Assessment, AuthorObject, AuthorRequest, AuthorResult, Catalogue, SourceId};

fn product(catalogue: Catalogue, reusable: SourceId) -> Result<AuthorResult, &'static str> {
    AuthorRequest::new(catalogue, "room-recipe", "room-product", "Room")?
        .namespace("reuse", "https://example.com/capabilities")?
        .namespace("product", "https://example.com/products")?
        .default_namespace("product")?
        .object(AuthorObject::new("sensor", reusable, "/sdfObject/Sensor", "reuse", true)?)?
        .checking(Assessment::Initial)?
        .author()
}
}

AuthorResult::outcome() describes the entire requested operation. generation() and fidelity() retain the independent assembly and Authoring fidelity conclusions. generated_document() returns available candidate bytes even when requested checking fails or remains unfinished. catalogue() supplies immutable source and effective inspection through the ordinary operations. Only document_deliverable() permits the CLI’s ordinary generated-document output.

For the CLI, save an explicit recipe such as:

{
  "key": "room-recipe",
  "generated_key": "room-product",
  "thing_name": "Room",
  "namespace": {
    "reuse": "https://example.com/capabilities",
    "product": "https://example.com/products"
  },
  "default_namespace": "product",
  "objects": [
    {
      "name": "sensor",
      "source": "reusable",
      "pointer": "/sdfObject/Sensor",
      "prefix": "reuse",
      "refinement": {},
      "required": true
    }
  ]
}

Run esdieff author --plan recipe.json --source reusable capabilities.sdf.json --document-output room.sdf.json --check initial-v1 --format json. The report goes to stdout. Use --report-output report.json for a separate report file, or use --document-output - --report-output report.json to send only the generated document to stdout. --replace-document and --replace-report separately authorize replacing an existing regular output, while protected input aliases remain refused.

Destination identity uses retained filesystem handles, including parent handles for absent paths, with checks before individual commits. Identity or hard-link support unavailable on a host produces an explicit failure. Conservatively reported filesystem identity collisions can refuse output, including wider filesystem identifier limits on Windows. This operation does not claim universal race prevention or a transaction across document and report delivery.

Refinements and explanations

Refinements are owned JSON maps. JsonBuilder retains exact accepted number lexemes; a null in an actual Composition patch deletes an inherited quality:

#![allow(unused)]
fn main() {
use esdieff::{Assessment, AuthorObject, AuthorRequest, AuthorResult, Catalogue, JsonBuilder, SourceId};

fn refined_product(catalogue: Catalogue, reusable: SourceId) -> Result<AuthorResult, &'static str> {
    let json = JsonBuilder::new();
    let patch = json.map(vec![
        ("description", json.null()?),
        ("sdfProperty", json.map(vec![
            ("temperature", json.map(vec![
                ("description", json.text("Product temperature")?),
                ("maximum", json.number("1e2")?),
            ])?),
        ])?),
    ])?;
    AuthorRequest::new(catalogue, "room-recipe", "room-product", "Room / Monitor")?
        .namespace("reuse", "https://example.com/capabilities")?
        .object(AuthorObject::new(
            "ambient / sensor", reusable, "/sdfObject/Sensor ~1 indoor", "reuse", true,
        )?.refinement(patch)?)?
        .checking(Assessment::Initial)?
        .author()
}
}

The reusable source keeps its original description, maximum and number tokens. The generated effective Property inherits its minimum, step and capability flags while overriding the maximum with the accepted 1e2 token. The Object description is absent, with its deletion explanation retained. Unrefined Action and Event descriptions keep their inherited values.

Use the ordinary EffectiveModel::explanation interface, then map a generated-source contributor back to its recipe:

#![allow(unused)]
fn main() {
use esdieff::{AuthorResult, EffectiveRequest};

fn inspect_refinement(result: &AuthorResult) -> Result<(), &'static str> {
    let effective = result.catalogue().effective(EffectiveRequest::new(result.generated_source()))?;
    let maximum = effective.explanation(
        "/sdfThing/Room ~1 Monitor/sdfObject/ambient ~1 sensor/sdfProperty/temperature/maximum",
    ).require()?;
    let generated_origin = maximum.sources().next().ok_or("maximum origin unavailable")?;
    let recipe = result.request_origin(generated_origin).require()?;
    assert_eq!(recipe.pointer().require()?, "/objects/0/refinement/sdfProperty/temperature/maximum");
    Ok(())
}
}

request_origin accepts a view belonging to this result’s Catalogue. A reusable-source contributor yields Absent; a foreign Catalogue view yields Unavailable, even if its compact Source ID and path coincide. Textual plans expose exact original-plan byte spans. Typed builders expose the logical recipe pointer with no fabricated textual span. Effective locations and generated-source byte spans keep their existing meanings. Author report 1.1 adds related recipe locations to located generated-source findings; ordinary check and inspection report tags retain their established contracts.

AuthorResult::checking() exposes the requested assessment, outcome, source roots and coverage through typed accessors. Its requested assessment-area and requirement counts remain separate from the single authoring unit in AuthorResult::requested_coverage(). full-baseline can remain unfinished while the candidate and independent inspection are available. Strict warnings can prevent document delivery while Authoring fidelity stays established. Limitations from Boolean or short-name sdfRef and from opaque contexts identify affected effective and source coordinates without hiding independent refinements or established errors.

For a delivered CLI result, inspect it with its explicit reusable inputs, for example esdieff inspect --view effective --document room.sdf.json --pointer '/sdfThing/Room ~1 Monitor/sdfObject/ambient ~1 sensor/sdfProperty/temperature' capabilities.sdf.json room.sdf.json. The ordinary inspection report exposes inherited, overridden and deleted observations and their nearest source origins. Use --format json for the shared structured inspection contract.

Authored-quality editing

Esdieff revises present authored qualities in one supplied SDF document. An owned EditRequest selects the original model source, a request key and a distinct generated key. Each Edit selects one authored named definition by decoded JSON Pointer and one exact Quality Name. replace requires an accepted JsonValue, including JSON null. remove carries no value. Both require a present original member.

The operation supports label, description and $comment on the six base named-definition classes, including ordinary nested definitions. Property and sdfData definitions additionally support exactly type, sdfType, const, default, enum, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, pattern, format, minItems, maxItems, uniqueItems, nullable, contentFormat and unit. Those data qualities remain unsupported on Thing, Object, Action and Event owners. Information blocks, arbitrary JSON, effective-only content, Action input/output, Event output, direct items, map-data entries and Choice alternatives are outside this owner capability. The operation refuses an owner or enclosing definition/data-description context with an authored sdfRef, irrespective of its value shape. Untouched Composition branches remain preserved.

A const or documentary default object/array is one literal value, never model structure or a Composition patch. Replacing it replaces the whole value. Literal null remains a present member, while removal makes the member absent. Replacement values are retained faithfully without quality-shape repair or coercion. Documentary values do not specify device behavior.

All targets are established against the original document before application. Empty or excess requests, malformed or overlong pointers, known missing owners/members, unsupported roles/qualities, duplicate decoded targets, contradictory operation fields, unknown source identities and generated-key collisions are request errors. Unreadable or incompletely decoded content and exhausted target-establishment work instead return scoped operational incompleteness.

EditRequest::from_plan(catalogue, bytes) accepts a UTF-8 JSON map with string key, source and generated_key, optional string generated_label, and a nonempty edits array. Each edit has string owner, quality and operation, with operation exactly replace or remove. value must be present for replacement, including explicit null, and absent for removal. Unknown fields, duplicate decoded members and repeated decoded targets are refused. source matches one supplied key exactly, without consulting labels or filenames. The generated key must differ from every retained source key, including substituted original evidence.

The plan retains original bytes and spans independently of model-source bytes. Public request locations retain the request key, logical /edits/index coordinate and original-plan span when available. Nested replacement coordinates remain below /edits/index/value. Typed requests retain the same logical coordinates with null textual spans.

Ownership and inspection

EditResult owns accepted intent, immutable original evidence, available candidate bytes and the active result Catalogue. original_source() exposes exact original bytes, path/URI, version and digest metadata. catalogue() and into_catalogue() expose active sources after replacing exactly the selected original contributor with the generated source. retained_sources() includes every retained attempt, including substituted evidence. Other contributors retain their identities and metadata. Explicit aliases remain distinct. Original evidence is never a name-resolution fallback.

The generated source has a new identity, caller key, Generated role and Generated acquisition state. Its acquisition URI, path, version and digest are absent. Same-document references stay within the generated document, and unchanged global names remain available to other contributors. A local-only source needs no namespace assignment.

target(index) relates one accepted edit to its original owner/member and request intent. Original spans describe original bytes. Generated-member spans describe generated bytes. Removed members return Field::Absent and receive no generated span. Typed request locations use /edits/index with no textual-plan span. request_origin() relates generated replacement content to /edits/index/value and any nested literal coordinate. These relationships do not promise exhaustive provenance.

Preservation and completion

Editing fidelity has identity esdieff.authored-quality-edit/1. Established fidelity verifies every requested change and every other authored JSON value, Given Name, definition position, namespace mapping and reference spelling. Unchanged and replacement numbers retain accepted lexemes, including exponents and numbers inside opaque or literal containers. Opaque content stays in its original authored position without a claim about unknown meaning.

Generated output is indented UTF-8 JSON with a trailing newline. Original whitespace, escape spelling, member order and byte spans are presentation details and are not reproduced. No numeric float conversion, normalization or coercion occurs.

Generation is independently complete, partial or unavailable. Fidelity is independently established or undetermined. A proven wrong edit or preservation loss fails the operation. Exhausted application, emission, decoding or fidelity work cannot produce completed editing or a deliverable document. Available candidate bytes remain inspectable. Successful editing without a requested Model check establishes faithful source changes, including intentionally invalid quality shapes, without claiming a valid model.

Optional Model checking

EditRequest::checking(Assessment::Initial) and checking(Assessment::FullBaseline) request one ordinary assessment. Other assessments or a repeated checking selection are request errors. strict_warnings(true) applies the ordinary warning policy. Checking selects the entire generated source as its root and uses the active Catalogue to establish needed dependencies. It neither independently certifies unrelated sources nor all consumers of the revised definitions. A subsequent ordinary Catalogue check can request that wider scope.

EditResult::checking() exposes the assessment, outcome, requested root IDs and assessment-area coverage. Full checking separately exposes its 54-requirement coverage. No check has an absent assessment/outcome/coverage, rather than a fabricated passed assessment. Complete candidate bytes and established Editing fidelity remain inspectable when a requested check fails or is unfinished. Ordinary delivery additionally requires that check to pass under its warning policy.

Source decoding, plan admission, transformation, fidelity and checking retain cumulative numeric, allocation and work allowances. A late limit preserves earlier established findings and leaves the whole requested editing operation unfinished. It never replenishes the check budget or turns an available candidate into delivered output.

Report 1.2

The supported esdieff.report envelope adds operation edit and version 1.2. Older operation meanings and unknown-operation guards remain unchanged. Top-level request.assessment and request.inventory are null. request.editing contains key, original_source, generated_source, edit_count and checking. The no-check slice reports checking as not_requested in both request summary and result.checking.state.

Requested coverage has count unit editing, total 1, and the existing assessed/unassessed/undetermined partition. This unit covers the whole request, including optional checking. An unfinished requested check therefore leaves this unit undetermined even when generation is complete and fidelity established. A completed check with findings still completes assessment of the unit, while the aggregate disposition fails. Broader RFC coverage remains partial. result retains generation, fidelity state and contract identity, generated document state/content completeness/retained bytes, original-to-generated substitution, active_sources, checking state and omissions. No generated JSON payload is mandatory.

Requested result.checking separately carries its assessment, inventory, scope, outcome and coverage. Its existing assessment_area and requirement units never count individual edits or the editing operation. Available Full inventories retain totals of 13 assessment areas and 54 requirements. Both established inventory aggregates remain mandatory when optional requirement rows or diagnostics are omitted. An unavailable inventory keeps its ordinary null inventory/total meaning. Ordinary source/effective check locations keep their meanings. Findings on revised replacement content can relate the generated span to the original member and /edits/index/value or its nested literal coordinate. These bounded relationships do not promise complete causality, and removed members receive no invented generated span.

Mandatory source records include all supplied/generated attempts, including original evidence. Scope roots identify the active generated source. Aggregate errors, completeness, identities, substitution and edit count remain present when optional diagnostics or pointers are omitted. Human and JSON conclusions use the same bounded projection. Editing diagnostics use separate edit_request locations with request key, logical decoded pointer and available textual-plan span. Typed spans are null. Existing source and effective locations retain their meanings.

Finite operation

The generated attempt and mandatory report envelope are reserved before request content is copied. All retained attempts share the configured ceiling of 256. Request/generated keys are at most 256 bytes, labels at most 512 bytes, selectors at most the configured 8 KiB default, and the nonempty request has at most 256 edits. Caller metadata shares the 1 MiB pre-copy ceiling. Original and generated raw bytes both count toward 4 MiB per-document and 32 MiB aggregate defaults, including after reuse of an active result Catalogue.

Source decoding, replacement admission, selection, traversal, transformation, verification and generated decoding share finite parsed-node/allocation, derived-node/allocation, numeric and work allowances. Storage and work are charged before allocation and emission, including JSON escaping, indentation and the trailing newline. Report detail has separate finite count, byte and pointer presentation limits. No phase replenishes an allowance. Reusing an active result Catalogue retains identity, acquisition-attempt and stored-byte accounting.

Plans are at most 4 MiB and obey any smaller configured document-byte ceiling. Generated-attempt and mandatory metadata/report reservation precede retained plan/request copying. Plan storage, JSON decoding and owned replacement copies consume the operation’s remaining allowances. Already charged replacement copies are admitted without charging their storage twice. Plan traversal carries its derived/work remainder into target establishment and generation.

Syntax and established field-shape errors are request errors. A hard decoding or admission ceiling that prevents a complete root, exact edit count or owned bounded request is a distinct admission-limit error and generates no document. Once request identity and the complete edit list are admitted, unavailable numeric capability, replacement copying or target-establishment work instead retains an unfinished result with the exact accepted edit count, original plan evidence and source substitution. It never permits ordinary document delivery.

Command and document delivery

The command accepts only explicit sources and a saved plan.

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

Repeat --source KEY PATH for other contributors. The plan’s source selects exactly one supplied key. Document output is required, and report output defaults to stdout. One source or the plan may use - for stdin. Document and report may each use - for stdout, but never together. There is no directory discovery, implicit acquisition or parent-directory creation. Plans are bounded by 4 MiB, CLI metadata by 1 MiB, and supplied source attempts by 255 so that the generated attempt remains reserved within 256.

An ordinary document is delivered only after complete generation and established Editing fidelity, plus a passing requested check under the warning policy. Without a check, the report explicitly says not_requested. Failed or unfinished work emits a report without writing the ordinary document. Exit codes are 0 for passed work, 1 for findings or strict warnings, 2 for invalid invocation/request, 3 for unfinished work without independent failure, and 4 for host or output failure. Hard pre-admission plan ceilings produce exit 2 before an owned editing request exists. Admitted incomplete requests retain a report and use their ordinary outcome code.

Human/JSON reports and generated JSON use distinct destinations. Report color never changes generated document bytes or JSON reports. Source and plan bytes remain immutable. File destinations protect every supplied source and the plan against direct, symlink, hard-link and resolved-parent aliases. Document/report file identities must also differ. Existing outputs require their corresponding replacement flag and must be regular non-symlink files. A replacement flag never permits an input alias, and it does not apply to stdout.

Each file output rechecks destination and protected-input identities, writes and syncs bounded staging in the existing destination directory, rechecks again and then commits individually. Create-only output uses a hard link so an existing file cannot be overwritten. Explicit replacement of an existing file uses rename. There are at most 100 staging-name attempts. Named FIFO input identities are retained without opening their streams before acquisition.

The document is delivered before the report. On any abandoned-staging failure, cleanup is attempted explicitly. Cleanup failure returns exit 4 and names the retained staging path, the original failure when present and whether the document was committed/delivered. A report failure after document delivery identifies that delivered document on stderr. Failed stdout delivery can leave partial bytes. There is no transaction across the two destinations or stdout rollback.

Reacquire a delivered file through ordinary checking or inspection, supplying needed dependencies and the edited file rather than its original contributor. For example, esdieff inspect --view source --document revised.sdf.json --pointer /sdfObject/Sensor revised.sdf.json examines the revised authored owner, and esdieff check --assessment full-baseline revised.sdf.json requests ordinary Model checking.

This contract follows ADR 0034: Authored-quality editing with source substitution. Renaming/moving definitions, inserting absent qualities, reference rewriting, namespace rebinding, in-place source writes, composition-patch editing and before-and-after equivalence remain separate capabilities.

Revision comparison

Esdieff compares two Model revisions from the Client’s side and classifies each difference between their corresponding groupings as breaking, compatible or undetermined. The rules follow ADR 0039: Client-side revision comparison, and the terms Model revision, Corresponding definition, Client, Client-supplied data, Thing-supplied data, Client direction, Breaking change, Meaning quality, Breaking witness, Representative value, Monotone rule, Compatibility proof, Difference acknowledgement, Acknowledged difference and Version warning come from the domain language. A difference Esdieff cannot classify stays undetermined, so it is never presented as safe.

#![allow(unused)]
fn main() {
use esdieff::{Catalogue, ComparisonRequest, SourceInput};
use std::path::Path;

let earlier = Catalogue::from_inputs(&[SourceInput::file("device.sdf.json", Path::new("v1/device.sdf.json"))])?;
let later = Catalogue::from_inputs(&[SourceInput::file("device.sdf.json", Path::new("v2/device.sdf.json"))])?;
let comparison = ComparisonRequest::new(&earlier, &later).compare()?;
println!("{}", comparison.to_human());
std::process::exit(comparison.disposition().exit_code().into());
}

The comparison contract identity is esdieff.revision-comparison/2. It binds which differences are classified and how. A release that classifies more differences gets a new identity, so a report keeps its meaning.

Command line

esdieff diff --old PATH --new PATH compares an earlier and a later Model revision. Each PATH is a directory, prepared with the directory discovery rules, or a single file, and both take the same form. --recursive and --exclude RELATIVE_PATH select both directories alike. Each document’s source key is its path relative to its directory, so documents correspond by location. Two single files correspond directly, whatever their names. From the repository root, compare the minimal and rich door lock models:

cargo run -- diff --old examples/door-lock-check/minimal.sdf.json --new examples/door-lock-check/rich.sdf.json

--format human|json selects one of the reports below, and the shared color controls style the human report. --format sarif emits the report’s SARIF projection for code-scanning annotations, and --format markdown its Markdown changelog for release notes. --acknowledged FILE supplies the acknowledged differences of an intended revision. Exit codes follow check and the disposition: a comparison without unacknowledged breaking or undetermined differences exits 0, one with an unacknowledged breaking difference 1 and otherwise one with an unacknowledged undetermined difference 3. Without --acknowledged, a compatible comparison exits 0, a breaking one 1 and an undetermined one 3. Version warnings never change the exit code. Invocation errors, such as a file beside a directory, - on either side, a missing --old or --new, an empty directory, a repeated --acknowledged, --acknowledged -, or an acknowledgement file that cannot be read or decoded, exit 2 with empty stdout before any document content is read. A report that cannot be written exits 4. The CLI contract states every rule.

Library operation

ComparisonRequest::new(earlier, later) takes the earlier and the later Catalogue, and compare() performs the comparison in one operation. Both Catalogues must use the same Limits, which set the one operation allowance described below. Different limits, or a report allowance too small for both revisions’ mandatory report envelopes, are request errors. recorded_registry_policy(policy) sets the recorded evidence policy for unit names and Content-Format identifiers and codings, described under Units and Content formats. As for check, the default uses the recorded evidence. acknowledgements(&acknowledgements) supplies the Difference acknowledgements described under Acknowledged differences.

RevisionComparison borrows both Catalogues and owns their effective models, which its typed differences and reports borrow, in the way model reports do. catalogue(revision) returns either Catalogue. outcome() returns the comparison’s Classification. It is breaking when any difference is breaking, otherwise undetermined when any difference is undetermined, otherwise compatible. Classification::disposition() maps it to the check dispositions: compatible is passed and breaking is failed. disposition() is the comparison’s own disposition, which only unacknowledged differences decide. Without acknowledgements it equals outcome().disposition(). complete() is true when no unacknowledged difference is undetermined, as the report’s outcome.complete states. count(classification) counts every difference, including any whose details could not be retained, and acknowledged_count(classification) counts the acknowledged ones. unused_acknowledgements() yields the zero-based positions of the supplied entries that acknowledge no difference. differences() yields the retained differences with unacknowledged breaking ones first, then unacknowledged undetermined, acknowledged breaking, acknowledged undetermined and compatible. compared_documents(), removed_documents() and added_documents() describe document correspondence. version_warnings() yields the Version warnings in the earlier revision’s source order. registry_knowledge(id) returns the recorded registry evidence that unit and content-format comparison consulted or found withheld. to_json(), to_human() and to_human_with_style(style) render the reports below, to_sarif(directory) renders the SARIF projection and to_markdown() the Markdown changelog.

Each Difference has:

• kind(): Removed when only the earlier revision has the content, Added when only the later one has it, Changed for a quality whose effective value differs, including one present in only one revision, and Unavailable when an effective view could not establish the content, so whether it changed is unknown.
• subject(): a whole Document, a grouping or affordance as Definition(class), a map properties Entry, or a Quality(name).
• classification() and reason(). The reason is present exactly when the difference is undetermined, with a stable code() and an explanatory message(). A unit change the recorded evidence cannot settle has the reason Unit(UnitReason), and a contentFormat change whose meanings cannot be compared has the reason ContentFormat(ContentFormatReason).
• directions() and affects(direction): the Client directions of the data the difference affects.
• witness(): the Witness of a data difference that is breaking because of one, described under Breaking witnesses and compatibility proofs.
• side(revision): the difference in the earlier or later revision, absent when that revision lacks the corresponding definition, properties entry or document. A side has its presence() (present, absent or unavailable), its root_document() numbered within its revision, its effective pointer(limit), and its origin(). The origin is the Explanation of the nearest content origin, or of the composition patch deletion that removed an absent quality.
• acknowledged(): whether a supplied entry acknowledges the difference, and acknowledgement(): the DifferenceAcknowledgement that would, present when the difference can be acknowledged and its effective pointers can be rendered.

Each VersionWarning has its code(), the earlier and later source IDs of its document pair as documents(), its earlier_version(), its later_version(), absent when the later document has none, and the pair’s breaking difference count as breaking(). location() is the later document’s source view at /info/version, or at /info or the document root when that member is absent, and related() the earlier document’s /info/version.

Acknowledged differences

A maintainer who publishes an intended breaking revision, or has reviewed an undetermined change, supplies Difference acknowledgements, following ADR 0040: Acknowledged revision differences. An Acknowledged difference keeps its classification, and the comparison’s result.outcome stays as it is. Only unacknowledged differences decide the disposition, so an acknowledged breaking comparison passes while its report still says it breaks Clients.

An acknowledgement file is one JSON object:

{
  "schema": "esdieff.acknowledged-differences",
  "version": "1",
  "differences": [
    {"kind": "removed", "subject": "sdfProperty", "classification": "breaking",
     "earlier": {"document": "lock.sdf.json", "pointer": "/sdfObject/Lock/sdfProperty/credential"},
     "later": null, "note": "Release 2 drops the credential"},
    {"kind": "changed", "subject": "quality", "quality": "minimum", "classification": "breaking",
     "earlier": {"document": "meter.sdf.json", "pointer": "/sdfObject/Meter/sdfProperty/power/minimum"},
     "later": {"document": "meter.sdf.json", "pointer": "/sdfObject/Meter/sdfProperty/power/minimum"}}
  ]
}

Each entry has a kind of removed, added or changed, a subject as in the report, a quality exactly when the subject is quality, a classification of breaking or undetermined, and earlier and later members. Each side is null or names the source key of the document holding the difference in that revision and its effective pointer, and at least one side is not null. An optional note is a comment for readers. An empty differences array is allowed. Unknown and duplicate members, two entries with the same identity, an entry of kind unavailable and an entry whose classification is compatible are refused.

DifferenceAcknowledgements::from_json(bytes, limits) decodes a file within the JSON decoding limits of limits, normally those of the revisions, and refuses limits a Catalogue would refuse, and DifferenceAcknowledgements::new(entries) builds the same value from typed entries. DifferenceAcknowledgement::new(kind, subject, classification) starts an entry, earlier(document, pointer) and later(document, pointer) locate it, and with_note(note) adds a note. Each validates as the file does, and DifferenceAcknowledgements::new refuses an entry without a location and duplicate identities. entries() lists them in file order, and each entry returns its kind(), subject(), classification(), document(revision), pointer(revision) and note().

An entry acknowledges a difference when the kind, subject, quality and classification are equal and, for each revision, both sides are null or the side’s root document source key and rendered effective pointer equal the entry’s document and pointer as exact decoded text. The note takes no part, and neither do request-local source IDs, content origins, directions, reasons or witnesses. An acknowledgement therefore still matches after an unrelated document is added to both revisions, and a shared definition seen through two groupings gives two differences that need two entries. Matching runs after the comparison over the retained differences, so it changes no classification. Breaking differences can be acknowledged, and so can undetermined differences of kind removed, added or changed whose content was examined, such as a reviewed added unit. A difference whose content nobody examined is never acknowledged: an Unavailable difference, a difference whose reason is UndeterminedReason::Unavailable, and a difference whose details the operation allowance could not retain. That reason covers the codes of unavailable content, such as reference.unavailable, data.number_unavailable, comparison.directions_unavailable and required.unavailable, and operation.limit. A difference whose pointer cannot be rendered within the materialized-pointer allowance also stays unacknowledged. Each pointer an entry needs is rendered once, so the report’s acknowledgement member and acknowledgement() give exactly the entry that matching compares. Because the classification is part of the identity, comparison rules that later classify an acknowledged undetermined difference as breaking bring it back for review: it is unacknowledged and its entry is unused. An entry that matches nothing is listed as unused and leaves the disposition unchanged.

The disposition is failed when any unacknowledged difference is breaking, undetermined when any unacknowledged difference is undetermined, and passed otherwise. outcome.errors counts unacknowledged breaking differences. outcome.complete, incomplete_checks and the requested coverage count unacknowledged undetermined differences.

Write an acknowledgement file for review with --acknowledgements-output FILE:

esdieff diff --old v1 --new v2 --acknowledgements-output reviewed.json

The file contains every eligible difference retained in the JSON report, including already acknowledged differences. Compatible differences and unavailable content have no entry. An empty comparison writes an empty differences array. Review the file before supplying it with --acknowledged. Exporting leaves the comparison report on standard output and preserves its exit status, so a breaking comparison still exits 1.

The destination must be a named file with an existing parent directory. An existing file requires --replace-acknowledgements, which permits replacement only of a regular non-symlink file. The destination cannot alias a selected document from either revision or the supplied acknowledgement file, including through hard links or parent-directory aliases. Destination validation precedes reading revision content. Delivery uses the same staged-write and input identity protections as edit. Destination or export-limit errors exit 2 with empty stdout. A write failure exits 4. If writing the report fails after export, the acknowledgement file has already been committed.

The file must fit the acknowledgement reader’s limits below. Export refuses an oversized or otherwise unreadable file before changing the destination. It covers the differences retained by the JSON report, so consult its omissions when comparison details were truncated. All report formats export the same entries.

Each difference that can be acknowledged also carries the exact entry that would acknowledge it in the report, so you can project a file yourself:

esdieff diff --old v1 --new v2 --format json | jq '{schema: "esdieff.acknowledged-differences", version: "1", differences: [.result.differences[].acknowledgement // empty]}'

This covers the differences the report kept within its allowance. An acknowledgement file is at most 1 MiB, which DifferenceAcknowledgements::FILE_BYTES states, decoded with the ordinary JSON input policies, and holds at most 4096 entries. Each document holds 1 to 256 bytes, each pointer at most 8192 bytes with RFC 6901 syntax, each quality at most 256 bytes and each note at most 1024 bytes. The mandatory report envelope reserves five bytes per supplied entry for the unused positions, and a report allowance too small for that reserve is a request error.

Correspondence

Documents correspond by source key, so the caller decides how documents pair. A document’s path within its revision’s directory is a natural key, and then a moved or renamed document has no correspondent. A model document only one revision has is a removed or added document, and each of its top-level groupings is a removed or added difference.

Top-level groupings correspond by their position in corresponding documents: the same class and Given Name. Nested groupings, affordances and map properties entries correspond by Given Name within their owner. A renamed definition therefore reads as a removal and an addition. Enum values correspond by value, so reordering an enum changes nothing. Choice alternatives correspond by Given Name and compare as the effective alternatives they derive, as described under Choices. Corresponding properties entries are compared at any depth of Map data with the same rules as the data description that holds them, and each difference inside an entry is located at that entry. An array’s items is compared in the same way, as the nested description of its values, described under Array data.

Every grouping of each corresponding document is compared through the effective view, including reusable Objects in shared documents. Top-level affordances and sdfData definitions are not compared as interfaces. Their changes appear through the effective groupings that use them, at any depth in their data, with the shared definition as the content origin.

Whether a quality changed

Exact numbers and Value equality decide whether an effective quality changed at all, following ADR 0012: Exact numbers and JSON input policies and ADR 0015: Bounded value equality in a resolved data context. Numbers compare their exact values, so 10 and 1e1 are the same bound. Text compares decoded Unicode scalar values, arrays are ordered and maps unordered. enum values and map-data required names compare as sets. An absent readable, writable or observable characteristic, or an absent Nullable characteristic of a data description, equals its explicit Specified default true, and an absent uniqueItems equals an explicit false. Inside items neither default applies. A representation that ordinary equality cannot settle under another meaning, such as two spellings of one instant, counts as a change and is classified like any other. Two contentFormat declarations in data with one established meaning, such as 50 and application/json, are the same, as described under Content formats.

Unchanged qualities produce no difference. sdfRequired instead compares by the requiredness it resolves to, described under Requiredness.

Classification

Client directions

Each difference in a data description names the Client directions it affects. A writable Property’s data and Action input are Client-supplied data. A readable or observable Property’s data, Action output and Event output are Thing-supplied data. A Property that is readable and writable carries data in both directions. Effective Property characteristics, including Specified default characteristics, decide which directions each revision offers, and data is compared only in the directions both revisions offer, since gaining or losing a direction is a characteristic change. When a needed characteristic is unavailable, the Property’s non-documentary data differences are undetermined with the reason comparison.directions_unavailable, apart from properties entries that no Client of the earlier revision uses, described under Map entries.

A Property whose revisions offer no common direction carries data to or from no Client in both of them, so each of its data differences is compatible and names no direction. The characteristic changes decide, as when a Property stops being readable and becomes writable.

A changed characteristic names the direction it allows. writable allows Client-supplied data, and readable and observable allow Thing-supplied data, so a characteristic that becomes false names the direction it removes. Input or output data added to or removed from an affordance names its own direction. Other differences outside data descriptions, such as removed affordances and grouping qualities, affect no data direction.

Breaking witnesses and compatibility proofs

A change to the values a data description admits is breaking only with a Breaking witness and compatible only with a Compatibility proof. Each changed quality that constrains admitted values has a monotone rule, which states whether the later revision admits more values than the earlier one under that quality, fewer, the same, or none of these. A Compatibility proof covers every changed quality of one data description: a Property’s data, an Action’s input or output, an Event’s output, or one map properties entry, array items description or choice alternative of them. It holds when each changed quality’s rule loosens in the safe direction for every Client direction the data carries, and nothing else in the description changed apart from documentary qualities. Client-supplied data may only widen and Thing-supplied data only narrow, so a readable and writable Property’s value set cannot change compatibly. An added or removed properties entry has a rule of its own, and one that no Client of the earlier revision uses leaves the proof as it is, as described under Map entries. A changed quality without a rule, another quality classified breaking or undetermined on its own, such as a breaking unit change or a changed contentFormat meaning, or unavailable content in the description leaves no proof. A changed sdfType changes how values read, so it never loosens in a safe direction.

Without a proof, Esdieff settles the candidate witnesses that the changed quality itself suggests, and for some qualities the representative values of the revision that must admit a candidate. At most 8 candidates are tried for one change, in the order its rule gives them, which bounds what settling a change costs. Sample-value checking checks each candidate against the effective description in both revisions, as it would a value supplied for that Property, input or output. A candidate that the earlier revision admits and the later one rejects is a witness for Client-supplied data, and one that the later revision admits and the earlier one rejects is a witness for Thing-supplied data. A witness counts only in a direction the data carries. Any other admission, including a candidate that another constraint such as a const excludes in both revisions, establishes nothing. A difference without a proof or a witness is undetermined with one of these reasons:

A candidate for a change inside a map properties entry is placed at that entry and checked against the whole Property data, input or output. Each enclosing map also holds a representative value of every other entry that either revision requires there, from the description of the revision that must admit the candidate, so the enclosing constraints still apply. So a candidate 23 for the end entry of a window entry is checked as {"window":{"end":23}}, or as {"window":{"end":23},"level":0} when the enclosing map requires an integer level with a minimum of 0. When a filled entry has no representative value, or its description rejects that value in both revisions, the difference stays undetermined with comparison.unproven. A candidate for a change inside an array’s items is placed as the items of that array, which holds it as often as the minItems of either revision requires, and at least once. So a candidate 100 inside the items of levels is checked as [100], or as [100,100] when levels requires two items. Repeated items are not unique, so an enclosing array that requires two or more unique items rejects the candidate in both revisions, and an enclosing minItems beyond the value capabilities gives no candidate. Either leaves the difference unproven.

The other revision must read the enclosing values as the admitting revision does, or it could reject the candidate for another change alone. So a candidate is not placed when the revisions describe a filled entry differently apart from its documentary qualities, such as its description or a $comment deep inside it, or when the other revision’s enclosing array could reject it for its length alone, with a maxItems below that length or with uniqueItems true for two or more items. Its difference then stays unproven unless another candidate witnesses it. So when two entries that a map requires both change what they admit, neither change gets a candidate placed beside the other entry. A candidate for a change inside a choice alternative stands where the description holding the choice does, since each alternative describes that description’s values, so a candidate 5 for a fan entry of the manual alternative of a mode entry is checked as {"mode":{"fan":5}}.

Representative values

A representative value is a simple value that an effective data description may admit. Esdieff generates them from the revision that must admit a candidate: the earlier revision for Client-supplied data and the later one for Thing-supplied data. A description’s representative values are, in order:

1. a copy of its const, in which each number keeps its authored spelling
2. its enum values
3. a copy of its documentary default
4. one value for each base type it admits, every base type when it has no type, in the order number, string, boolean, map and array, or for a choice the first representative value of each of its effective alternatives, in their order
5. null, when it is Nullable

A number lies at the description’s lower bound, or else at its upper bound: the bound itself when it is inclusive, and one unit inside it when it is exclusive, where the unit is 1 for an integer bound and one of the bound’s last digit otherwise. Without a bound it is 0. A string is a conventional value of a format that Sample-value checking checks beside type: "string": "1970-01-01T00:00:00Z" for date-time, "1970-01-01" for date, "00:00:00Z" for time, "https://example.com" for uri, "" for uri-reference and "00000000-0000-0000-0000-000000000000" for uuid. Otherwise it is minLength copies of a, which is "" without a minLength. Boolean data gives true. A map holds every entry the description requires, each filled with the first representative value of its own description, and null for a required entry without a description. An array holds minItems copies of the first representative value of its items, or of null without an items description, and is [] without a minItems. A Direct items description has no Nullable characteristic, so null is never a representative value of items.

A value that would nest deeper than a generated value may, or a count beyond the value capabilities, is never generated. A representative value that its own description rejects, such as an empty string beside a pattern, is no witness, so the change it was generated for may stay unproven. Generation is charged to the one operation allowance, and generation that runs out of it leaves its difference undetermined with operation.limit.

A Witness has its value() as JSON text, its direction(), and its admission(revision) in each revision. The JSON report gives the same as the difference’s witness, and the human report shows it on its own line beneath the difference.

Numeric bounds

Bounds compare as exact numbers. minimum and exclusiveMinimum together set a description’s lower bound, the tighter of the two, and maximum and exclusiveMaximum its upper bound. A change to either quality of a pair is judged by the effective bound the pair leaves. So an exclusive bound replacing an inclusive one at the same value narrows by that value alone, and a redundant bound can change without changing the admitted values. A raised lower bound, a lowered upper bound or an added bound narrows, and the reverse widens.

The candidates lie among the values the wider of the two revisions’ bounds admits and the tighter one rejects. They are the tighter bound when it is exclusive and the wider bound when it is inclusive, each in its authored spelling, so a bound written 1e2 is the witness 1e2. When neither bound value lies there, the candidate is one unit of the finer bound’s last digit across an open edge, or half a unit when one unit reaches the other edge. Without a wider bound the unit is 1 where the coefficient digit limit allows, so integer data gets an integer. An exclusive minimum of 0 replaced by a minimum of 10 has the candidate 1, a removed maximum of 2.5 the candidate 2.6, and a removed maximum of 100 the candidate 101.

String lengths

minLength and maxLength bound how many Unicode scalar values a string holds, inclusively, and compare as exact nonnegative integer counts. An absent minLength reads as 0 and an absent maxLength as unbounded. So a raised minLength, a lowered maxLength or an added maxLength narrows, and the reverse widens, while an added minLength of 0 leaves the admitted values as they are. The first candidate is a string of a whose length lies just across the tighter bound: one shorter than a tighter minLength and one longer than a tighter maxLength. The representative values of the revision that must admit a candidate follow it. So a minLength of Client-supplied data raised from 2 to 4 is breaking with the witness "aaa", a maxLength of Thing-supplied data raised from 6 to 8 with the witness "aaaaaaa", and a minLength of 3 removed from Thing-supplied data with the witness "aa". A length beyond the value capabilities is never generated, so such a change stays undetermined unless a representative value witnesses it. A count that is not an exact nonnegative integer neither narrows nor widens.

Steps

multipleOf admits the exact integer multiples of a positive step, and the comparison decides multiples exactly. Every multiple of the earlier step is a multiple of the later one exactly when the earlier step is a multiple of the later step. So a later step that divides the earlier one widens, such as 0.5 replaced by 0.25, and a later step that the earlier one divides narrows, such as 0.25 replaced by 0.5. Any other change, such as 0.3 replaced by 0.5, does neither. An added step narrows and a removed one widens. The earlier step is a candidate for Client-supplied data unless it is a multiple of the later step, and the later step is a candidate for Thing-supplied data unless it is a multiple of the earlier step, each in its authored spelling. Half a step is never a multiple of it, so half an added or removed step is the candidate, followed by 1 for an added or removed step above 1, which integer data may admit. The representative values of the revision that must admit a candidate come last. So 0.25 replaced by 0.5 breaks Client-supplied data with the witness 0.25, 0.5 replaced by 0.25 breaks Thing-supplied data with the witness 0.25, 0.3 replaced by 0.5 breaks them with 0.3 and 0.5, a step of 0.5 added to Client-supplied data breaks it with 0.25, a step of 3 added to integer Client-supplied data breaks it with 1, and the same step removed from integer Thing-supplied data breaks it with 1. A step that is not a positive exact number neither narrows nor widens.

Patterns and formats

A pattern restricts string data to the strings it matches, so an added pattern narrows and a removed one widens. Esdieff does not decide whether one pattern matches every string another matches, so a changed pattern neither narrows nor widens. The candidates are the representative values of the earlier revision for Client-supplied data, when the later revision has a pattern, and those of the later revision for Thing-supplied data, when the earlier revision has one. So a pattern ^[0-9]+$ added to write-only string data is breaking with the witness "", and a removed one is compatible there. A changed pattern is breaking only when a representative value matches one pattern and not the other, and otherwise stays undetermined with comparison.unproven.

A format follows the same rule for the six formats that Sample-value checking checks beside type: "string": date-time, date, time, uri, uri-reference and uuid. So date-time added to write-only string data is breaking with the witness "", and date replaced by date-time there is breaking with "1970-01-01", the conventional value of the earlier format. Every URI is a URI-reference, and Sample-value checking reads it as the same URI under either format, so uri replaced by uri-reference widens and the reverse narrows. So uri replaced by uri-reference is compatible for Client-supplied data and breaking for Thing-supplied data with the witness "", which is a URI-reference but no URI. A change where either revision’s format is another value, or sits beside no type: "string", is undetermined with comparison.not_classified.

Enum values

Enum values correspond by value as decoded strings, so reordering them changes nothing. A value only the earlier revision lists narrows the data, and a value only the later revision lists widens it, so an enum that loses some values and gains others does neither. Each such value is a candidate in the direction it breaks: a removed value for Client-supplied data and an added value for Thing-supplied data. So a value removed from a write-only Property’s enum, or added to a read-only Property’s enum, is breaking with that value as the witness, such as "off", while the reverse changes are compatible. An enum added to a description narrows it and a removed enum widens it. The candidates of an added enum are the representative values of the earlier revision, for Client-supplied data, and those of a removed enum the representative values of the later revision, for Thing-supplied data. So an enum added to write-only string data is breaking with the witness "", which the enum excludes.

Each enum value becomes an alternative whose own const replaces any const beside the enum, and an enum beside an sdfChoice gives no alternatives, following ADR 0024: Effective alternatives and nullable characteristics. So an enum beside a const or an sdfChoice, or one that is not a nonempty array of strings, neither narrows nor widens.

Choices

A choice admits the values that any of its effective alternatives admits, following ADR 0024: Effective alternatives and nullable characteristics. Alternatives correspond by Given Name, and each is compared as the effective alternative it derives, with the shared qualities it inherits and the branch qualities that replace them. Comparing the authored branches instead would read a branch that overrides a shared maximum of 10 with 20 as an added bound, although that alternative widened.

An alternative that only the earlier revision’s choice has is a Removed difference of the sdfChoice quality, located at that alternative, and one that only the later revision’s choice has is an Added one. A removed alternative narrows the data and an added one widens it, so an alternative removed from Client-supplied data or added to Thing-supplied data is breaking with a value of that alternative as the witness, and the reverse changes are compatible. The candidates are the representative values of that alternative, from the earlier revision for a removed one and the later revision for an added one. A candidate that another alternative still admits is no witness, so the difference stays undetermined with comparison.unproven.

Each alternative inherits every shared quality that its branch does not replace. A changed shared quality is reported once, at the description that holds the choice, and it is judged on each corresponding alternative that inherits it in both revisions, beside that alternative’s own qualities. So a shared quality that every alternative replaces changes nothing and is compatible, and a raised shared exclusiveMinimum that a shared minimum makes redundant still narrows an alternative that replaces that minimum. A quality that an alternative’s branch states in either revision is compared at that alternative, located there, so a branch that comes to override a shared maximum is a changed maximum of that alternative. The meaning qualities unit, contentFormat and sdfType follow the same distribution. A shared one tells a Client how to read only the values of the alternatives that inherit it in both revisions, so a change between two meanings that every alternative replaces is compatible, and one that an alternative inherits keeps its own classification. Beside a choice whose alternatives either revision does not establish, a change that would be breaking is not classified.

A choice added to or removed from data as a whole may admit values the other revision rejects, and reject values it admits, so it neither narrows nor widens. Its candidates are the representative values of the earlier revision for Client-supplied data and of the later revision for Thing-supplied data. An enum beside an sdfChoice derives no alternatives, and a choice with an unavailable branch does not establish all of them. A changed choice whose alternatives either revision does not establish is therefore not classified, and a shared quality beside it neither narrows nor widens.

Type

Every integer is a number, and a description without a type admits values of every type. So integer data that becomes number data widens, number data that becomes integer data narrows, an added type narrows and a removed one widens. A fraction separates integer data from number data. The candidates are 0.5, then a fraction just inside each bound of the revision that admits fractions: an inclusive bound that is a fraction itself, and otherwise half a unit inside the bound, of 1 for an integer bound and of its last digit for another. So integer Thing-supplied data that becomes number data has the witness 0.5, or 10.5 with a minimum of 10, and integer Client-supplied data that becomes number data is compatible. Any other change between base types, such as string data that becomes boolean data, neither narrows nor widens. The candidates of every change of type other than one between integer and number are representative values: those of the earlier revision for Client-supplied data, when the type is added or changed, and those of the later revision for Thing-supplied data, when it is removed or changed. So string Client-supplied data that becomes boolean data has the witness "", the same change to Thing-supplied data the witness true, and a type added to Client-supplied data without one the witness 0. A type other than the six base types neither narrows nor widens and suggests no candidate, so it stays undetermined.

Nullable

The effective Nullable characteristic decides each revision, with its Specified default true where nullable is absent. Data that stops being Nullable narrows and data that becomes Nullable widens, and null is the candidate. So Client-supplied data that stops being Nullable and Thing-supplied data that becomes Nullable are breaking with the witness null, unless another constraint excludes null in both revisions, and the reverse changes are compatible. A nullable that is not a boolean neither narrows nor widens.

Required map entries

Map data’s required names compare as a set of decoded strings. A later revision that requires every entry the earlier one requires, and more, narrows, and one that requires only some of them widens. A requirement added to Thing-supplied data or dropped from Client-supplied data therefore loosens in the safe direction. A representative map holds exactly the entries its revision requires. So the representative values of the earlier revision lack every newly required entry, and are the candidates for Client-supplied data, and those of the later revision lack every dropped requirement, and are the candidates for Thing-supplied data. When the earlier revision requires flow and the later one flow and label, the Client-supplied witness is a map holding only flow, such as {"flow":5} for an integer flow with a minimum of 5. A requirement dropped from Thing-supplied data has a witness map that lacks it, such as {} when nothing else is required.

Map entries

Clients use only what the earlier revision describes or requires, following ADR 0039: Client-side revision comparison. A properties entry that only the later revision describes, and that the earlier revision does not require, is part of no Client’s interaction, so it is compatible in every Client direction, whatever else changes in its map and even when the Property’s directions are unavailable. So an optional note added to write-only or read-only map data is compatible. Beside a choice, the earlier revision also requires an entry that a corresponding alternative requires when that alternative inherits the entries in both revisions, as a changed shared quality is judged. So when an earlier scheduled alternative requires an undescribed start, a start of string data described beside the choice of write-only data is breaking with the witness {"start":0}. An earlier choice whose alternatives either revision does not establish, or that the later revision lacks, may require the entry too, so the entry is settled as a required one. When the later revision also comes to require such an entry, its changed required decides, as described under Required map entries. So when map data that requires zone comes to require zone and a newly described note, the change is compatible for Thing-supplied data, and breaking for Client-supplied data with a witness map lacking the note, such as {"zone":1} for an integer zone with a minimum of 1.

Maps are open, so an entry without a description admits every value. An entry whose description is removed therefore widens its map. An entry that the earlier revision requires without describing it narrows its map when the later revision describes it. A removed entry is compatible for Client-supplied data and breaking for Thing-supplied data with a Breaking witness. A newly described entry that the earlier revision requires is compatible for Thing-supplied data and breaking for Client-supplied data with a Breaking witness. The candidates are maps holding the entry with one value of each JSON kind, 0, "", true, {}, [] and null in that order, beside a representative value of every other entry that either revision requires there, as for a nested candidate. So when read-only map data requires such a zone, a removed flow entry of number data is breaking with the witness {"flow":"","zone":1}. When write-only map data requires such a zone and a note in both revisions, and only the later revision describes the note as string data, the note is breaking with the witness {"note":0,"zone":1}. A removed entry whose earlier description admits every candidate, such as one with only a description, stays undetermined with comparison.unproven.

A candidate is therefore placed only at an entry that the earlier revision describes or requires. A candidate for a change inside an entry stands at an entry that both revisions describe, and the candidate of an added or removed entry stands at that entry. The other entries around a candidate are filled as for any nested candidate, so they hold every entry that either revision requires, including one that only the later revision requires.

Array data

An array’s items is the nested description of its values. Its changes are compared like those of a map properties entry: they are settled together, apart from the array’s own qualities, and each is located inside items. An items description is a Direct items description, whose vocabulary is sdfRef, type, sdfChoice, enum, minimum, maximum, format, minLength, maxLength, description and $comment, with required and properties when its type is object, following ADR 0024: Effective alternatives and nullable characteristics. Sample-value checking establishes no meaning for one that carries any other quality, such as const, pattern, exclusiveMinimum, nullable or label. So when either revision’s items carries such a quality, every change inside it other than to description or $comment is undetermined with comparison.not_classified, including a narrowed bound beside it. A Direct items description has no Nullable characteristic, so an absent nullable there differs from an explicit one, and null is never a representative value of items.

An array without an items description admits items of every type, so an items description added to array data narrows it and a removed one widens it. The candidates are arrays of 0, "", true, {} and [], in that order, each repeated as often as the minItems of the revision that must admit them requires, and at least once. So an items description of integers added to Client-supplied data, or removed from Thing-supplied data, is breaking with the witness [""]. An items that is a description in one revision and something else in the other is not classified.

minItems and maxItems are inclusive counts that compare as exact numbers. An absent minimum reads as 0 and an absent maximum as unbounded, so an added minItems of 0 changes nothing. A raised minimum, a lowered maximum and an added maximum narrow, and the reverse changes widen. The candidate is an array of the count just across the tighter bound: one item short of the higher minimum, or one item over the lower maximum. Each item is a copy of the first representative value of the items of the revision that must admit the candidate, or null without an items description. So when write-only data’s items are integers with a minimum of 0, a minItems raised from 1 to 3 is breaking with the witness [0,0], and a maxItems lowered from 4 to 2 with the witness [0,0,0]. A count that is not a nonnegative integer neither narrows nor widens, and a candidate count beyond the value capabilities is never generated, so its change stays unproven.

uniqueItems reads as false where it is absent, so an explicit false is no change. Data that comes to require unique items narrows, and data that stops requiring them widens. The candidate repeats one representative item, twice or as often as the minItems of the revision that must admit it requires. So uniqueItems that becomes true on Client-supplied data is breaking with a witness such as [0,0], and the reverse change on Thing-supplied data with the same witness. Repeated items are never unique, so a count candidate of two or more items for an array that requires unique items stays unproven.

Constants

A const restricts a description to one value, unless it sits beside an enum, whose values each replace it. So an added const narrows and a removed one widens. A changed const neither narrows nor widens. The candidates for Client-supplied data are the representative values of the earlier revision, when the later revision has a const, and those for Thing-supplied data the representative values of the later revision, when the earlier revision has one. A changed const therefore has the earlier constant as its first Client-supplied candidate and the later constant as its first Thing-supplied candidate, each copied with its numbers in their authored spelling. So a constant added to write-only string data is breaking with the witness "", a constant "open" changed to "shut" there with the witness "open", and a removed constant is compatible there.

sdfType

byte-string and unix-time are the sdfType conventions of RFC 9880 Section 4.7.1 that Sample-value checking establishes. They tell a Client how to read a value, so a change between them is breaking in every Client direction the data carries, without a witness, following the meaning qualities of ADR 0039: Client-side revision comparison. A convention that is added or removed changes how values read as well, so the change neither narrows nor widens, and it is breaking only with a Breaking witness. The candidate is a value outside the convention’s JSON representation, which the revision with the convention rejects: "!", outside the base64url alphabet, for byte-string, and "", which is not a number, for unix-time. So byte-string added to Client-supplied string data, or removed from Thing-supplied string data, is breaking with the witness "!". The reverse changes, and a candidate that another constraint such as a pattern already excludes, stay undetermined with comparison.unproven. Any other sdfType value is not classified.

Requiredness

Each grouping’s mandatory declarations come from its Required declaration relationships, following ADR 0026: Required declaration relationships and source evidence. An sdfRequired entry of a grouping makes the declaration it selects mandatory in that grouping. An affordance’s sdfRequired and a true carrier belong to the grouping that encloses the definition carrying them, so a carrier makes its own affordance or grouping mandatory there. A declaration required from an enclosing grouping is represented only inside the groupings between them, so those groupings are mandatory there too, and the declaration is mandatory in each of them. Requiredness then closes through mandatory groupings: whatever is mandatory in a mandatory grouping is also mandatory in the grouping that requires it.

Corresponding groupings compare these closures at every depth, and declarations correspond by their position in the document. A declaration that both revisions have and that stops being mandatory in a grouping is breaking, because a Thing may now omit what a Client uses. A declaration that becomes mandatory only obliges Things to provide more, so it is compatible. A declaration that only one revision has is a removed or added definition of its own and does not count here. Each grouping whose mandatory declarations change has one changed sdfRequired quality, located at that grouping’s sdfRequired, present or absent, and it affects no data direction. It is breaking when any declaration stops being mandatory there, even when others become mandatory.

Since requiredness is compared after resolution, "temp", "#/sdfObject/Oven/sdfProperty/temp" and a true carrier in temp spell one requirement, and replacing one with another is no change. A requirement that a Thing moves to a required Object inside it, which then requires the declaration itself, is no change either. An Object that keeps requiring temp while its enclosing Thing stops requiring it is breaking at the Thing, because the Object may now be absent.

A revision’s resolution is partial or unavailable when a name selects no declaration, a reference is ambiguous, unavailable or malformed, a target has no effective declaration, or the traversal could not see every definition. Then a grouping whose known mandatory declarations differ, or whose own sdfRequired or that of a corresponding direct affordance changed, is undetermined with the code required.unavailable, and an unchanged requirement stays no change. sdfRequired in data-only descriptions selects no declaration of a grouping, so it is compared as a data quality and stays not classified.

Grouping instance counts

minItems and maxItems make an sdfObject or sdfThing a Grouping array and bound its instance count inclusively. Things decide how many instances they have, so the range behaves like Thing-supplied data, following ADR 0039: Client-side revision comparison. When both revisions are arrays, a raised minimum, a lowered maximum or an added maximum narrows the range and is compatible, and a lowered or removed minimum or a raised or removed maximum widens it and is breaking. An absent minimum reads as 0 and an absent maximum as unbounded, so an added minItems of 0 leaves the range as it is and is compatible. Counts compare as exact numbers, each change is judged at its own end of the range, and none has a witness or a data direction. A grouping that becomes or stops being an array changes how its instances are addressed, so its count changes are undetermined with comparison.not_classified, and so are counts that are not exact nonnegative integers or a minimum above the maximum.

Units

A changed unit in a data description follows the unit rule of ADR 0039: Client-side revision comparison and the recorded evidence of ADR 0027: Unit names and recorded registry guidance, described in the unit contract. A change between two different current names breaks every Client direction the data carries, because Clients would misread its values. A current name has a nonlegacy entry in the recorded SenML evidence, from either its SenML Units or its Secondary Units section. So Cel to K, ms to s and Wh to kWh are all breaking.

Any other unit change is undetermined, with the first reason that applies:

A unit that is not text leaves the change undetermined with comparison.not_classified. A unit outside a data description is compared like any other unclassified quality. When a needed Property characteristic is unavailable, the change is undetermined with comparison.directions_unavailable, as for other data qualities.

Only names that need the recorded evidence are looked up, so added and removed units and URI names stay undetermined with their own reasons under either policy. With RecordedRegistryPolicy::WithholdRecorded, every other unit change is undetermined with registry.caller_withheld, and no recorded table is consulted. Each consulted row is charged to the one operation allowance. A lookup that exhausts it leaves its unit change undetermined with operation.limit.

Content formats

A changed contentFormat in a data description follows the meaning qualities of ADR 0039: Client-side revision comparison and the bounded model meaning of ADR 0033: Content-format model meaning, described in the content-format contract. A declaration’s established meaning is its media type and subtype compared without ASCII case, its parameter meaning, and its content codings in order:

• A media name has established parameter meaning only under the supported rules: application/json without parameters or with one charset, which has no effect, application/cbor without parameters, and text/plain in its US-ASCII default or with one utf-8 or us-ascii charset. Parameter names and these charset values compare without ASCII case, and quoted and token spellings are equivalent.
• Each coding needs a positive entry in the recorded HTTP content codings, compared without ASCII case. The reserved identity, an unrecorded token, and the deprecated x-gzip and x-compress, which RFC 9110 Section 8.4.1 makes equivalent to other codings, have no established meaning.
• A numeric identifier means its complete recorded CoAP tuple, without a separate coding lookup. Its content type is read through the same media rules where they apply, so 50 means application/json and 0 means text/plain; charset=utf-8. A tuple outside those rules, such as 21 for image/gif, keeps its registered parameters, and distinct tuples are distinct registrations.

Two declarations with one meaning, such as 50 and application/json, Application/JSON and application/json, or text/plain and text/plain; charset=us-ascii, are no change and produce no difference. Two different established meanings make Clients misread values in every Client direction the data carries, so application/json to text/plain, application/json to application/json@gzip, @gzip@deflate to @deflate@gzip, and 21 to 22 are breaking. Sample-value checking never establishes a value beside a contentFormat, so no witness settles these changes.

Any other contentFormat change is undetermined, with the first reason that applies:

Both spellings and their media rules are read before any recorded evidence, so a declaration without meaning on its own spelling is unestablished under either policy, and the supported media rules need no recorded evidence. Then the earlier declaration’s identifier or codings are looked up before the later one’s. With RecordedRegistryPolicy::WithholdRecorded, a change that needs a numeric identifier or a coding is undetermined with registry.caller_withheld, and the withheld registry is named in the report. A contentFormat that is not text leaves the change undetermined with comparison.not_classified, and a contentFormat outside a data description is compared like any other unclassified quality. When a needed Property characteristic is unavailable, a change that is not a respelling is undetermined with comparison.directions_unavailable.

Classification, the media rules, every compared row and the comparison itself are charged to the one operation allowance, and a comparison that exhausts it leaves its change undetermined with operation.limit. A comparison that consults the media rules or a recorded tuple names content-format-model-meaning/1 in baseline.interpretations.

Unavailable content

A revision with findings, unresolved references or other unavailable content is still compared, following ADR 0006: Scoped reference failures. Only the differences that depend on content an effective view could not establish are undetermined, each with a reason from that content. Content the view could not establish is an Unavailable difference whose reason carries the view’s code, and a change whose Client directions or requiredness depend on such content is undetermined with comparison.directions_unavailable or required.unavailable. Independent differences keep their classifications, so a breaking removal elsewhere still decides the outcome.

• An unresolved reference, an effective reference cycle or an unavailable dependency leaves the affected definition, properties entry or quality undetermined, with a code such as reference.unavailable or reference.effective_cycle. Content hidden by an unavailable owner never reads as removed or added.
• A document that could not be acquired or decoded keeps its acquisition result in its source row under its revision, and its revision’s scope lists it in unavailable_required. Each top-level grouping of the corresponding document in the other revision is an Unavailable definition with the acquisition reason, such as json.syntax, document.envelope or input.acquisition. Its side in the failed revision is that document, with presence unavailable, so no grouping reads as removed or added. When neither document has a grouping to name, the document itself is one Unavailable difference.
• A document that declares an Extension feature is deferred as a whole, following ADR 0003: Check findings and completeness. It is compared like an undecodable document, with the code structure.feature_context_unavailable, and a definition importing content from it is undetermined with the same code.
• Undeclared extension vocabulary leaves the base meaning of its definition intact, following ADR 0037: Undeclared extension vocabulary. Base qualities beside it keep their classifications, and a change to the vocabulary itself is undetermined as not classified. baseline.interpretations names undeclared-extensions-ignorable/1 when a breaking or compatible classification concerns a quality of a definition or data description carrying extension vocabulary, or rests on a witness whose checks set aside such vocabulary deeper in the description. Recorded extension vocabulary such as oma:id counts too, because the comparison does not consult its record, following ADR 0038: Recorded extension vocabulary.

One operation allowance

One operation allowance covers both revisions’ acquisition, composition and comparison, following ADR 0009: Bounded processing and reporting and ADR 0013: Shared workflow and report guarantees. No revision or phase refills it. Both revisions’ parsed nodes, parsed allocation, decoding work, numeric work and retained bytes together must fit the shared Limits. When the later revision’s acquisition exceeds what the earlier one left, every later document is unavailable with operation.limit. Composition and comparison then share one work, allocation, node and reference allowance, which also covers collecting each composed document’s Required declaration relationships and closing its requiredness. Corresponding documents are composed and compared one pair at a time in the earlier revision’s source order, followed by removed and then added documents. Monotone rules and witness checks charge the same allowance, and a witness check that runs out of it leaves its difference undetermined with operation.limit. When the allowance runs out, the rest of that document and every later one are undetermined with operation.limit. A document whose composition ran out is unavailable on that side, and a document whose comparison ran out gains one document difference with both sides present. Differences already found keep their classifications, and a difference whose details the allowance could not retain still counts. In the description where the allowance ran out, a changed quality without a monotone rule, in data that a common Client direction reaches, stays undetermined with comparison.not_classified. Every other change there that was still waiting to be settled is undetermined with operation.limit. Each revision keeps its own source-attempt ceiling, because source IDs are numbered within each revision.

Version warnings

A Client that watches a model’s info version misses a breaking revision that keeps or lowers it. RFC 9880 Section 3.1 recommends a version that is lexicographically increasing over a model’s life, so Esdieff warns about such a revision, following ADR 0044: Versions of breaking revisions. A compared document pair gets one Version warning with the code comparison.version_not_increased when all of these hold:

1. The document’s bytes changed between the revisions.
2. The comparison of the pair found at least one breaking difference, acknowledged or not. Every difference found while comparing a pair is located in its documents.
3. The earlier revision’s info version is text, and the later revision’s is absent or is text that does not compare higher by Unicode code point order.

Comparison is plain code point order, without date parsing, so 2020-07-06 after 20200706 and 2019-11-14 after 2019-11-14 both warn, and 2019-11-15 after 2019-11-14 does not. A pair whose document is unchanged gets no warning, even when a document it imports changed. A breaking difference belongs to the pair in whose effective groupings it is located, so a changed document that holds only shared definitions, such as sdfData that other documents import, gets no warning of its own. Neither does a pair whose earlier version is absent or not text, or whose later version is present but not text, nor a removed or added document. A breaking difference whose details the operation allowance could not retain still counts.

The warning never changes a classification, the outcome, the disposition or the exit code, and strict_warnings stays false. Reading the two versions and comparing the document bytes is linear in content both Catalogues already admitted, so it charges nothing to the operation allowance.

Report 1.5

Operation diff uses the esdieff.report envelope with version 1.5, which adds Version warnings to version 1.4. Version 1.4 added the acknowledgement fields and the disposition they decide to version 1.3. Every diff report is emitted at 1.5, with or without acknowledgements or warnings. The shared source, outcome and diagnostic meanings of the report contract remain intact. Both Catalogues number their sources from 1, so each source names its revision, and every ID inside an earlier or later member selects a source of that revision.