Ricardian Contract Spec v1

Legibility by construction

Every action facilitated by Ambr produces a dual-format Ricardian Contract — the same agreement expressed as human-readable legal prose and machine-parsable JSON, bound by SHA-256. Legible actions can be audited, defended, and amended. Agents grounded in dual-format contracts stay defensible as governance standards harden — for their principals, their counterparties, and the platforms that host them. Ambr provides that grounding so agents you deploy today are still defensible tomorrow.

Contract shape

Every contract produced by Ambr is a pair: a human-readable legal prose document and a machine-parsable JSON document describing the same agreement. The two are linked by a single SHA-256 hash that covers both payloads.

Required JSON fields:

• contract_id — format amb-YYYY-NNNN
• template — template slug (consumer a1–a3, delegation d1–d3, commerce c1–c3, one-sided power of attorney p2)
• template_version — integer, monotonically increasing per template
• principal_declaration — { agent_id, principal_name, principal_type }
• parameters — object conforming to the template's parameter schema
• sha256 — hash of the canonical encoding (see below)
• created_at — ISO 8601 UTC

Optional:

• parent_contract_hash — SHA-256 of a parent contract, required when amendment_type is present
• amendment_type — original | amendment | extension

Hash scheme

The sha256 field is computed from two inputs: (a) the human-readable prose exactly as stored, and (b) the machine-readable object with sha256 excluded. Canonicalize (b) by sorting object keys lexicographically at every depth — arrays keep their order — and serializing with ECMAScript JSON.stringify (no insignificant whitespace between tokens). Join the two payloads with the literal five-byte separator "\n---\n" (LF, three hyphens, LF), hash the UTF-8 bytes with SHA-256, and encode the digest as 64 lowercase hex characters:

sha256_hex( utf8( prose + "\n---\n" + canonical_json ) )

Reference implementation (Node.js) — any party can recompute the hash without calling Ambr:

const { createHash } = require('crypto');

const sortKeys = (o) =>
  Array.isArray(o) ? o.map(sortKeys)
  : o && typeof o === 'object'
    ? Object.fromEntries(Object.keys(o).sort().map((k) => [k, sortKeys(o[k])]))
    : o;

// The API serves machine_readable without an embedded sha256 field. If your
// copy carries one (per the data model above), exclude it before hashing:
const { sha256, ...doc } = machineReadable;

const hash = createHash('sha256')
  .update(prose + '\n---\n' + JSON.stringify(sortKeys(doc)), 'utf-8')
  .digest('hex');

A verifier recomputes the hash over the two payloads it received. A match proves the prose and the JSON refer to the same agreement — the basis of the legibility guarantee — and requires no trust in Ambr as an intermediary.

JSON example (abbreviated)

{
  "contract_id": "amb-2026-0042",
  "template": "d1-agent-delegation",
  "template_version": 3,
  "principal_declaration": {
    "agent_id": "agent-abc",
    "principal_name": "Acme Corp",
    "principal_type": "company"
  },
  "parameters": {
    "spend_limit_usd": 500,
    "duration_days": 30
  },
  "sha256": "f8c3…",
  "created_at": "2026-04-20T14:22:19Z"
}

Declaring compliance

Third-party A2A or MCP implementations can declare compliance with this format by including the URN in their compliesWith field:

"compliesWith": ["urn:ambr:ricardian-v1"]

A minimal JSON-LD context for contract payloads:

{
  "@context": {
    "ambr": "https://ambr.run/context/ricardian#",
    "urn": "urn:ambr:ricardian-v1"
  }
}

Licensing

The spec, the URN namespace, and the reference template catalogue are MIT licensed. Ambr encourages alternative implementations — convergence on a shared contract format is the point. Templates live in the Ambr repository under /open-source/.

Versioning

This is version 1 of the spec. Breaking changes will be published under a new URN (e.g. urn:ambr:ricardian-v2). Non-breaking additions land under the same URN with a bump to platformVersion on the discovery endpoints.

Contact

Questions, proposals, or federation intent: governance@ambr.run.