6. Identifiers, versioning and digests

This section is normative.

6.1 Identifiers

• Every id MUST be an absolute URI (RFC 3986) and MUST NOT contain the characters @ or #, which are reserved for references.
• Producers SHOULD use URIs under a domain they control, for example https://ois.acme.example/intents/INT-142.
• An intent id and an actor id identify the thing across all its versions. A single version is identified by the pair of id and version.
• Artifact, evidence and decision id values MUST be unique per record.
• Producers MUST NOT use unregistered URN namespaces. No URN namespace for OIS is registered yet (Appendix C).

6.2 References

Form	Syntax	Used for
Plain	<id>	Artifacts, evidence, decisions
Versioned	<id>@<version>	Intents, agents and tools
Criterion	<intent-id>@<version>#<key>	A criterion within one intent version

Example of a criterion reference: https://ois.acme.example/intents/INT-142@3#AC-2. References to intents, agents and tools MUST use the versioned form. Human actors have no version and are referenced in plain form.

6.3 Versioning

• Intents: a draft version MAY change. Once a version has status approved, its record MUST NOT change. Any change creates a new version with version increased by 1 and supersedes pointing to the previous version.
• Supersession: a version is superseded when a newer approved version of the same intent exists. Consumers derive this; it is not stored.
• Withdrawal: an intent is withdrawn by recording a new version with status withdrawn.
• Stale evidence: evidence bound to version n remains current for a later version m only if version m contains a criterion with the same key and an identical criterion digest. Otherwise consumers MUST treat the evidence as stale for version m.
• Actors: version is a free-form string. Section 4.4 defines when a new version is required.
• Specification: during 0.x, versions MAY be incompatible. From 1.0, minor versions will only add optional fields.

Revocation: records are never deleted or edited. Evidence that turns out to be wrong, for example from a flaky test, is withdrawn by a decision with gate evidence-revocation whose subject is the evidence record (R11). Consumers MUST stop counting revoked evidence.

6.4 Digests

• Producers MUST include a sha256 value, except for artifacts located in Git, which MAY use the gitCommit key alone. Consumers MUST support sha256.
• Artifacts: the digest is computed over the raw bytes of the artifact content.
• Criteria: the digest is computed over an object that contains only the criterion’s key, statement, notation, kind, target and language, in JSON Canonicalization Scheme form (RFC 8785). criticality is excluded, so changing it does not make evidence stale.
• Intents: criterion digests are computed first. The intent digest is then computed over the intent record without its top-level digest and status members, in RFC 8785 form. It therefore stays the same when a draft becomes approved, and the intent-approval decision binds it through subjectDigest.
• Other records are protected by signing the bundle or passport that carries them (section 8.3).