Schemas
You define the criteria schema, the completion schema, and the deterministic field mappings. AGLedger validates inbound records and completions against your schemas, chains the signed result, and publishes the canonical predicate shapes that any verifier can resolve. The engine ships with no built-in contract types — you define them.
JSON Schema draft-2019-09 · RFC 8785 manifest digest · in-toto v1 Statement
Last updated: 2026-05-26 · API v0.25.4
The contract type
Three parts: record schema, completion schema, rules config
A contract type is registered with a stable identifier, a version, and three content fields. The shape is the same whether the type is authored via API or imported from a peer Server.
recordSchema (required)
JSON Schema (draft-2019-09) describing the structured criteria for an assignment of this type. Required fields, value ranges, enums, formats. Inbound records are validated against this schema before the signed entry hits the chain — bad shape never gets notarized.
completionSchema (optional)
JSON Schema describing the structured evidence the performer submits to terminate the record. The presence or absence of this field is what splits the two AGLedger paths.Omit it and the type is Notarize-only: the record reaches RECORDED and there is nothing to verify. No completion endpoint, no verdict, no Settlement Signal.Provide it and the type is Verify-eligible: performers submit signed completions, the principal renders accept or reject (or the rules engine does it in auto mode), and a Settlement Signal fires on terminal verdict.
rulesConfig (optional)
Field mappings that the rules engine can evaluate deterministically for auto-mode verification. Each mapping names a path into the record criteria, the corresponding path into the completion evidence, an optional tolerance field, and a value type drawn from a closed enum: number, denomination, string, boolean, datetime, expression. The principal is still the judge; the mappings are the mechanical convenience layer.
Type identifiers may not begin with the reserved ACH- prefix. Use your own namespace — e.g. ACME-LEGAL-REVIEW-v1 or LOGISTICS-DOT-v1.
Registration
Two paths to register a contract type
Both paths produce the same row in the schema registry, the same canonical manifest, and the same content-addressed digest. Pick whichever fits your operating model.
API — POST /v1/schemas
Submit the registration body with inline JSON Schemas. The request requires the schemas:admin scope — schema authority is a separation-of-duties role. The engine synthesizes a canonical manifest from the registration body, computes the digest, and writes the row. Subsequent versions are tracked under the same type identifier with a configurable compatibility mode (none, backward, forward, full).
YAML provisioning — declared at startup
Drop schema files into a provisioning directory and let the engine reconcile them at boot or on POST /v1/admin/provisioning/reload. Useful for GitOps deployments, multi-environment setups, and pipelines that recreate environments from config. Full walkthrough on the YAML provisioning guide.
Response includes the synthesized canonical manifest and the manifest_digest — the value that identifies this exact schema content across every AGLedger Server that holds it.
Predicate profiles
in-toto predicate kinds, schema-discoverable
Every Signed Statement in the chain is a tagged COSE_Sign1 envelope (RFC 9052, tag 18) over a deterministically CBOR-encoded in-toto v1 Statement payload (RFC 8949 §4.2.1). Inside that Statement, the predicateType field tells the verifier which body shape to expect — a URI of the form https://agledger.ai/predicates/{kind}/v1.
AGLedger publishes seven first-class predicate kinds. Each corresponds to a distinct event category on the chain. The canonical JSON Schema for every kind is generated from the engine's runtime body shape at module load — drift between published schema and emitted payload is impossible by construction.
| Kind | What it carries |
|---|---|
record-state | Lifecycle transitions on a record (create, accept, complete, fulfill, fail, expire, cancel). |
settlement-signal | SETTLE / HOLD / RELEASE emitted on terminal verdict, with the downstream authorization context. |
vault-checkpoint | Periodic signed checkpoint anchoring vault chain head for external attestation. |
tenant-read | Read attestation — who fetched what, when. Forensic accountability for sensitive lookups. |
counter-attestation | Counterparty co-signed assertion on a federated event — bilateral signal anchor. |
federation-projection | Peer-Server event projected into the local chain so the local audit trail is complete. |
schema-event | Schema registry lifecycle — registration, version bump, lifecycle status change. |
Two unauthenticated discovery endpoints expose the catalog:
GET /predicatesIndex of every kind, its predicate URI, and the schema fetch URL on this deployment.GET /predicates/{kind}/v1The canonical JSON Schema (draft-2019-09) for that kind's predicate body, served as application/schema+json.DSSE bundle exports at /v1/records/{id}/attestation reference these URIs in their predicateType field, so sigstore-compatible tooling can resolve the schema for verification without any AGLedger-specific knowledge.
Content addressing
Manifest digest is the share key
Every registered contract type carries a manifest_digest of the form sha256:<hex>. The manifest body is canonicalized via RFC 8785 (JSON Canonicalization Scheme) and hashed with SHA-256. Two engines that hold byte-identical manifest bodies compute byte-identical digests, regardless of authoring path.
There is no central catalog. When a federated record arrives referencing a schema by manifest digest, the receiving Server checks whether it already holds that exact content. If yes, validation proceeds. If no, the operator imports the manifest body once via POST /v1/schemas/import and the digest match unlocks every future record that references it. No vendor registry, no DNS lookup, no third-party dependency.
Every row is tagged with its trust class — local when authored on this engine, imported when loaded from a peer's exported manifest. The distinction is durable on the row; auditors can always tell which Server originated a schema definition.
Row-only metadata — federatable, default_share, co_sign_required — deliberately lives outside the canonical manifest body. Two operators can hold the same schema content under different sharing policies without breaking digest equality.
What this enables
What customer-defined schemas enable
Because the engine ships with no built-in contract types, there is no AGLedger-flavored taxonomy to bend your business around. A legal team registers privilege-review schemas. A lab registers test-protocol schemas with reading-window tolerances. A logistics operator registers DOT compliance checkpoints. A content-moderation pipeline registers decision-record schemas with closed-enum verdict categories. The shape of the work is whatever your domain says it is; AGLedger validates against it and chains the signed result.
The same mechanism carries cross-organization vocabulary. Two counterparties agree out-of-band on a contract type body, both register it on their own Servers, and the matching manifest digest is what lets each side validate inbound records from the other. Vocabulary alignment by digest equality, not by central catalog.
AGLedger is the interface, not the vocabulary vendor. We publish the predicate profiles that describe how the chain itself moves — record-state, settlement-signal, vault-checkpoint, the rest of the seven — and we validate that your customer-defined contract types are well-formed JSON Schema. Everything between those two surfaces is yours.
Related capabilities
Contract types drive Verify mode — the schema is what a verifier evaluates the submitted Completion against.
Cross-org workflows pin a content-addressed manifest digest so both Servers validate the same contract version byte-for-byte.
The /predicates and /v1/schemas routes that publish predicate kinds and contract definitions for discovery.
Predicate profiles carry the crypto identity that lets verifiers check whether a predicate-bearing record was issued by an authorized Server.
Why predicate discovery is a first-class endpoint and how schemas become the contract agents reason about.