4. Core data model

This section is normative.

OIS defines six record types (intent, artifact, actor, evidence, decision, finding), one embedded type (criterion) and one transport container (bundle). Fields not listed here MUST NOT appear at the top level of a record. Additional data goes into extensions (section 10).

4.1 Common fields

Every record MUST carry these fields.

Field	Type	Req.	Description
ois	string	REQUIRED	Specification version. MUST be "0.1" for this version.
type	string	REQUIRED	One of intent, artifact, actor, evidence, decision, finding.
id	URI	REQUIRED	Identifier of the record (section 6.1).
createdAt	timestamp	REQUIRED	When the record was created.
profiles	array of URI	OPTIONAL	Profiles the record conforms to (section 10.2).
trace	object	OPTIONAL	W3C Trace Context with traceId and optional spanId.
extensions	object	OPTIONAL	Namespaced extension data (section 10.1).

Shared types:

• Ref: a URI string that identifies a record or artifact. Versioned and criterion references follow section 6.2.
• Digest: an object that maps algorithm names to lowercase hex values, for example {"sha256": "9f86d0..."}. This is the in-toto DigestSet format.
• Measurement: an object with name (string, REQUIRED), value (number, string or boolean, REQUIRED), unit (string, OPTIONAL) and method (URI, OPTIONAL). The method identifies how the value was computed; OIS does not define methods.

4.2 Intent

An intent states what a change must achieve. Each version is a separate, immutable record once approved.

Field	Type	Req.	Description
version	integer ≥ 1	REQUIRED	Increases by exactly 1 per new version.
title	string	REQUIRED	Short human-readable title.
status	enum	REQUIRED	draft, approved or withdrawn. Supersession is derived, not stored (section 6.3).
language	string	OPTIONAL	BCP 47 language tag of title and of criteria that set no language of their own.
criteria	array of Criterion	REQUIRED	At least one criterion.
producedBy	Ref	RECOMMENDED	The actor that drafted this version, for example a requirement agent.
source	URI	OPTIONAL	Origin, for example an issue tracker item.
supersedes	Ref	OPTIONAL	Versioned reference to the previous version.
risk	enum	OPTIONAL	low, medium, high or critical. How it is assessed is out of scope.
digest	Digest	REQUIRED when approved	Digest of the intent’s canonical form (section 6.4).

Criterion (embedded in an intent):

Field	Type	Req.	Description
key	string	REQUIRED	Unique within the intent across all its versions, for example AC-2. Pattern [A-Za-z0-9._-]{1,64}.
statement	string	REQUIRED	The criterion text.
notation	enum	REQUIRED	gherkin, ears or text.
kind	enum	REQUIRED	functional or non-functional.
language	string	OPTIONAL	BCP 47 language tag of statement. Overrides the intent’s language.
target	object	RECOMMENDED for non-functional criteria	Measurable threshold: metric (string), operator (lt, lte, gt, gte or eq), value (number) and optional unit. An evidence measure whose name equals metric shows whether the target is met.
criticality	enum	OPTIONAL	low, medium or high.
digest	Digest	REQUIRED when the intent is approved	Digest of the criterion’s canonical form (section 6.4).

4.3 Artifact

An artifact record references something produced during delivery. It never contains the artifact itself.

Field	Type	Req.	Description
kind	enum	REQUIRED	code, test, contract, dataset, document, build or other.
location	URI	REQUIRED	Where the artifact or its container lives, including the revision, for example a Git repository at a commit. For packages, a Package URL (purl) is RECOMMENDED.
path	string	OPTIONAL	Path of the artifact inside the container at location, for example a file in a repository.
digest	Digest	REQUIRED	Digest of the artifact’s content.
producedBy	Ref	REQUIRED	Reference to the producing actor (section 6.2).
inputs	array of Ref	RECOMMENDED for builds	Artifacts this artifact was made from, for example the code commits a build contains. SLSA provenance for the same build MAY be referenced in extensions.
context	array of Ref	OPTIONAL	Everything the producer was given as input. If present, it MUST be complete (section 5).
contextRecordedBy	Ref	RECOMMENDED	The actor that observed and recorded context, usually the runtime or gateway that ran the producer. The context counts as attested only under the conditions of R12; otherwise it is self-declared.
classification	enum	REQUIRED for datasets	synthetic, anonymized or production.
mediaType	string	OPTIONAL	IANA media type of the content.

4.4 Actor

An actor is a human, an AI agent or a tool. Each actor version is a separate record.

Field	Type	Req.	Description
kind	enum	REQUIRED	human, agent or tool.
name	string	REQUIRED	Display name. For humans, a pseudonym is RECOMMENDED (section 12).
version	string	REQUIRED for agents and tools	Version of the actor.
model	object or array	REQUIRED for agents	provider, name and version of the underlying model. Agents that route between several models give an array of such objects. Where a vendor does not disclose the model, name MAY be undisclosed.
identity	object	RECOMMENDED, REQUIRED for Level 3	How signatures are attributed to this actor: issuer (URI) and subject of a certificate identity, or keyId for a long-lived key. Agents and tools SHOULD use workload identities such as SPIFFE IDs. For humans, subject MUST NOT be an e-mail address or another direct identifier; use a pseudonymous subject or omit identity (section 12).
operator	string	OPTIONAL	Team or organization responsible for the actor.
autonomyLevel	integer 0–3	OPTIONAL	See below.

When an agent’s model, system instructions or tool set change, producers MUST record a new actor version.

Autonomy levels have a fixed meaning. How a level is assigned is out of scope.

