schemas: boolean-discriminator unions need an enum migration to be discriminator-keyword-compatible

[bokelley]

Background

Follow-up from #3917 / #3928 / #3934. Two AdCP schemas use a boolean as the discriminator value:

• `content-standards/update-content-standards-response.json` `#/oneOf` — `success: true` vs `success: false`
• `protocol/get-adcp-capabilities-response.json` `#/properties/adcp/properties/idempotency/oneOf` — `supported: true` vs `supported: false`

Both are valid JSON Schema (`const: true` / `const: false`) and validators that respect the `const` pattern narrow them correctly. But Ajv's discriminator implementation (`new Ajv({ discriminator: true })`, used in `tests/json-schema-validation.test.cjs` and `tests/composed-schema-validation.test.cjs`) requires unique string values, not booleans, so we cannot add `discriminator: { propertyName: "..." }` to either union. They remain ✓ via the const-property pattern but lose the OpenAPI codegen hint.

Proposed fix

Migrate each boolean discriminator to a string enum:

Schema	Current	Proposed
`update-content-standards-response`	`success: true | false`	`status: "ok" | "error"` (or similar)
`get-adcp-capabilities-response` idempotency	`supported: true | false`	`mode: "supported" | "unsupported"` (or similar)

Both are breaking wire changes — adopters checking `response.success === true` or `idempotency.supported === true` would need to update. Worth doing in 4.0 (or earlier in 3.x with a migration window).

Decision needed

• Is the value of compatible discriminator-keyword codegen worth the breaking change?
• If yes: schedule for 4.0 alongside the response-union family-wide `status` discriminator already in flight.
• If no: document the boolean-discriminator pattern as intentional, and accept that Ajv's discriminator support won't validate these unions (the `const` pattern still does).

Acceptance (if we proceed)

• Both schemas migrated to string-enum discriminator
• adcp-client / adcp-py codegen regenerated
• Migration note in the corresponding spec version's release notes
• `scripts/oneof-discriminators.baseline.json` ratcheted (these will move from ✓-via-const to ✓-via-discriminator)

Refs

• spec(adcp): discriminator audit — every oneOf needs a discriminator key + CI assertion #3917 — discriminator audit issue
• spec(schemas): add discriminator hints to const-property oneOf unions (adcp#3917) #3928 — first wave
• spec(schemas): hoist pricing-option + format inner-asset discriminators (adcp#3917) #3934 — second wave

[bokelley]

Triage

Classification: Breaking change proposal
Bucket(s): schema, spec / protocol
Status: ready-for-human
Milestone: 4.0 (if Option A or C proceeds)

What the experts said:

• ad-tech-protocol-expert: Both boolean const unions are valid draft-07 and already pass the audit walker (the classify() logic accepts any scalar const, not just strings). The Ajv discriminator gap is real but bounded to OAS3.1-codegen toolchains. The idempotency schema's own description at line 62 already documents the boolean-was-intentional rationale. Option C (parallel field deprecation) mirrors the major_versions → supported_versions pattern already in this same schema.

My take: Three paths exist, not two. Option C threads the needle between a breaking rename and a permanent tooling gap — and the protocol already has its own precedent for this exact migration pattern. The blast radii differ: idempotency.supported is read on every buyer connect (wide blast); success is a single-task write response (narrower). These two schemas may warrant different treatment.

@bokelley, your call: A, B, or C?

---

Option A — Rename to string-enum discriminators (4.0, breaking):

// update-content-standards-response
- { "success": true, "standards_id": "cs_123" }
+ { "status": "ok", "standards_id": "cs_123" }

// get-adcp-capabilities idempotency
- { "supported": true, "replay_ttl_seconds": 3600 }
+ { "mode": "supported", "replay_ttl_seconds": 3600 }

Full discriminator keyword compatibility. Adopters checking success === true or supported === true must update on 4.0 upgrade.

Option B — Document as intentional (no wire change):
Add a schema note acknowledging the Ajv limitation. const-narrowing continues to work; discriminator keyword stays unavailable for these two unions. Zero migration cost; permanent codegen gap.

Option C — Parallel-field deprecation in 3.x, removal in 4.0 (non-breaking in 3.x):

// idempotency — sellers emit both fields in 3.x
  {
    "supported": true,
+   "mode": "supported",
    "replay_ttl_seconds": 3600
  }
// same pattern for update-content-standards-response: add "status" alongside "success"

Buyers can adopt mode/status ahead of 4.0; boolean removed at 4.0. Mirrors the major_versions deprecation notice already in get-adcp-capabilities-response: "Servers MUST continue to emit this field through 3.x… Removed in 4.0."

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[bokelley]

Moving to 3.2.0 — boolean-discriminator enum migration is a breaking-shape change on multiple schemas. Moves with #3917/#3935/#3939 cluster. 3.2 cycle.