4. The contract¶

English | Português (Brasil)

← Format reference · Contents · Tools →

Two levels: MUST and SHOULD¶

Both are hand-written JSON Schema 2020-12. On top of them, the contract has the YAML profile rules (a single document, duplicate keys, the on key) and the integrity rules (ids, edge ends, orphans), which JSON Schema cannot see. So a JSON Schema validator alone is not a complete reader: the reference reader applies all three layers, and the conformance suite checks all three in every reader.

The schema's format: date is an assertion: the date must exist on the calendar (2026-02-30 fails). Many validators treat format as an annotation by default, so the suite has cases for it.

Codes¶

Every violation has a stable code, shaped by its layer:

<kind> is one of required, enum, type, pattern, range, const or unknown-key. <scope> is one of top, meta, node or edge. For a nested field, the path uses dots: form.required.node.provenance.locator. In external_edges, the scope is top and the field carries the list name (form.enum.top.external_edges.edge_type). A date that is not on the calendar (format: date) fails as form.pattern.<scope>.<field>.

The full list, with what each code catches, is in spec/conformance/README.md.

Where in the source (v4.17)¶

A locator was free text: "lines 10 to 12", "the License section". People read it; a tool could not check it. Since v4.17, a node can say how to read it, and keep a hash of what it read. Both are optional and only warn: nothing that passed fails.

provenance:
  source: "https://github.com/acme/brain/blob/9f2c1e0/docs/payments.md"
  locator: "line=41,44"
  method: "reading: the retry section"
  scheme: text
  sha256: "3f1d…"   # 64 lowercase hex digits: the SHA-256 of the file at that commit

The conformsTo URIs of the W3C Web Annotation model count as aliases, including the RFC 3778 URI that its table still uses for PDF. The hash goes in its own field: the md5= of RFC 5147 is not used, because MD5 does not resist collisions (RFC 6151). Warnings: form.enum.node.provenance.scheme, form.pattern.node.provenance.locator (the locator does not fit its scheme) and form.pattern.node.provenance.sha256. kg_trace check then opens the source and checks the locator and the hash (chapter 5). What the standards leave open is a decision of this contract, written as such: a JSON Pointer that does not resolve in a JSON source fails kg_trace, char counts code points in every reader, rows and columns of a CSV count from 1 and are written without a leading zero (RFC 7111 allows 0 and 01), and the media interval excludes its end. The form does not check what only the source can say, such as a start after the end or a line that does not exist: that is the job of kg_trace.

The hash of a cited node (v4.18)¶

A bridge to another graph (scheme: kg-node) points to one node inside a file. The sha256 of the file breaks as soon as any node of that file changes, even one the bridge does not cite. Since v4.18, provenance.node_sha256 hashes only the cited node: the SHA-256 of its canonical form by RFC 8785 (JCS, the JSON Canonicalization Scheme), computed over the model the reader extracts from the graph, with keys in UTF-16 order and numbers and strings in ECMAScript form.

provenance:
  source: "https://github.com/acme/core/blob/9f2c1e0/docs/graph/seals.kg.yaml#D_RETRY_POLICY"
  locator: "#D_RETRY_POLICY"
  method: "testimony: the seal of the core"
  scheme: kg-node
  node_sha256: "d4d7…"   # kg_trace.py digest docs/graph/seals.kg.yaml#D_RETRY_POLICY

It goes only with scheme: kg-node and only warns: form.pattern.node.provenance.node_sha256 out of form, form.required.node.provenance.scheme without a scheme, form.const.node.provenance.scheme with another one. kg_trace check compares it with the cited node (chapter 5).

What changed from v3 to v4¶

v4 is a major version: what used to warn now fails.

The minor releases of the 4.x line added features without changing the MUST verdict of a well-written graph, with one recorded exception: 4.11.0, 4.12.0 and 4.13.0 started to fail rare YAML constructs (the strict profile). They were minor because none of the real graphs measured in four adopter repositories changed its verdict. Even so, they count as new MUST rules for the stability criterion, and each one reset the 30-day clock. Since 4.11.0, the contract has its own version label (v4.4 in 4.11.0, v4.5 in 4.12.0, v4.6 in 4.13.0, v4.7 in 4.14.0, v4.8 in 4.15.0, v4.9 in 4.15.1 and 4.16.0, v4.10 from 4.16.1 to 4.18.0, v4.11 in 4.19.0 and 4.20.0, v4.12 in 4.21.0, v4.13 in 4.22.0, v4.14 from 4.23.0 to 4.26.0, v4.15 from 4.27.0 to 4.31.1, v4.16 from 4.32.0 to 4.36.0, v4.17 in 4.37.0, v4.18 since 4.38.0), which is not the release number.

Versions and tags¶

A release is a kg-ssot-vX.Y.Z tag (up to 4.3.0, the name was contract-vX.Y.Z; the old tags still exist). Going by the release history:

The gate stores the sha256 of both schemas as the contract identity. A tag that changes the bytes of the schemas, even only in the description text (4.7.2) or in $id (4.7.3), changes the identity. Since 4.16.0, the identity is composite: the gate reports the change on a · identity line, but the comparison, made with the new contract, decides the rc. A change that changes no verdict passes with rc 0, and --update records the new identity when you choose to. A new rule that makes a graph worse fails through the comparison. --strict-identity restores rc 1 on every change, as before 4.16.0. When it runs from a vendor, the gate checks the sha256 of both schemas against the stamp and fails a hand-edited schema. A rule that only the reader sees (the YAML profile, the line break) also goes into the description of the MUST schema, as a line that starts with "No v4.6 ..." (the schema descriptions are in Portuguese): since 4.13.1, release hygiene requires that line for the version the reader declares, so every contract version moves the identity.

A new SHOULD warning can raise the debt the gate measures. That is intentional: a contract's ramp is to warn in one version and fail in the next, so you see the debt before it becomes an error.

The surface that travels in each tag is listed in spec/release.json. You do not customize the contract in your repository: the vendor fails a local edit, and a needed change goes back to the product as an issue in the public repository.

The older contracts¶

The product repository keeps v1, v2 and v3 in spec/ as history; the release ships only v4, the current one, which is what the reader uses without --schema.