Level	Name	Meaning
0	Suggest	The actor only proposes. A human performs the action.
1	Full review	Every output is reviewed by a human before it takes effect.
2	Sampled review	Outputs take effect after risk-based or sampled human review.
3	Autonomous within policy	Outputs take effect when all policy gates pass.

4.5 Evidence

An evidence record states that one test run produced one result for one criterion.

Field	Type	Req.	Description
criterion	Ref	REQUIRED	Criterion reference (section 6.2).
test	Ref	REQUIRED	The test artifact (kind test).
subject	Ref	RECOMMENDED	The implementation artifact under test.
inputs	array of Ref	OPTIONAL	Further inputs such as datasets or configuration.
derivedFrom	enum	REQUIRED	intent, implementation or unknown: what the test was derived from. The value is a claim that validators check against R4 and R5 (section 5).
result	enum	REQUIRED	pass, fail, skipped or error.
observedAt	timestamp	REQUIRED	When the result was observed.
recordedBy	Ref	REQUIRED	Reference to the actor that ran the test and recorded the result.
measures	array of Measurement	OPTIONAL	For example a mutation score.
run	URI	OPTIONAL	Link to the pipeline or test run.

4.6 Decision

A decision records the outcome of a gate.

Field	Type	Req.	Description
gate	string	REQUIRED	Gate name. Well-known gates are listed below; other names are allowed.
subject	Ref	REQUIRED	What was decided on: an intent version, an artifact, a finding or a release.
subjectDigest	Digest	RECOMMENDED, REQUIRED for intent-approval and release	Digest of the subject as it was when the decision was made, so that the decision binds to content and not only to an identifier.
outcome	enum	REQUIRED	approved, rejected, passed, blocked or waived.
decidedBy	Ref	REQUIRED	Reference to the deciding actor.
decidedAt	timestamp	REQUIRED	When the decision was made.
policy	object	OPTIONAL	Policy evaluated: id (URI), version and optional digest.
evidence	array of Ref	OPTIONAL	Evidence records considered.
assessments	array of Measurement	OPTIONAL	Values considered, for example a risk score.
rationale	string	REQUIRED when outcome is waived	Why the decision was made.

Well-known gates:

Gate	Subject	Outcomes	Meaning
intent-approval	Intent version	approved, rejected	The intent is accepted as the measure for the work.
design-approval	Artifact of kind contract or document	approved, rejected	The design or contract is accepted.
merge	Artifact of kind code	passed, blocked, waived	The change may enter the main line.
release	Artifact of kind build. A release made of several builds uses one build artifact whose inputs list the parts.	approved, rejected, passed, blocked, waived	The build may be released.
evidence-revocation	Evidence record	rejected	The evidence is withdrawn and MUST NOT be counted (section 6.3). rationale is REQUIRED.
finding-resolution	Finding record	approved, rejected	The resolution listed in resolvedBy is confirmed by an actor other than the producers of that resolution (R14).

4.7 Finding

A finding records a defect or incident: behaviour that violates a criterion, or behaviour that nobody required. It is the entry point of the learning loop, and it suits existing systems, where defects usually come before intents.

Field	Type	Req.	Description
criterion	Ref	OPTIONAL	The criterion that was violated, if one exists.
intent	Ref	OPTIONAL	Versioned reference to the intent the finding concerns.
subject	Ref	RECOMMENDED	The artifact in which the behaviour was observed, usually a build or code.
source	enum	REQUIRED	production, test, review, customer or other.
severity	enum	REQUIRED	low, medium, high or critical.
summary	string	REQUIRED	Short description of the behaviour. MUST NOT contain personal data.
observedAt	timestamp	REQUIRED	When the behaviour was observed.
reportedBy	Ref	REQUIRED	The reporting actor (section 6.2).
ticket	URI	OPTIONAL	Issue tracker item.
cause	enum	OPTIONAL	Root cause once classified: spec-gap, implementation, test-gap, gate-gap, review or unknown.
resolvedBy	array of Ref	OPTIONAL	Intent versions, artifacts or evidence that resolve the finding.
supersedes	Ref	OPTIONAL	The previous finding record this one replaces.

Rules:

• At least one of criterion, intent or subject MUST be present.
• Findings are immutable like every record. To classify or resolve one, a producer records a new finding with supersedes pointing to the previous one. The last record in the chain is the current finding. A finding MUST have at most one successor, and a resolution listed in resolvedBy counts only once a decision with gate finding-resolution confirms it (R14).
• A finding with cause spec-gap SHOULD be resolved by a new intent version whose new criterion describes the expected behaviour. The fix is then an artifact, and its evidence follows the normal path.
• A finding with cause implementation or test-gap SHOULD be resolved by evidence with result pass for the violated criterion, recorded after the fix.

{
  "ois": "0.1", "type": "finding", "id": "https://ois.acme.example/findings/FND-18",
  "createdAt": "2026-11-03T07:40:00Z",
  "intent": "https://ois.acme.example/intents/INT-142@1",
  "subject": "https://ois.acme.example/artifacts/ART-305",
  "source": "production",
  "severity": "high",
  "summary": "Address change to a Liechtenstein postcode aborts the premium calculation",
  "observedAt": "2026-11-02T18:12:00Z",
  "reportedBy": "https://ois.acme.example/actors/support-4b1e",
  "ticket": "https://jira.acme.example/browse/PORTAL-1302",
  "cause": "spec-gap"
}

4.8 Bundle

A bundle transports records together. It has the fields ois, type (value bundle), id, createdAt and records (array of records, REQUIRED). A bundle adds no meaning beyond its contents and MAY be signed (section 8.3).