schemas: tracker for the 20 remaining undiscriminated oneOf unions

[bokelley]

Tracker for the dangerous oneOf unions still in scripts/oneof-discriminators.baseline.json after the #3917 audit loop landed (#3922 / #3928 / #3934). These are bucketed by the kind of fix each needs — none are "free hoists" like the first two waves. The WG should route each bucket to a driver.

Already filed separately: #3935 (core/format.json outer assets/items two-tier restructure), #3936 (boolean-discriminator unions).

A. Scalar-vs-object shape decisions (10 rows)

These are unions where a value can be either a scalar or a structured object. Today they validate, but downstream codegen produces string | object types that adopters have to narrow with typeof at every read site. Each needs a single-shape decision (drop the scalar, or wrap the scalar in { value: <scalar> }).

• brand.json #/definitions/brand/properties/tone/oneOf — string vs empty-object
• brand.json #/definitions/font_role/oneOf — string vs { family }
• brand/get-brand-identity-response.json #/oneOf/0/properties/fonts/definitions/font_role/oneOf — duplicate of the above
• core/format.json #/properties/supported_macros/items/oneOf — enum-ref vs raw string
• media-buy/get-media-buy-delivery-request.json #/properties/status_filter/oneOf — single-enum vs array-of-enum
• media-buy/get-media-buy-delivery-request.json #/properties/reporting_dimensions/properties/geo/properties/system/oneOf — metro-system enum vs postal-system enum
• media-buy/get-media-buys-request.json #/properties/status_filter/oneOf — same as delivery-request
• media-buy/get-products-response.json #/properties/filter_diagnostics/properties/excluded_by/additionalProperties/properties/values/items/oneOf — string vs object
• pricing-options/cpv-option.json #/properties/parameters/properties/view_threshold/oneOf — number vs { duration_seconds }
• property/property-feature-result.json #/properties/property/oneOf — string id vs { ...property-id object }
• sponsored-intelligence/si-capabilities.json modalities voice / video / avatar (3 unions) — boolean vs object

Recommend: pick the object form for every case. Adopters who want the scalar can read a single field; the spec stops carrying the validator-ambiguous shape.

B. Response-union variant collisions (4 rows)

Each union has multiple variants that share required keys, so a payload can match more than one variant. This is a genuine spec defect — adopters can't tell success from partial-success from conditional-success without inspecting non-required fields.

• compliance/comply-test-controller-response.json #/oneOf — 7 variants all share [success]; variant 4 requires only [success] and matches every other variant. Variant 4 is unreachable / overlapping.
• brand/acquire-rights-response.json #/oneOf — success / partial / approved-with-conditions all share [rights_id, status, brand_id]
• brand/creative-approval-response.json #/oneOf — same shape, success / conditions / errors collide on [status, rights_id]
• content-standards/get-content-standards-response.json #/oneOf — success has empty required, error has [errors]; success matches every error payload too

Recommend: add a per-variant status: const discriminator ("ok" | "error" | "partial" | "conditional") wherever the variants are not already disjoint. This is the same pattern the WG should standardize family-wide on response unions for 4.0.

C. Top-level / structural overlap (2 rows)

• brand.json #/oneOf — variant 2 has zero required keys, so it matches every document. The other three variants pick by authoritative_location / house / (house, brands). Variant 2 looks like an unintended catch-all.
• a2ui/bound-value.json #/oneOf — variant 4 requires [literalString, path], intersecting variants 0 ([literalString]) and 3 ([path]). Either variant 4 should be removed or a kind discriminator added.

D. Two-tier discriminator restructure (1 row)

• core/audience-selector.json #/oneOf — variants already declare type: const, but 3 of 4 share type: "signal" and only differ by a secondary value_type (binary / categorical / numeric); the 4th has type: "description". Same restructure pattern as schemas: restructure core/format.json outer assets oneOf to be discriminated #3935: split the parent oneOf on type, then nest a second oneOf on value_type inside the signal branch.

Acceptance for closing this tracker

When the buckets above are resolved, scripts/oneof-discriminators.baseline.json should be empty (or contain only intentional ⚠ entries). At that point we can flip the audit walker from baseline-diff mode to hard-fail mode for both ✗ and ⚠ in CI.

Refs

