Open spec v0.1 · draft · 2026-11-21

The Fact Ledger

A tiny, open standard for a business to publish what is true about itself — signed, versioned and linked to evidence — at a well-known URL any AI assistant or agent can fetch and verify.

AI answers can be wrong about a business: old prices, closed locations, discontinued features, departed founders. Today the usual fix is to change a page and wait for the next crawl to pick it up. The Fact Ledger gives models and agents a single, machine-readable, verifiable source of first-party claims — and gives businesses a place to correct the record.

Make one now

Everything runs in your browser. Nothing is uploaded.

Sign it locally with the CLI (from a copy of the repository) so your private key never leaves your machine: node bin/earncitations.mjs ledger keygen then ledger sign facts.json --key facts.key.

1. Discovery

A Fact Ledger for the origin https://example.com MUST be served at:

https://example.com/.well-known/facts.json     # the ledger (application/json)
https://example.com/.well-known/facts.pub      # the signing public key (base64url, one line)

Publishers SHOULD also advertise it from their HTML and JSON-LD so crawlers that never request well-known paths still find it:

<link rel="alternate" type="application/json" href="/.well-known/facts.json" title="Fact Ledger">

…and list it in /llms.txt under a ## Facts section. Serving the key from the subject's own origin is what binds the ledger to the domain; a key embedded in the document only proves integrity, not authorship.

2. Document format

Machine-readable: fact-ledger-0.1.json (JSON Schema 2020-12). Semantic rules the schema can't express — no instructions to AI in claims, signature verification, correctFact references — are enforced by the reference validator.

FieldTypeReq.Meaning
versionstring✓"0.1"
subjectobject✓name, url (origin), type (schema.org type), optional description, logo, sameAs[]
issuedISO 8601✓When this version was signed
factsFact[]✓First-party claims, see §3
correctionsCorrection[]Known false statements and the fact that corrects them, see §4
signatureobjectSHOULDEd25519 signature over the canonical document, see §5

3. Facts

FieldTypeReq.Meaning
idstring✓Stable, lowercase, dotted — pricing.starter, hours.riverside.sat
claimstring ≤ 280✓One self-contained sentence a model can quote verbatim. Name the subject; avoid pronouns.
categoryenumidentity · offering · pricing · location · hours · contact · people · policy · metric · integration · compliance · other
valueany JSONStructured form of the claim, e.g. {"amount":29,"currency":"USD","per":"user/month"}
evidenceURL[]✓Public pages a human can check. Empty arrays are allowed but down-weighted.
validFrom / validUntilISO 8601When the claim is true. Expired facts MUST NOT be presented as current.
Write claims for quotation. "Northwind's Starter plan costs $29 per user per month, billed monthly." beats "Starter: $29". A quoted sentence keeps its meaning; a fragment loses it.

4. Corrections

A place to name the specific falsehood AI keeps repeating, and the fact that corrects it.

{
  "incorrect": "Northwind does not support Gmail",
  "correctFact": "integrations.gmail",
  "seenIn": ["chatgpt", "perplexity"],
  "firstSeen": "2026-10-02"
}

correctFact MUST reference a fact id in the same ledger.

5. Signing

  1. Remove the signature member.
  2. Canonicalize with JCS (RFC 8785): object keys sorted by code point, no insignificant whitespace, standard JSON number and string serialization; members whose value is undefined are omitted.
  3. Sign the UTF‑8 bytes with Ed25519.
  4. Add signature: { alg: "Ed25519", canonicalization: "JCS", keyId, publicKey, keyUrl, sig } where publicKey and sig are base64url and keyId is "ed25519:" + base64url(sha256(rawKey))[0:16].

Any edit invalidates the signature; re-sign after every change. Keep the private key out of your repository.

6. Verification

  1. Fetch /.well-known/facts.json from the origin in question. Reject it if subject.url's host differs from the origin (ignoring a leading www.).
  2. Validate structure (§2–4).
  3. Fetch /.well-known/facts.pub from the same origin over HTTPS. If present, it is the trusted key; the embedded publicKey MUST equal it.
  4. Verify the Ed25519 signature over the canonical bytes with the trusted key (or, lacking one, the embedded key — which proves integrity only).
  5. Result: authenticated (domain-bound key, valid signature), intact (valid signature, unbound key), or unverified.

7. Guidance for AI assistants and agents

8. Security considerations

9. Reference implementation

From a copy of the EarnCitations repository (Node 22, no dependencies; the npm package isn't published yet):

node bin/earncitations.mjs ledger init --name "Northwind CRM" --url https://northwind.example
node bin/earncitations.mjs ledger add facts.json --id pricing.starter --category pricing \
    --claim "Northwind's Starter plan costs \$29 per user per month." \
    --evidence https://northwind.example/pricing
node bin/earncitations.mjs ledger keygen --out facts.key
node bin/earncitations.mjs ledger sign facts.json --key facts.key
node bin/earncitations.mjs ledger verify northwind.example

See ours: /.well-known/facts.json · /.well-known/facts.pub