usertrustdocs site github
all docs
Reference

JSON Schemas

Published JSON Schemas for trust receipts and audit chain events, with stable $ids.

usertrust publishes JSON Schema (draft 2020-12) definitions for its two public interop shapes: the receipt returned by every governed call, and one persisted line of the hash-chained audit log. The $id URLs are stable — pin them in validators, CI checks, or any tool that consumes receipts or audit logs.

Schema$idDescribes
Trust Receipt v1receipt.v1.schema.jsonThe TrustReceipt returned by every governed call
Trust Receipt v2receipt.v2.schema.jsonv1 plus root-level additions: the four-tier usage split, pricing (appliedRates, tableVersion), and cacheWrite1h (present only when the call wrote 1-hour cache) — see Pricing
Audit Event v1audit-event.v1.schema.jsonOne line of the audit chain (.usertrust/audit/*.jsonl)

Versioning

Validating a receipt

With ajv v8 (npm install ajv ajv-formats):

typescript
import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";

const schema = await fetch("https://usertrust.ai/schemas/receipt.v1.schema.json").then((r) =>
  r.json(),
);

const ajv = addFormats(new Ajv2020());
const validate = ajv.compile(schema);

if (!validate(receipt)) {
  console.error(validate.errors);
}

No validator handy? The schemas are plain static JSON — fetch one and read required / properties directly. String formats (date-time, uuid) are annotations; ajv-formats enforces them, other validators may not.

Schema validation checks shape, not integrity. To check an audit log's hash chain and sequence continuity, run the zero-dependency usertrust-verify package against the vault. It works offline. Without an external anchor, a log rewritten together with its sidecar still passes; Verification says what the check does and does not catch.

privacy