• spec(adcp): discriminator audit — every oneOf needs a discriminator key + CI assertion #3917 — audit issue + plan
• ci(schemas): add oneOf discriminator audit + baseline (adcp#3917) #3922 / spec(schemas): add discriminator hints to const-property oneOf unions (adcp#3917) #3928 / spec(schemas): hoist pricing-option + format inner-asset discriminators (adcp#3917) #3934 — audit infrastructure + first two waves
• schemas: restructure core/format.json outer assets oneOf to be discriminated #3935 — format.json outer oneOf restructure
• schemas: boolean-discriminator unions need an enum migration to be discriminator-keyword-compatible #3936 — boolean-discriminator migration

[bokelley]

Triage

Classification: Tracking
Bucket(s): spec / protocol
Status: deferred

Blocked-on: #3935, #3936 — resurfaces on merge. Buckets A–D need WG routing per the tracker body; no auto-PR is appropriate for a multi-decision schema restructure epic.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01D4YBzoyvaAdE84nVssnkbg

---

Generated by Claude Code

[bokelley]

Moving to 3.2.0 — tracker for 20 undiscriminated oneOf unions. Moves with the rest of the discriminator cluster (#3917, #3935, #3936). 3.2 cycle.

[bokelley]

Walker false-positive analysis — four ✗ entries are correctly disjoint

Investigated the four entries I'd previously flagged in Bucket B/C as "spec defects" while looking for a pre-GA carve-out. Confirmed at the ajv level: all four are walker false-positives, not bugs. Documenting the actual discrimination mechanisms here so future-3.2.0 work starts with this in hand and doesn't repeat the audit.

compliance/comply-test-controller-response.json #/oneOf

Walker reports: 7 variants, shared-required=[success].

Actual: every variant carries not.anyOf: [{required:[<peer-keys>]}] excluding all peers' distinguishing keys. Variant 4 (SeedSuccess, required:[success] only) is fully disjoint from peers because its not.anyOf forbids error/scenarios/previous_state/simulated/forced/recorded_calls. {success:true} matches only SeedSuccess; {success:true, scenarios:[...]} matches only ListScenariosSuccess; etc.

Walker gap: doesn't track not.anyOf[*].required as variant exclusion.

a2ui/bound-value.json #/oneOf

Walker reports: 5 variants, variant 4 [literalString,path] intersects variants 0 [literalString] and 3 [path].

Actual: every variant has additionalProperties: false. {literalString:"x"} matches only variant 0 (variants 1/2/3 require different keys; variant 4 requires path too). {literalString:"x", path:"/p"} matches only variant 4 (variant 0 rejects extra path; variant 3 rejects extra literalString). Fully disjoint.

Walker gap: doesn't track additionalProperties:false + the closed property set as a variant exclusion.

brand.json #/oneOf

Walker reports: 5 variants, variants 2 and 4 have empty required.

Actual:

• Variant 2 (Brand Agent): anyOf:[{required:[agents]},{required:[brand_agent]}] — effectively requires one of those.
• Variant 4 (Brand Canonical Document): allOf:[{not:{anyOf:[{required:[house]},...,{required:[note]}]}}, {$ref:#/definitions/brand}] — the brand ref transitively requires [id, names], AND the not.anyOf excludes every key that distinguishes variants 0/1/3.
• All variants carry additionalProperties: false.

A {house:"x", brands:[...]} payload matches only variant 3 (House Portfolio). A {authoritative_location:"..."} payload matches only variant 0. A {id:"...", names:[...]} payload matches only variant 4 (the brand canonical). No structural overlap.

Walker gaps: (a) doesn't track anyOf[*].required as variant requirements; (b) doesn't fuse allOf.$ref-resolved required with the variant's own required for the classification.

content-standards/get-content-standards-response.json #/oneOf

Walker reports: 2 variants, success variant has empty required.

Actual: success variant is allOf:[{$ref:content-standards.json}] and content-standards.json transitively requires standards_id (line 70 of that file). Verified directly: {errors:[...]} fails the success variant with must have required property 'standards_id'. Only the error variant matches; oneOf resolves cleanly.

Walker gap: same as brand.json case (d) — needs to fuse allOf.$ref-resolved required with variant-level required during classification. The walker resolves one-hop refs for variantInfo but only uses the properties and required from the ref target directly, not when fused with variant-level fields.

Implication for 3.2.0 walker work

The right shape for #3939's walker improvements:

1. Credit not.anyOf[*].required: [<peer-key>] as the variant excluding that key — that closes the comply-test-controller family of false-positives.
2. Credit additionalProperties:false + property-set as a closed-form exclusion of all keys not in the set — closes bound-value-shaped false-positives.
3. Credit anyOf[*].required as adding to a variant's required-set — closes the brand.json variant-2 false-positive.
4. Fuse allOf chains' required (including via $ref) into the variant's effective required-set before classifying — closes both brand.json variant 4 and get-content-standards-response variant 0.

After those four walker enhancements, the audit reclassifies cleanly without touching any wire shape. The remaining ✗ rows after that pass are the ones genuinely worth fixing as spec changes (and may shrink the Bucket B/C list significantly).

Filing this as analysis-in-advance so the 3.2.0 walker work doesn't have to re-derive it. The walker is at scripts/audit-oneof.mjs; the schemas referenced above are unchanged.

— posted by Claude on behalf of @bokelley