# Extending CrawlCheck documents, v1

Status: published 8 October 2026. Registry: /spec/extensions.json (signed). Proposals: https://github.com/emmanuelorta/crawlcheck/issues

## Rules every consumer follows
1. Ignore fields you do not know, at any depth. Verify the signature over the whole document either way: a field you ignore is still covered by it.
2. Never drop or rewrite fields when you store or forward a signed document; the signature is over the exact bytes of the canonical form.
3. An unknown decision value is treated as the most cautious one you know: block for connect, transact and administer, warn for read and cite.
4. An unknown status value is never treated as good, allowed or measured.
5. A document's `v` changes only when a field changes meaning or is removed. Adding fields, sections or enum values is a minor version of the spec, and old consumers keep working by rules 1, 3 and 4.

## How a field becomes part of a spec
| stage | what it means |
|---|---|
| proposed | an issue titled `Extension: <name>`: the documents it touches, each field with a JSON Schema, why an agent needs it, what it costs to measure, and what it reveals about people (it must reveal nothing about a visitor or a customer) |
| provisional | registered here after 14 days of public comment; it may change, and it appears under `ext` (below) |
| stable | moved into the document in a minor version, recorded in the spec's change log |
| deprecated | still served for at least 180 days, marked in the registry with its replacement |
| removed | gone; removing a stable field is a new `v` |

Criteria for accepting: an agent would decide differently with it; it is measured or declared, never inferred about a person; it can be verified by someone other than CrawlCheck, or its evidence is kept and signed.

## Fields from others
Anyone publishing a document in one of these formats (a mirror, an observer, a site's own staple) may add fields under `ext`, an object keyed by a domain the publisher controls: `"ext": {"example.com": {...}}`. Consumers ignore `ext` keys they do not know. CrawlCheck never reads instructions from `ext`.

## Documents covered
See /spec/extensions.json for each document, its current version, spec and schema.