The Format

This is the page to link when you say “the OLOBOLO format”. The format is deliberately small, frozen, and independently implementable — the normative definition ships with the open-source chain package (FORMAT.md in olobolo-com/chain), and this page summarizes it.

Design constraints

1. Frozen: the serialization of schema_version: "0" never changes. Evolution happens only by introducing a new schema version; old entries always verify against their own version.
2. Reimplementable in an afternoon: canonical JSON + SHA-256, no exotic primitives. If it can’t be independently reimplemented, it can’t be independently verified.
3. Metadata only: the payload shapes have no fields for source code, prompts, spec text, review comments or test output — the format makes the privacy promise structural.

Canonical serialization (v0)

Canonical form is JSON, compatible with RFC 8785 (JCS) restricted to a stricter subset:

• object keys sorted by UTF-8 byte sequence, ascending;
• UTF-8, no BOM, no insignificant whitespace;
• integers and strings only — decimals travel as strings, so float representation can never change a hash;
• timestamps as RFC 3339 UTC with millisecond precision;
• omitted fields are omitted, never null.

Entries and chaining

Each entry is an envelope + payload:

entry_hash = sha256(canonical(envelope))
envelope   = { algo, schema_version, event_type, payload_hash,
               prev_entry_hash, occurred_at, org_id, repo_id }
payload_hash = sha256(canonical(payload))

prev_entry_hash links each entry to its predecessor; the genesis predecessor is 64 zeros. Five event types are defined (change.authored, spec.linked, change.reviewed, test.evidenced, release.sealed) — their payload shapes are listed in the API reference, generated from the same contracts the server enforces.

Seals and segments

A release.sealed payload fixes a segment: first entry hash, last entry hash, and chain_hash = SHA-256 over the segment’s entry hashes in order. Reports, attestations and quarterly data-room packs are all derived from sealed segments — deterministically.

Test vectors

The chain package publishes chained test vectors (three per event type) plus an independent cross-check: any implementation that reproduces the vectors’ entry hashes and chain head implements v0 correctly. The verifier’s selftest runs exactly this.

in-toto mapping

Sealed segments export as in-toto Statements (Attestation Framework v1) under the predicate type https://olobolo.com/attestation/provenance/v0 — subject digest is the segment’s recomputable chain_hash, the predicate carries the segment’s authorship/review/test figures, and a reserved agent_trace field awaits the emerging AI-agent-trace standards. Full mapping: ATTESTATION.md in the chain package. Statements ship unsigned in v0: integrity comes from the chain itself plus RFC 3161 anchors, and every figure is recomputable from the export — which beats a signature from an unmanaged key.