docs(protocol): add reference-data design principle (own the namespace, not the corpus)

[bokelley]

Why

This codifies the boundary we worked through after declining the AAO geo-metro registry proposal (#5627, closed): a protocol should own the namespace and the resolution contract for reference data, not the underlying corpus of code↔name tables — unless AdCP itself mints the values. It exists so the next reference-data RFCs (postal #5383, places #5588, app/property lists) are decided by a reusable rule instead of re-litigated case by case.

What

Adds supporting principle 8 — "Reference data: own the namespace and the resolution contract, not the corpus" to docs/protocol/design-principles.mdx, following the page's existing rule / why / what-it-rules-out / when-you'd-push / reviewer-test structure, and bumps the "five → six supporting principles" counts.

The principle:

• Own: the namespace (which classification systems exist, ID shape) and the resolution contract (resolve against a declared source, surface ambiguity, never infer an identifier from training data).
• Don't own: the code↔name tables, unless AdCP is itself the authority (cites v1-canonical-mapping.json as the one legitimate "we mint both sides" case).
• Defer to external authorities (ISO, Eurostat NUTS, ONS ITL, GeoNames); a thin generated mirror is allowed only when the source is open and the projection is non-authoritative.

Notes that the protocol already does this right on the read side (geo-delivery-metrics carries geo_name beside geo_code), and reuses the anti-centralization framing of principle 5.

Review

Reviewed by docs-expert, ad-tech-protocol-expert, code-reviewer, and security-reviewer. Every factual claim was verified against the schemas (geo-delivery-metrics, targeting, v1-canonical-mapping, capabilities); three should-fixes addressed (the "closed→additive" correction, optional-geo_name, "Albany names two DMAs (NY and GA)").

No changeset: docs/protocol/ is not a PROTOCOL_SCOPED_PATH, so this is a non-protocol docs change (an empty changeset would trip the gate).

Related: closes the framing question behind #5627; decision recorded buyer-side in scope3data/agentic-api#4576.

🤖 Generated with Claude Code

[aao-release-bot]

Adds supporting principle 8 to the design-principles page; clean docs-only change that codifies the reference-data boundary instead of re-litigating it per RFC. Right call to write down the rule once — own the namespace and resolution contract, defer the corpus — so #5383, #5588, and the app/property RFCs inherit a decision instead of reopening one.

Things I checked

• Every load-bearing factual claim against the actual schemas, not the prose:
  • geo-delivery-metrics.json:37 lists geo_code in required; geo_name sits in properties (L30) but not required. The "optional geo_name beside required geo_code" claim holds.
  • v1-canonical-mapping.json is AAO/AdCP-authored ("Authoritative AAO-published mapping") and additive — its governance note states "Entries are additive; once published they are not removed (they may be marked deprecated: true if superseded)." The "we mint both sides, set is additive" framing is accurate.
• Intro arithmetic: principles 1–2 lead, 3–8 are the supporting set. "Five → Six supporting principles" and the new ### 8. header are consistent (L50–L121 carry 3–7, new block adds 8).
• Changeset gate: docs/protocol/ is deliberately absent from PROTOCOL_SCOPED_PATHS in scripts/check-changeset-protocol-scope.cjs:8-19 (only docs/reference/ is gated, L12). The PR's "no changeset, empty changeset would trip the gate" reasoning is correct — no wire-touching path changed.
• No static/schemas/source/** touched, so no spec-vs-docs drift surface and no ad-tech-protocol-expert trigger.

Triage: docs-only (docs/protocol/*.mdx, no schema or reference paths) → skip-everything list, no experts. Verified the factual claims directly since the principle leans on schema reality.

Minor nits (non-blocking)

1. "reference-data RFCs (postal #5383, places #5588, app/property lists)". The PR body names these as the consumers of the rule, but the principle text itself doesn't link them — a reader landing on principle 8 cold won't see the pending RFCs it's meant to adjudicate. Worth a one-line "see also" if those RFCs cite back to this principle.

LGTM. Nit noted, non-blocking.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
adcp	🟢 Ready	View Preview	Jun 25, 2026, 8:37 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.