Models, populations, and evidence formats

GND artifacts answer different questions and have different versioned contracts. Keep them separate even when they refer to the same model. A model version, a report schema version, and the package version are independent identities.

The two starting artifacts

A model declares object types, fact types, constraints, provenance, and optional operations, derivations, and fixed references. A population provides instances and facts for that vocabulary and declares what it covers. Both accept the supported YAML/JSON representation; a .json suffix does not turn a file into a different semantic model.

population.model is a model reference label; model_id, when declared, checks compatible identity. Neither means “open any path written inside this data.” Pass the actual model explicitly to the API or command. Coverage says which fact types the population addresses. An absent relation is not silently equivalent to a deliberately covered empty relation.

Use complete tutorial checkpoints as starting examples. A schema fragment in a guide illustrates one construct and is not a complete loadable model.

Canonical references

These links point into the repository's maintained specification and schema sources. For a released integration, consult the same paths at the tag/commit matching your installed package rather than assuming main is that version.

Bind bytes without confusing the identities

Some identities bind normalized model/population representations; others bind the raw file bytes. The format says which applies. Fixed-reference sha256 pins, for example, bind exact raw files; changing whitespace changes the pin. Transition model_digest and operations_digest have different bases. Obtain them from gnd validate MODEL --trace, rather than hashing the whole model file and guessing. The canonical model identity, a digest a caller can recompute without Python, is defined in the representation format's "Model identity (canonical, versions 1 and 2)"; gnd validate MODEL --identity prints it and the document it hashes. Wherever GND matches a model_digest you supply (a walk, a report read back, a synth sidecar, a witness certificate), either identity is accepted, and GND keeps writing the legacy value in its own reports; the representation format's digest table states the rule.

An input refusal after a file change is useful information: the old evidence described other bytes. Re-author or regenerate the appropriate dependent artifact deliberately. Do not merely replace a digest to label old evidence current without rerunning the step that produced it.

Consume the right report

Check JSON, a session outcome, a conformance report, a witness certificate, and a review synthesis are not interchangeable success records. Read the schema version and command family first, then its findings and bindings. Report version 15, written by gnd check --rule-ids, --baseline or --allow-vacuous, is described in the rule-check report reference. Reference-aware reports can wrap the mechanical report, while the base diff schema has its own shape. Use the API examples for concrete access patterns rather than reaching into private evaluator internals.