Rename SCREAMING_SNAKE schema artifacts that surface as public TypeScript types

[bokelley]

Context

Two source-schema patterns leak into the TypeScript SDK's public type surface as awkward, typo-feeling names. Both originate in schemas/cache/{version}/ and propagate through json-schema-to-typescript into @adcp/client's core.generated.ts and (via adcp-client#938 / #931) into the public Values exports.

Tracked SDK-side in adcp-client#942.

1. SCREAMING_SNAKE parent names

A discriminator branch with code: \"RATE_LIMITED\" and no explicit title lands as RATE_LIMITEDDetails in the generated TypeScript. PR #938 then propagates it as RATE_LIMITEDDetails_ScopeValues. Reads as a typo to every consumer.

2. Numbered-dupe suffixes from re-referenced enums

When the same enum is reachable through two different schema paths without a shared $ref, json-schema-to-typescript emits both copies as Foo and Foo1. Currently visible: AgeVerificationMethod + AgeVerificationMethod1, plus BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1. Both copies always have identical literal values — the suffix implies a version/distinction that doesn't exist. Documented as a known codegen artifact in the SDK's auto-memory (project_jsts_numbered_dupes.md).

Suggested fix (upstream)

In schemas/cache/{version}/:

1. Give the RATE_LIMITED discriminator branch (and any siblings using SCREAMING_SNAKE codes) an explicit \"title\": \"RateLimitedDetails\" so json-schema-to-typescript produces RateLimitedDetails.
2. For cross-referenced enums (AgeVerificationMethod and the four *Asset1 cases), introduce a single shared $ref so the codegen emits one type. Eliminates the dedup-by-value problem at the source.

SDK-side fallback: rename in a post-codegen step, with aliases for one minor version. Adds codegen complexity; the spec is the authoritative place to express both fixes.

Acceptance

• RATE_LIMITEDDetails → RateLimitedDetails (or equivalent PascalCase) in the SDK's core.generated.ts after npm run sync-schemas
• AgeVerificationMethod1, BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1 consolidate into the un-suffixed names
• No consumer-facing breakage in the SDK's Values exports — released names with the suffixes get aliases for one minor version

Refs

• SDK tracking issue: Rename SCREAMING_SNAKE schema artifacts (RATE_LIMITEDDetails, AgeVerificationMethod1) propagated by json-schema-to-typescript adcp-client#942
• Where these surface in the public values surface: feat(types): inline-union value arrays for anonymous string-literal unions (#932) adcp-client#938
• Companion SDK PR (named enums): feat(server): idempotency: 'disabled' mode + standalone enum value arrays adcp-client#931

🤖 Filed by Claude Code

[bokelley]

Triage

Classification: Bug (codegen artifact from schema annotation)
Bucket(s): schema
Status: drafting-pr (partial — Problem 1 only)

What the experts said:

• ad-tech-protocol-expert: title is non-normative per draft-07 §10.1; rename to "Rate Limited Details" is correct and non-breaking. Dist snapshots needed updating too. Spec PR can ship before SDK alias (adcp-client#942), but alias must merge before sync-schemas runs for consumers. $defs bundler change is the right fix for Problem 2 (~50–80 line change to resolveRefs).
• adtech-product-expert: Numbered-suffix types (BriefAsset1, VASTAsset1, etc.) are higher urgency than the rate-limit title — they appear in the creative-asset discriminated union that every creative-agent implementer writes against. One-minor alias window is sufficient given 3.x cadence. Spec-side fix is the correct layer; SDK post-codegen shim would mask the root cause.

My take: Problem 1 (RATE_LIMITED title) is a clear, non-breaking annotation fix — shipping in draft PR #3149 (Refs #3145). Problem 2 (numbered-dupe suffixes) needs a bundler design call before implementation: should $defs hoisting in scripts/build-schemas.cjs be scoped to pure-enum schemas only, or to all multiply-referenced types? Hoisting complex object schemas is safe but affects bundled-output readability.

Shipped in #3149: RATE_LIMITED title fix (source + dist/3.0.0 + dist/3.0.0-rc.3 + latest).

Remaining in this issue: AgeVerificationMethod1, BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1 numbered-dupe suffixes. Root cause is resolveRefs in scripts/build-schemas.cjs inlining the same shared type multiple times across bundled schemas. Fix: hoist multiply-referenced types to $defs in the bundled output.

@bokelley, your call: Should the $defs hoisting in resolveRefs be scoped to pure-enum schemas only (type: string, enum: [...]) or to all multiply-referenced schemas (including complex objects like BriefAsset, VASTAsset)? Enum-only is safer and narrower; all-types is a more complete fix but affects bundled readability. Either approach keeps #3145 open as the tracker for the remaining four types.

---

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

---

Generated by Claude Code

[bokelley]

Re: enum-only vs all-types \$defs hoisting

Recommendation: enum-only for the next PR. Defer all-types behind an RFC.

Reasoning from the SDK-side protocol review:

Enum dupes (AgeVerificationMethod1) are unambiguous bugs. Two enums with byte-identical literal values are the same enum, full stop. Hoisting to a shared \$defs entry is semantics-preserving and the codegen artifact disappears. No design call needed — just do it.

Complex object dupes (BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1) are sometimes intentional. Today these have identical structure across the schemas that reach them, but they're separate type lineages — BriefAsset (proposed creative) and VASTAsset (delivered video creative) are conceptually distinct even when their fields happen to align. Hoisting them globally:

1. Creates cross-tool coupling the source schemas don't express. A future change that should have been scoped to BriefAsset now requires updating every consumer of VASTAsset too.
2. Is hard to undo. Once SDKs (adcp-client, Python clients, etc.) codegen against the hoisted single type, splitting them back out is breaking.
3. Blurs the discriminated-union story for creative_asset — having distinct types per discriminator branch is desirable even when fields match.

The right path for complex types is a deliberate x-hoist: true opt-in (or similar marker) on schemas the spec authors have decided are canonically shared, surfaced through an RFC. Don't let codegen ergonomics drive the type lineage.

Suggested PR scope

For the follow-up \$defs hoisting work:

• In scope: pure-enum schemas (type: string + enum). Detector should match {type === 'string' && Array.isArray(enum) && Object.keys(schema).length <= 4} — keeps siblings like description, title benign.
• Out of scope: any object schema, any oneOf/anyOf/allOf, anything with properties. Surface via RFC.

That keeps the PR scoped to ~50–80 lines in resolveRefs as the protocol expert estimated, and closes the loud cases (AgeVerificationMethod1) without locking in design decisions on the harder ones.

[bokelley]

Thanks for the clear scoping call, @bokelley. Acting on it now.

Shipped in #3170: enum-only $defs hoisting. hoistDuplicateInlineEnums() added to scripts/build-schemas.cjs — detects titled pure-enum schemas inlined 2+ times in a bundled output and replaces duplicates with $ref pointers. Fixes AgeVerificationMethod1 (update-media-buy-request.json and core/tasks-get-response.json).

Remaining in this issue: BriefAsset1, VASTAsset1, DAASTAsset1, CatalogAsset1 (complex object types). Deferred per your direction — these require an RFC with an x-hoist: true opt-in marker before the bundler hoists object schemas.

---

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

---

Generated by Claude Code