Quick-start · implementer / developer

Goal: build against the standard and stay byte-compatible with the reference cores.

The contract

• Payload schema (JSON Schema 2020-12) and the JSON-LD context.
• Canonicalization is RFC 8785 (JCS); the integrity hash is SHA-256 over the canonical bytes. This is the anti-fork keystone - two conformant implementations MUST produce byte-identical canonical JSON and the same hash.
• The conformance vectors are the oracle: canonical bytes, hashes, golden embedded PDFs, negatives, and a differential-fuzz corpus. Reproduce them exactly.

Reference implementations

Published packages: openom-core on PyPI, openom-js on npm.

pip install openom-core      # Python: embed/read/inspect/extract/validate
npm  install openom-js       # TypeScript: byte-parity with the Python core

First success: embed → read → validate

TypeScript:

import { embedPayload, readPayloadFromBytes, validatePayload } from "openom-js";

const out = await embedPayload(pdfBytes, payload);   // non-destructive; page content untouched
const r = await readPayloadFromBytes(out);           // r.payload is typed (OMPayload)
const { errors } = validatePayload(payload);          // 0.1 schema is bundled - no schema file needed
if (errors.length) throw new Error("schema errors block");

Python:

from openom_core import embed, read, validate

out = embed(pdf_bytes, payload, asserted_date=payload["assertedDate"])
r = read(out)                       # r.present, r.hash_valid, r.payload
report = validate(r.payload)        # defaults to the bundled 0.1 schema
assert report.ok                    # schema errors block; warnings never do

More runnable snippets (webhook receiver, consumer read) live in examples/.

Validation model

Two tiers: schema errors block; consistency warnings never block; market truth is out of scope forever. See the code catalog for every code, its message and requirement, and the requirement reference for every OM-* clause. Enable full format assertion (ajv-formats mode:full / jsonschema FormatChecker) to reproduce conformance outcomes.