OSAP Data Model
Status: See Status of This Document.
This document normatively defines the OSAP v0.1 object types. The JSON Schemas in ../schemas/ are authoritative for structure; this document is authoritative for semantics.
1. General Rules
- All OSAP documents are JSON (RFC 8259) encoded as UTF-8.
- All OSAP documents MUST carry the version member
"osap": "0.1", except that the verification result (an output produced by a verifier, not a published document) carries it as an OPTIONAL member. - All timestamps are RFC 3339
date-timestrings. Timestamps SHOULD be expressed in UTC with theZsuffix. - Unknown members are not permitted: every schema sets
additionalProperties: false. Extensions require a new version or a defined extension mechanism (see index.md § 11). - Signed document types (attestation envelope, trust bundle, revocation list when signed) are canonicalized with the JSON Canonicalization Scheme (JCS, RFC 8785) before signing. See envelope.md.
2. Document Types
| Document | Schema | Signed |
|---|---|---|
| Attestation envelope | osap-envelope.schema.json | REQUIRED |
| Issuer metadata | osap-issuer.schema.json | No (integrity via HTTPS + did:web) |
| Trust bundle | osap-trust-bundle.schema.json | REQUIRED |
| Revocation list | osap-revocation-list.schema.json | RECOMMENDED (proof is optional in schema) |
| Transparency log entry | osap-transparency-log-entry.schema.json | Extension area, non-normative |
| Verification result | osap-verification-result.schema.json | No (local verifier output) |
3. Attestation Envelope
Schema: osap-envelope.schema.json. Full semantics and signing procedure: envelope.md.
Required members: osap, id, type, issuer, issued_at, proof.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | MUST | Protocol version. |
id | string | MUST | Stable attestation identifier, e.g. osap:attestation:sha256:<hex>. See envelope.md § Identifier. |
type | enum | MUST | One of SourceAttestation, DerivativeAttestation, CorrectionAttestation, RevocationAttestation, ContextAttestation. |
issuer | issuerRef | MUST | Reference to the signing issuer (see § 3.1). |
subject | subject | OPTIONAL | The asset this attestation is about (see § 3.2). REQUIRED in practice for all types except RevocationAttestation; see claims.md. |
claims | array of claim | OPTIONAL | Claims made by the issuer (see § 3.4). |
issued_at | date-time | MUST | When the issuer states the attestation was issued. |
valid_from | date-time | OPTIONAL | Start of the attestation's stated validity. |
valid_until | date-time | OPTIONAL | End of the attestation's stated validity. |
derived_from | array of derivationRef | OPTIONAL | Lineage references (see § 3.5). |
corrects | string | OPTIONAL | Attestation id corrected by this CorrectionAttestation. |
revokes | string | OPTIONAL | Attestation id revoked by this RevocationAttestation. |
evidence | array of evidenceRef | OPTIONAL | Supporting evidence references (see § 3.6). |
revocation | object | OPTIONAL | Object with required status_url (URI): where the issuer's revocation list is published. |
proof | proof | MUST | Data integrity proof (see § 3.7). |
3.1 issuerRef
Required members: id, key_id.
| Member | Type | Req. | Meaning |
|---|---|---|---|
id | string | MUST | Issuer identifier. v0.1: a did:web identifier. |
name | string | OPTIONAL | Human-readable issuer name. Display only; carries no identity weight. |
key_id | string | MUST | Identifier of the key used to sign, e.g. did:web:publisher.example#key-2026. MUST match proof.verificationMethod. |
3.2 subject
Required members: asset_hashes.
| Member | Type | Req. | Meaning |
|---|---|---|---|
type | string | OPTIONAL | Media type of the asset, e.g. image/jpeg. |
canonical_url | URI | OPTIONAL | Where the issuer states the asset is canonically published. |
title | string | OPTIONAL | Human-readable title. |
asset_hashes | array of assetHash | MUST | One or more fingerprints; MUST contain at least one entry. |
3.3 assetHash
Required members: alg, scope, value.
| Member | Type | Req. | Meaning |
|---|---|---|---|
alg | "sha256" | MUST | v0.1 defines only SHA-256. |
scope | "exact-bytes" | MUST | v0.1 defines only exact-bytes. Perceptual scopes are a future extension area. |
value | string | MUST | Lowercase hexadecimal digest (^[0-9a-f]+$). For SHA-256 this is 64 characters. |
3.4 claim
Required members: type.
| Member | Type | Req. | Meaning |
|---|---|---|---|
type | string | MUST | Claim type, e.g. published_by. See claims.md for the baseline registry. |
value | any | OPTIONAL | Claim value; type depends on the claim type. |
note | string | OPTIONAL | Free-text explanation by the issuer. |
Note (non-normative): Verifying an attestation establishes that the issuer signed the claim, not that the claim is true.
3.5 derivationRef
Required members: attestation_id.
| Member | Type | Req. | Meaning |
|---|---|---|---|
attestation_id | string | MUST | id of the attestation covering the source asset. |
relation | enum | OPTIONAL | One of crop, resize, transcode, excerpt, translation, composite, other. |
note | string | OPTIONAL | Free-text description of the transformation. |
3.6 evidenceRef
Required members: type.
| Member | Type | Req. | Meaning |
|---|---|---|---|
type | string | MUST | Kind of evidence, e.g. official-statement, archived-publication. |
url | URI | OPTIONAL | Where the evidence can be inspected. |
note | string | OPTIONAL | Free-text explanation. |
3.7 proof
Required members: type, cryptosuite, created, verificationMethod, proofPurpose, proofValue.
| Member | Type | Req. | Meaning |
|---|---|---|---|
type | "DataIntegrityProof" | MUST | Fixed in v0.1. |
cryptosuite | "eddsa-jcs-2026" | MUST | Ed25519 over JCS canonical form. Fixed in v0.1. |
created | date-time | MUST | When the proof was created. |
verificationMethod | string | MUST | Key identifier resolvable via issuer metadata, e.g. did:web:publisher.example#key-2026. |
proofPurpose | "assertionMethod" | MUST | Fixed in v0.1. |
proofValue | string | MUST | Unpadded base64url encoding of the raw 64-byte Ed25519 signature. |
The signing input is defined in envelope.md § Canonicalization and Signing.
4. Issuer Metadata
Schema: osap-issuer.schema.json. Served at https://<domain>/.well-known/osap.json. Full semantics: identity.md.
Required members: osap, id, keys.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | MUST | Protocol version. |
id | string | MUST | Issuer identifier. v0.1: did:web. |
name | string | OPTIONAL | Human-readable issuer name. |
keys | array of publicKey | MUST | One or more signing keys; MUST contain at least one entry. |
revocations_url | URI | OPTIONAL | Where the issuer's revocation list is published. |
outbox_url | URI | OPTIONAL | Where the issuer publishes a feed of its attestations. |
lookup_url | URI | OPTIONAL | Base URL of the issuer's hash lookup API (see discovery.md). |
4.1 publicKey
Required members: id, type, publicKeyMultibase.
| Member | Type | Req. | Meaning |
|---|---|---|---|
id | string | MUST | Key identifier, e.g. did:web:publisher.example#key-2026. |
type | "Multikey" | MUST | Fixed in v0.1. |
publicKeyMultibase | string | MUST | Multibase base58btc (z...) encoding of the ed25519-pub multicodec prefix 0xed 0x01 followed by the 32-byte Ed25519 public key. |
valid_from | date-time | OPTIONAL | Start of the key's validity. |
valid_until | date-time | OPTIONAL | End of the key's validity. See security-considerations.md on expired keys vs historical validity. |
5. Trust Bundle
Schema: osap-trust-bundle.schema.json. Full semantics: trust-bundles.md and temporal-trust.md.
Required members: osap, type, id, maintainer, issued_at, entries, proof.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | MUST | Protocol version. |
type | "TrustBundle" | MUST | Fixed. |
id | string | MUST | Bundle identifier, e.g. trustbundle:basic-example:v0.1. |
maintainer | object | MUST | Required id (string); optional name (string). |
description | string | OPTIONAL | Human-readable description of the bundle's policy. |
issued_at | date-time | MUST | When this bundle version was issued. |
expires_at | date-time | OPTIONAL | When this bundle version should be considered stale. |
entries | array of entry | MUST | Issuer entries. |
proof | proof | MUST | Same proof structure as § 3.7, signed by the maintainer. |
5.1 entry
Required members: issuer, trust_periods.
| Member | Type | Req. | Meaning |
|---|---|---|---|
issuer | string | MUST | Issuer identifier this entry applies to. |
trust_periods | array of trustPeriod | MUST | One or more trust periods; MUST contain at least one entry. |
5.2 trustPeriod
Required members: valid_from, status.
| Member | Type | Req. | Meaning |
|---|---|---|---|
valid_from | date-time | MUST | Start of the period. |
valid_until | date-time | OPTIONAL | End of the period; absent means open-ended. |
status | enum | MUST | One of trusted, limited_trust, high_caution, untrusted. |
scope | array of string | OPTIONAL | Claim categories this period applies to. Absent means all categories. |
topics | array of string | OPTIONAL | Topic areas the maintainer associates with this period. |
reason | string | OPTIONAL | Why the maintainer assigned this status. SHOULD be present. |
evidence | array | OPTIONAL | Evidence objects: required type (string), optional url (URI), optional note (string). |
6. Revocation List
Schema: osap-revocation-list.schema.json. Typically published at /.well-known/osap/revocations.json.
Required members: osap, type, issuer, updated_at.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | MUST | Protocol version. |
type | "RevocationList" | MUST | Fixed. |
issuer | string | MUST | Issuer identifier the list belongs to. |
updated_at | date-time | MUST | When the list was last updated. |
revoked_attestations | array | OPTIONAL | Entries with required id (string) and revoked_at (date-time); optional reason (string) and replacement_id (string). |
revoked_keys | array | OPTIONAL | Entries with required key_id (string) and revoked_at (date-time); optional reason (string). |
proof | proof | OPTIONAL | Same proof structure as § 3.7. Issuers SHOULD sign revocation lists. |
7. Transparency Log Entry (Extension Area)
Schema: osap-transparency-log-entry.schema.json. Non-normative in v0.1; see transparency-logs.md.
Required members: osap, type, log_id, index, logged_at, attestation_id, attestation_hash.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | MUST | Protocol version. |
type | "TransparencyLogEntry" | MUST | Fixed. |
log_id | string | MUST | Identifier of the log. |
index | integer ≥ 0 | MUST | Position in the log. |
logged_at | date-time | MUST | When the entry was appended. |
attestation_id | string | MUST | id of the logged attestation. |
attestation_hash | object | MUST | Required alg ("sha256") and value (lowercase hex): digest of the attestation document. |
issuer | string | OPTIONAL | Issuer of the logged attestation. |
asset_hash | string | OPTIONAL | Lowercase hex exact-bytes hash of the subject asset, to support earlier-source queries. |
8. Verification Result
Schema: osap-verification-result.schema.json. Produced locally by verifiers; full semantics: verification.md.
Required members: valid_signature, labels.
| Member | Type | Req. | Meaning |
|---|---|---|---|
osap | "0.1" | OPTIONAL | Protocol version. |
valid_signature | boolean or null | MUST | Whether the proof verified. null when the check could not be performed. |
asset_hash_match | boolean or null | OPTIONAL | Whether the local asset matches a signed fingerprint. null when the asset was not available. |
issuer | string or null | OPTIONAL | Issuer identifier, when known. |
issuer_key_valid | boolean or null | OPTIONAL | Whether the signing key was valid (per issuer metadata) at issued_at. |
revoked | boolean or null | OPTIONAL | Whether the attestation is revoked. null when revocation status could not be checked. |
attestation_id | string | OPTIONAL | The id of the attestation. |
earlier_source | object or null | OPTIONAL | Earlier matching source, when discovered: required issuer, attestation_id, issued_at. |
trust_result | object or null | OPTIONAL | Trust-bundle interpretation (see § 8.1). null when no evaluation was performed. |
labels | array | MUST | Label objects with required level (one of success, info, warning, error, unknown) and text (string). See ui-labels.md. |
8.1 trust_result
Required members: status, bundle.
| Member | Type | Req. | Meaning |
|---|---|---|---|
status | enum | MUST | Trust status at the attestation's issued_at time under the selected bundle: trusted, limited_trust, high_caution, untrusted, outside_bundle, or no_bundle. |
historical_status | enum or null | OPTIONAL | Status at issued_at: trusted, limited_trust, high_caution, untrusted, or null (issuer not covered at that time). |
current_status | enum or null | OPTIONAL | Status at verification time; same values as historical_status. |
scope | array of string | OPTIONAL | Scope of the matched trust period(s). |
bundle | string or null | MUST | id of the bundle evaluated, or null when status is no_bundle. |
Note (non-normative): status is the headline value for the historical evaluation, while historical_status and current_status allow both evaluations to be reported explicitly. When the issuer is absent from the bundle, status is outside_bundle and both detailed statuses are null.