Define your own contract types
AGLedger has one primitive: a signed record spanning the full lifecycle of a piece of work. The contract type - and whether it declares a completion schema - is what decides which lifecycle that record runs. You define both. The engine validates inbound records and completions against your schemas, then signs and chains the result. AGLedger ships with no built-in contract types. You define them.
This is the same idea behind the rest of the developer story: the agent integrates itself against the API, and you do not build a bespoke attestation or schema layer to make your domain fit ours. The shape of the work is whatever your domain says it is.
JSON Schema draft-2019-09 · RFC 8785 manifest digest · in-toto v1 Statement
Last updated: 2026-06-29 · API v1.2.0 · How-to: /docs/guides/schemas
The contract type
One type definition, two lifecycles
A contract type is registered with a stable identifier, a version, and its schema content. There is one primitive underneath - the signed record - and the contract type configures it. The presence or absence of a completion schema is what selects the lifecycle the record runs.
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 lifecycles.Omit it and the type is Notarize-only: the record terminates at RECORDED in one signed call - the on-ramp. No completion endpoint, no verdict, no Settlement Signal.Provide it and the type runs the gated lifecycle: 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 still renders the verdict; the mappings are the mechanical convenience layer.
No prefixes are reserved - an organization owns its entire type namespace. Use whatever convention fits, e.g. ACME-LEGAL-REVIEW-v1 or LOGISTICS-DOT-v1.
What gets signed
The agent reports; the notary signs
Your schemas define the body of what is reported. The signing is the engine's. AGLedger signs each entry with the instance key, naming the accountable principal and acting credential inside the signed payload. Agents and principals are not required to hold signing keys - there are no per-principal keys to mint, rotate, or guard. The authority is the principal's; the signature is the notary's.
That is why you can define an arbitrary schema and still get audit-grade attribution: the cryptographic guarantee comes from the instance key over a canonical payload, while your schema decides only what the payload carries. The two never collide.
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. The step-by-step walkthrough lives in the schemas guide; this page owns the why.
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. These are the Predicate Profiles: the in-toto predicate kinds AGLedger itself publishes for how the chain moves, served as JSON Schema.
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 - no central catalog
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. That digest is how peers share a vocabulary without anyone running a registry.
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.
Why customer-defined
No built-in contract types, by design
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
A completion schema drives the gated lifecycle - the schema is what the rules engine 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.
The instance key signs every entry, naming the principal inside the payload - how verifiers check 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.