Standard annotation types

The most open-ended type. Use it to record what a field or structure actually means to the people who use it — the kind of knowledge that lives in a senior engineer's head, not in the schema. A `status` field with values like `inactive` means different things to billing, support, and security; this is where each interpretation gets written, with attribution.

{ "field": "status", "value": "inactive", "meaning": "User has cancelled their subscription but data is retained for 90 days per legal policy.", "domain": "billing" }

A typed endorsement with evidence. Unlike a simple thumbs-up, a trust signal carries a reason: tested in production, audited by a specific team, provenance verified. Readers weigh signals from accounts they trust more heavily than anonymous assertions.

{ "claim": "production-tested", "evidence": "Validated against 2M records in the billing pipeline, zero schema violations.", "verdict": "reliable" }

Answers the question: who is using this, and how? A usage report records that a specific project consumes a schema — which fields it reads, which it ignores, which language and validator it uses. This is the layer's telemetry: not what the schema is, but what people actually do with it.

{ "project": "billing-service", "language": "elixir", "validator": "ex_json_schema", "fields_used": ["id", "email", "status"], "fields_ignored": ["internal_notes"] }

When a schema moves from v1 to v2, the migration guide annotation says what changed, what breaks, and what to do. Attached to a version (not a schema), it's the upgrade manual that travels with the contract — so the agent resolving a new version sees the migration path, not just the diff.

{ "from_version": "1.0.0", "to_version": "2.0.0", "breaking": true, "changes": ["email is now required", "metadata removed"], "upgrade": "Add email validation before migrating; move metadata to a sidecar table." }

Points at where the definition came from — an RFC, a regulatory document, an internal design doc, a database migration. An annotation without provenance is an opinion; an annotation with a source attestation is a citation. This is how the context layer stays auditable.

{ "source": "https://example.com/rfcs/user-model-v2", "source_type": "rfc", "relationship": "derived-from", "note": "Field names and required constraints follow RFC 2 §3.1." }

The graph type. A semantic link connects one subject to another — a schema to its successor, a field to its equivalent in another schema, an annotation to the doc that explains it. This is what makes the context layer a graph rather than a list: relationships are first-class, typed, and resolvable.

{ "target": "acme/schemas/user-profile", "relationship": "supersedes", "note": "Use user-profile for new services; this schema is maintained for compatibility." }

The inverse of every other type: instead of asserting meaning, it asks for it. When an agent or a person hits a field they can't safely interpret, they file a context request instead of guessing. It's the typed version of a TODO — visible, attributable, and resolvable when someone fills it in.

{ "field": "metadata", "question": "What is the structure of the metadata field? It's an object with no properties declared.", "urgency": "blocking" }

An instruction to the next agent or person who opens this subject: before you use this schema, load these other things. It's a manifest for context retrieval — a reading list attached to the contract, so the agent doesn't have to guess what it needs to resolve first.

{ "load_before": ["acme/schemas/billing-period", "acme/annotation-types/retention-policy"], "reason": "This schema references billing-period by ID and applies retention rules from the retention-policy annotation type." }