spec(adcp): discriminator audit — every oneOf needs a discriminator key + CI assertion

[bokelley]

Summary

AccountReference = { account_id } | { brand, operator, sandbox? } has no spec-level discriminator. Every adapter we built (and the four reviewer agents) collapsed the union via (ref as { brand?: { domain?: string } }) and silently dropped the account_id arm. Real adopters who wire sync_accounts will hit the gap because buyers reference accounts by account_id post-sync.

This isn't an AccountReference-only issue. Other unions in AdCP 3.x with the same risk:

• BuildCreativeReturn (CreativeManifest | CreativeManifest[] | BuildCreativeSuccess | BuildCreativeMultiSuccess)
• PreviewCreativeResponse (single | batch | variant) ✓ has response_type
• MediaBuyDeliveryNotification variants
• ActivationKey ✓ has type
• AssetVariant ✓ has asset_type
• Format.renders[] items (dimensions vs parameters_from_format_id) — fixed via codegen tightening (feat(dashboard): escalation visibility and invoice draft-confirm flow #1325)
• Every *Success | *Error response union (most of AdCP 3.x)
• AsyncResponseFor<T> family
• SignalID ✓ has source

Some unions have discriminators. Many don't. The ones without push the narrowing burden onto every adopter in every codegen target — TS, Python, Go, Java — and every adopter writes the same buggy cast.

Proposed fix

1. Audit pass: for every oneOf in schemas/cache/latest/, classify:
   • ✓ Has a stable discriminator key (kind, source, response_type, asset_type, output_format, type).
   • ⚠ Doesn't have one but variants have a structurally distinguishing required field (e.g. account_id vs brand on AccountReference).
   • ✗ Variants overlap structurally and need a discriminator added (the dangerous case).
2. Add discriminators to every ⚠ and ✗ union. For AccountReference specifically: add kind: 'account_id' | 'identity' (or similar) so TS/Python/Go can narrow without 'account_id' in ref archaeology. JSON Schema Draft 2020-12 discriminator keyword OR a sentinel propertyName constant per branch.
3. Update the JSON Schema to declare discriminator: { propertyName: 'kind' } on every oneOf. Codegen targets that support discriminators (jsts with the right config, msgspec, openapi-generator) emit narrower types.

CI assertion

Schema-walker on every oneOf that asserts:

• Either discriminator: { propertyName: ... } is set, OR
• Every variant declares the same properties.<key>.const value (and they're distinct across variants).

Output on failure: oneOf at /core/account-ref.json#/ has no discriminator and no shared const-property — add { kind: 'account_id' | 'identity' } or equivalent.

This is a single-pass schema walker. ~50 lines of TS / Python in the spec repo's CI. Catches every regression on every spec PR going forward.

Why on adcp not adcp-client

The audit is on the spec; codegen targets are downstream. Filing on adcontextprotocol/adcp so the discriminator fix lands at the source and propagates to adcp-client (TS), adcp-py, etc.

Acceptance

• Audit table published as a PR description listing every oneOf and its current discriminator status.
• AccountReference gains kind discriminator; codegen produces a properly-narrowed union in TS.
• CI assertion in adcp spec repo fails any PR that adds a oneOf without a discriminator.
• adcp-client's generated TS for AccountReference makes 'account_id' in ref unnecessary.

Refs

• adcp-client PR PricingOption Parameters is a shared type across all pricing models #1373 (review surfaced this on the four hello_*_adapter_*.ts examples)
• adcp-client#1325 (Format.renders[] codegen tightening — same family, different surface)
• adcp-client src/lib/server/decisioning/account.ts AccountStore.resolve JSDoc — documents the canonical narrowing pattern that today requires the cast
• JSON Schema discriminator spec: https://json-schema.org/draft/2020-12/json-schema-validation#section-10.3.1.4

🤖 Generated with Claude Code

[bokelley]

oneOf discriminator audit — static/schemas/source/

Ran a one-pass walker over 524 schema files at static/schemas/source/ (the source-of-truth tree the dist artifacts are built from). 108 oneOf occurrences total.

Counts

Status	Count
✓ discriminated (explicit discriminator.propertyName or shared const-property with distinct values)	35
⚠ structurally narrowable (each variant has at least one unique required property)	34
✗ dangerous (variants overlap; no reliable narrowing)	27
(scalar oneOf — string/number/array etc., N/A for discriminator)	12

Methodology caveats

• One-hop $ref resolution: ref-only variants are reported as ref-only(<path>). Some unions classified as ✗ are actually discriminated inside the ref target (see core/pricing-option.json and core/format.json assets below). Those still merit a fix at the parent oneOf so codegen can narrow without descending into the ref.
• The walker does not verify that any TS/Py codegen actually emits a discriminated union for the ✓ rows — only that the spec carries enough info for it to.

Top ✗ entries — the bugs

These are the unions where a structural cast like ('account_id' in ref) will silently misfire:

1. compliance/comply-test-controller-response.json #/oneOf (7 variants) — every variant only requires success; variant 4 is just {success} and matches anything. Needs a kind discriminator.
2. brand.json #/oneOf (4 top-level shapes) — variant 2 has zero required keys, so it matches every document. Top-level brand.json shape is undefined-by-overlap.
3. brand/acquire-rights-response.json and brand/creative-approval-response.json — success / partial-success / approved-with-conditions all share the same required keys (rights_id, status, brand_id). Adapters can't tell success from pending from partial.
4. core/audience-selector.json #/oneOf (4 variants) — all share type (so the intent is type is the discriminator) but variants don't actually declare type: { const }. Cheapest fix: add the const per variant.
5. core/format.json #/properties/assets/items/oneOf (15 variants, 12 nested) — variants are $ref to per-asset-type schemas that do have an asset_type const. Hoist that into the parent oneOf as discriminator: { propertyName: asset_type } (mirrors the pattern already in core/assets/asset-union.json ✓).
6. core/pricing-option.json #/oneOf (9 ref-only variants) — same shape as fix: remove empty line before frontmatter in creative-formats.md #5; each ref target has a model const. Promote to discriminator: { propertyName: model }.
7. a2ui/bound-value.json #/oneOf (5 variants) — variant 4 requires [literalString, path], which intersects variants 0 and 3. Either drop variant 4 or add kind.
8. pricing-options/cpv-option.json view_threshold #/oneOf (number vs {duration_seconds}) — fine for narrowing-by-typeof in TS, but breaks codegen targets that don't model "scalar | object" cleanly. Wrap the number in {seconds: number} or add kind.
9. Several scalar-vs-object knobs in brand.json / sponsored-intelligence/si-capabilities.json (tone, font_role, voice, video, avatar) — same string|object or boolean|object ambiguity. Pick one shape.
10. Several excluded_by and status_filter unions are enum-ref vs array-of-enum — these are narrowable in TS via Array.isArray(), but they're ambiguous to JSON Schema validators and to Python/Go codegen. Worth tightening anyway.

⚠ structurally narrowable — fine in TS, brittle elsewhere

The 34 ⚠ rows are mostly the Success | Error response unions plus a handful of geometry/value unions. Each variant has a unique required field, so 'errors' in r works in TS — but:

• Python codegen (msgspec, pydantic) without an explicit discriminator generates Union[A, B] and forces isinstance chains.
• Go codegen produces interface{} with no help.
• Future spec edits that add a field can accidentally destroy the unique-required-set property without any test catching it.

Recommend adding status: 'success' | 'error' | 'submitted' (or similar) as an explicit discriminator across the entire response-union family. That collapses 30+ rows from ⚠ to ✓ in one pattern change.

Notable ✗ that are actually discriminated downstream of a ref

Worth calling out because the fix is small (hoist the discriminator):

• core/format.json assets/items oneOf → ref targets carry asset_type const (mirror core/assets/asset-union.json).
• core/pricing-option.json oneOf → ref targets carry model const.
• media-buy/get-media-buy-delivery-request.json geo.system oneOf → enum refs (metro-system / postal-system) — needs a system_kind discriminator at the parent.

CI assertion shape

The walker that produced this audit is ~80 lines. Wire it as a CI gate that fails on any ✗ row:

schemas/source/<path>: oneOf at <pointer> has no discriminator and overlapping required-sets:
  variant 0 requires: [...]
  variant 3 requires: [...]
  Add `discriminator: { propertyName: "<key>" }` or a per-variant const-property.

Allow ⚠ to pass for now (or ratchet by file). Block ✗ outright.

Full table

108 oneOf occurrences (sorted ✗ → ⚠ → ✓ → scalar)

Status	Schema	Pointer	Variants	Discriminator / Notes
✗	a2ui/bound-value.json	#/oneOf	5	shared-required=[∅]; 0:req=[literalString] | 1:req=[literalNumber] | 2:req=[literalBoolean] | 3:req=[path] | 4:req=[literalString,path]
✗	brand/acquire-rights-response.json	#/oneOf	4	shared-required=[∅]; 0:req=[rights_id,status,brand_id,terms,generation_credentials,rights_constraint] | 1:req=[rights_id,status,brand_id] | 2:req=[rights_id,status,brand_id,reason] | 3:req=[errors]
✗	brand/creative-approval-response.json	#/oneOf	4	shared-required=[∅]; 0:req=[status,rights_id] | 1:req=[status,rights_id,reason] | 2:req=[status,rights_id] | 3:req=[errors]
✗	brand/get-brand-identity-response.json	#/oneOf/0/properties/fonts/definitions/font_role/oneOf	2	shared-required=[∅]; 0:string | 1:req=[family]
✗	brand.json	#/oneOf	4	shared-required=[∅]; 0:req=[authoritative_location] | 1:req=[house] | 2:req=[∅] | 3:req=[house,brands]
✗	brand.json	#/definitions/font_role/oneOf	2	shared-required=[∅]; 0:string | 1:req=[family]
✗	brand.json	#/definitions/brand/properties/tone/oneOf	2	shared-required=[∅]; 0:string | 1:req=[∅]
✗	compliance/comply-test-controller-response.json	#/oneOf	7	shared-required=[success]; 0:req=[success,scenarios] | 1:req=[success,previous_state,current_state] | 2:req=[success,simulated] | 3:req=[success,forced] | 4:req=[success] | 5:req=[success,recorded_calls,total_count,since_timestamp] | 6:req=[success,error]
✗	content-standards/create-content-standards-request.json	#/properties/calibration_exemplars/properties/pass/items/oneOf	2	shared-required=[∅]; 0:req=[type,value] | 1:ref-only(/schemas/content-standards/artifact.json)
✗	content-standards/create-content-standards-request.json	#/properties/calibration_exemplars/properties/fail/items/oneOf	2	shared-required=[∅]; 0:req=[type,value] | 1:ref-only(/schemas/content-standards/artifact.json)
✗	content-standards/get-content-standards-response.json	#/oneOf	2	shared-required=[∅]; 0:req=[∅] | 1:req=[errors]
✗	content-standards/update-content-standards-request.json	#/properties/calibration_exemplars/properties/pass/items/oneOf	2	shared-required=[∅]; 0:req=[type,value] | 1:ref-only(/schemas/content-standards/artifact.json)
✗	content-standards/update-content-standards-request.json	#/properties/calibration_exemplars/properties/fail/items/oneOf	2	shared-required=[∅]; 0:req=[type,value] | 1:ref-only(/schemas/content-standards/artifact.json)
✗	core/audience-selector.json	#/oneOf	4	shared-required=[type]; 0:req=[type,signal_id,value_type,value] | 1:req=[type,signal_id,value_type,values] | 2:req=[type,signal_id,value_type] | 3:req=[type,description]
✗	core/format.json	#/properties/assets/items/oneOf	15	ref-only variants — targets carry asset_type const; hoist as discriminator.propertyName=asset_type
✗	core/format.json	#/properties/assets/items/oneOf/14/properties/assets/items/oneOf	12	same as parent
✗	core/format.json	#/properties/supported_macros/items/oneOf	2	ref-to-enum vs raw string
✗	core/pricing-option.json	#/oneOf	9	ref-only variants — targets carry model const; hoist as discriminator.propertyName=model
✗	media-buy/get-media-buy-delivery-request.json	#/properties/status_filter/oneOf	2	enum-ref vs array-of-enum
✗	media-buy/get-media-buy-delivery-request.json	#/properties/reporting_dimensions/properties/geo/properties/system/oneOf	2	metro-system vs postal-system enum refs
✗	media-buy/get-media-buys-request.json	#/properties/status_filter/oneOf	2	enum-ref vs array-of-enum
✗	media-buy/get-products-response.json	#/properties/filter_diagnostics/properties/excluded_by/additionalProperties/properties/values/items/oneOf	2	string vs object
✗	pricing-options/cpv-option.json	#/properties/parameters/properties/view_threshold/oneOf	2	number vs {duration_seconds}
✗	property/property-feature-result.json	#/properties/property/oneOf	2	string vs ref-to-property-id
✗	sponsored-intelligence/si-capabilities.json	#/properties/modalities/properties/voice/oneOf	2	boolean vs object
✗	sponsored-intelligence/si-capabilities.json	#/properties/modalities/properties/video/oneOf	2	boolean vs object
✗	sponsored-intelligence/si-capabilities.json	#/properties/modalities/properties/avatar/oneOf	2	boolean vs object
⚠	account/get-account-financials-response.json	#/oneOf	2	unique-required: 0:[account,currency,period,timezone] | 1:[errors]
⚠	account/sync-accounts-response.json	#/oneOf	2	unique-required: 0:[accounts] | 1:[errors]
⚠	account/sync-governance-response.json	#/oneOf	2	unique-required: 0:[accounts] | 1:[errors]
⚠	adagents.json	#/oneOf	2	unique-required: 0:[authoritative_location] | 1:[authorized_agents]
⚠	brand/get-brand-identity-response.json	#/oneOf	2	unique-required: 0:[brand_id,house,names] | 1:[errors]
⚠	brand/get-rights-response.json	#/oneOf	2	unique-required: 0:[rights] | 1:[errors]
⚠	brand/search-brands-response.json	#/oneOf	2	unique-required: 0:[brands] | 1:[errors]
⚠	brand/update-rights-response.json	#/oneOf	2	unique-required: 0:[rights_id,terms] | 1:[errors]
⚠	content-standards/calibrate-content-response.json	#/oneOf	2	unique-required: 0:[verdict] | 1:[errors]
⚠	content-standards/create-content-standards-response.json	#/oneOf	2	unique-required: 0:[standards_id] | 1:[errors]
⚠	content-standards/get-media-buy-artifacts-response.json	#/oneOf	2	unique-required: 0:[media_buy_id,artifacts] | 1:[errors]
⚠	content-standards/list-content-standards-response.json	#/oneOf	2	unique-required: 0:[standards] | 1:[errors]
⚠	content-standards/validate-content-delivery-response.json	#/oneOf	2	unique-required: 0:[summary,results] | 1:[errors]
⚠	core/account-ref.json	#/oneOf	2	unique-required: 0:[account_id] | 1:[brand,operator] — the union from the issue
⚠	core/catchment.json	#/oneOf	3	unique-required: 0:[travel_time,transport_mode] | 1:[radius] | 2:[geometry]
⚠	core/format.json	#/properties/renders/items/oneOf	2	unique-required: 0:[dimensions] | 1:[parameters_from_format_id]
⚠	core/product-filters.json	#/properties/geo_proximity/items/oneOf	3	unique-required: 0:[travel_time,transport_mode] | 1:[radius] | 2:[geometry]
⚠	core/requirements/image-asset-requirements.json	#/properties/bleed/oneOf	2	unique-required: 0:[uniform] | 1:[top,right,bottom,left]
⚠	core/targeting.json	#/properties/geo_proximity/items/oneOf	3	unique-required: 0:[travel_time,transport_mode] | 1:[radius] | 2:[geometry]
⚠	creative/get-creative-features-response.json	#/oneOf	2	unique-required: 0:[results] | 1:[errors]
⚠	creative/preview-creative-response.json	#/oneOf/1/properties/results/items/oneOf	2	unique-required: 0:[response] | 1:[errors]
⚠	creative/sync-creatives-response.json	#/oneOf	3	unique-required: 0:[creatives] | 1:[errors] | 2:[status,task_id]
⚠	error-details/agent-permission-denied.json	#/oneOf	2	unique-required: 0:[status] | 1:[reason]
⚠	governance/sync-plans-request.json	#/properties/plans/items/properties/budget/oneOf	2	unique-required: 0:[reallocation_threshold] | 1:[reallocation_unlimited]
⚠	media-buy/build-creative-response.json	#/oneOf	4	unique-required: 0:[creative_manifest] | 1:[creative_manifests] | 2:[errors] | 3:[status,task_id]
⚠	media-buy/create-media-buy-response.json	#/oneOf	3	unique-required: 0:[media_buy_id,packages] | 1:[errors] | 2:[status,task_id]
⚠	media-buy/log-event-response.json	#/oneOf	2	unique-required: 0:[events_received,events_processed] | 1:[errors]
⚠	media-buy/provide-performance-feedback-response.json	#/oneOf	2	unique-required: 0:[success] | 1:[errors]
⚠	media-buy/sync-audiences-response.json	#/oneOf	2	unique-required: 0:[audiences] | 1:[errors]
⚠	media-buy/sync-catalogs-response.json	#/oneOf	3	unique-required: 0:[catalogs] | 1:[errors] | 2:[status,task_id]
⚠	media-buy/sync-event-sources-response.json	#/oneOf	2	unique-required: 0:[event_sources] | 1:[errors]
⚠	media-buy/update-media-buy-response.json	#/oneOf	3	unique-required: 0:[media_buy_id] | 1:[errors] | 2:[status,task_id]
⚠	pricing-options/price-breakdown.json	#/properties/adjustments/items/oneOf	2	unique-required: 0:[rate] | 1:[amount]
⚠	signals/activate-signal-response.json	#/oneOf	2	unique-required: 0:[deployments] | 1:[errors]
✓	adagents.json	#/oneOf/1/properties/authorized_agents/items/oneOf	6	const-property authorization_type
✓	collection/base-collection-source.json	#/oneOf	3	discriminator.propertyName=selection_type
✓	compliance/comply-test-controller-response.json	#/oneOf/5/properties/recorded_calls/items/oneOf	2	const-property attestation_mode
✓	content-standards/artifact.json	#/properties/assets/items/oneOf	4	const-property type
✓	content-standards/artifact.json	#/$defs/asset_access/oneOf	3	const-property method
✓	content-standards/update-content-standards-response.json	#/oneOf	2	const-property success
✓	core/activation-key.json	#/oneOf	2	const-property type
✓	core/assets/asset-union.json	#/oneOf	14	discriminator.propertyName=asset_type
✓	core/assets/daast-asset.json	#/oneOf	2	discriminator.propertyName=delivery_type
✓	core/assets/vast-asset.json	#/oneOf	2	discriminator.propertyName=delivery_type
✓	core/creative-item.json	#/oneOf	2	const-property asset_kind
✓	core/data-provider-signal-selector.json	#/oneOf	3	discriminator.propertyName=selection_type
✓	core/deployment.json	#/oneOf	2	const-property type
✓	core/destination.json	#/oneOf	2	const-property type
✓	core/offering-asset-group.json	#/properties/items/items/oneOf	12	discriminator.propertyName=asset_type
✓	core/optimization-goal.json	#/oneOf	2	const-property kind
✓	core/optimization-goal.json	#/oneOf/0/properties/target/oneOf	2	const-property kind
✓	core/optimization-goal.json	#/oneOf/1/properties/target/oneOf	3	const-property kind
✓	core/package.json	#/properties/committed_metrics/items/oneOf	2	discriminator.propertyName=scope
✓	core/performance-feedback.json	#/properties/metric/oneOf	2	discriminator.propertyName=scope
✓	core/publisher-property-selector.json	#/oneOf	3	discriminator.propertyName=selection_type
✓	core/requirements/catalog-field-binding.json	#/oneOf	3	const-property kind
✓	core/requirements/catalog-field-binding.json	#/oneOf/2/properties/per_item_bindings/items/oneOf	2	const-property kind
✓	core/signal-id.json	#/oneOf	2	discriminator.propertyName=source
✓	core/signal-pricing.json	#/oneOf	5	const-property model
✓	core/signal-targeting.json	#/oneOf	3	discriminator.propertyName=value_type
✓	creative/preview-creative-response.json	#/oneOf	3	const-property response_type
✓	creative/preview-render.json	#/oneOf	3	const-property output_format
✓	media-buy/get-media-buy-delivery-response.json	#/properties/aggregated_totals/properties/metric_aggregates/items/oneOf	2	discriminator.propertyName=scope
✓	media-buy/get-media-buy-delivery-response.json	#/properties/media_buy_deliveries/items/properties/by_package/items/allOf/1/properties/missing_metrics/items/oneOf	2	discriminator.propertyName=scope
✓	media-buy/get-products-request.json	#/properties/refine/items/oneOf	3	discriminator.propertyName=scope
✓	media-buy/get-products-response.json	#/properties/refinement_applied/items/oneOf	3	discriminator.propertyName=scope
✓	media-buy/package-request.json	#/properties/committed_metrics/items/oneOf	2	discriminator.propertyName=scope
✓	property/base-property-source.json	#/oneOf	3	discriminator.propertyName=selection_type
✓	protocol/get-adcp-capabilities-response.json	#/properties/adcp/properties/idempotency/oneOf	2	const-property supported

Suggested fix order

1. Family-wide pattern: add status discriminator across every *Response oneOf. Closes 30+ ⚠ rows in one pattern PR.
2. AccountReference (the original issue): add kind: 'account_id' | 'identity' and regenerate adcp-client TS so adapters stop casting.
3. Hoist ref-target discriminators: core/format.json assets, core/pricing-option.json, media-buy/.../geo/system. Mechanical.
4. Pick a shape for the scalar-or-object knobs in brand.json / si-capabilities.json / pricing-options/cpv-option.json. These are spec smells more than codegen bugs.
5. Fix the genuinely broken ones: compliance/comply-test-controller-response.json (variant 4 matches everything), brand.json top-level, brand/{acquire-rights, creative-approval}-response.json, a2ui/bound-value.json.
6. Land the CI walker — once the ✗ list is empty, gate on it.

Audit script saved at /tmp/audit-oneof.mjs (not committed). Happy to convert it to a scripts/audit-oneof.mjs + CI step in a follow-up PR if there's appetite.

— posted by Claude on behalf of @bokelley