json-schema-to-typescript emits Foo+Foo1 for inline asset variants referenced from multiple parents

[bokelley]

Context

@adcp/client 5.x uses json-schema-to-typescript to generate TypeScript types from the AdCP JSON schemas. When the same asset schema is referenced from two parent schemas, the generator emits a numerically-suffixed duplicate type for the inline form. This surfaces as the following exported types in core.generated.ts:

• VASTAsset (from creative/asset-types) and VASTAsset1 (from creative-asset.json's asset map)
• DAASTAsset and DAASTAsset1
• BriefAsset and BriefAsset1
• CatalogAsset and CatalogAsset1
• CreativeAsset1 (from creative-manifest.json referencing creative-asset.json)

The two forms are NOT byte-identical — VASTAsset is the wrapped form ({ asset_type: 'vast', vast_version, vpaid_enabled, captions_url, … } & (url|inline)), while VASTAsset1 is just the inner discriminated (url|inline) union exposed inline inside creative-asset.json's asset map. Both shapes are valid public types — but the 1 suffix reads as a versioning artifact and makes consumer imports harder to review.

AgeVerificationMethod was the same artifact and got fixed upstream by introducing a single $ref to enums/age-verification-method.json so json-schema-to-typescript only emits one type. This issue tracks the equivalent fix for the asset-variant refs.

Repro

git clone https://github.com/adcontextprotocol/adcp-client
cd adcp-client
npm i && npm run sync-schemas && npm run generate-types
grep -E '^export type (VAST|DAAST|Brief|Catalog)Asset1' src/lib/types/core.generated.ts
# → emits VASTAsset1, DAASTAsset1, BriefAsset1, CatalogAsset1

Where the duplication originates

The asset map in core/creative-asset.json and core/creative-manifest.json both inline a oneOf over the asset variant schemas:

{
  "oneOf": [
    { "$ref": "/schemas/3.0.1/core/assets/vast-asset.json" },
    { "$ref": "/schemas/3.0.1/core/assets/daast-asset.json" },
    { "$ref": "/schemas/3.0.1/core/assets/brief-asset.json" },
    { "$ref": "/schemas/3.0.1/core/assets/catalog-asset.json" },
    …
  ]
}

The generator hoists the inline form a second time when it crosses the second parent.

Suggested fix

Two options, in increasing order of churn:

Option A — promote the shared inline-variant union to its own schema file. Create something like core/assets/asset-variant.json that is the oneOf union, and have both creative-asset.json and creative-manifest.json reference that single schema. json-schema-to-typescript then emits one shared type instead of two suffixed copies.

Option B — inline the variant union as a JSON Schema $defs in a single canonical location (e.g. inside creative-asset.json's top-level $defs) and have other parents reference creative-asset.json#/$defs/asset-variant. Less invasive than (A) but still produces a single emitted type.

Either is fine; option (A) is cleaner because the variant list isn't a 'private' concept of creative-asset.json — it's the canonical list of inline asset forms.

SDK-side workaround we are NOT pursuing

Renaming *Asset1 to Inline*AssetDelivery via a post-process step on core.generated.ts is straightforward (~50 LOC + alias map). We've decided against it because the right fix is at the schema source — bandaiding in the SDK compounds drift across implementations.

Cross-ref

• @adcp/client issue: Rename SCREAMING_SNAKE schema artifacts (RATE_LIMITEDDetails, AgeVerificationMethod1) propagated by json-schema-to-typescript adcp-client#942
• @adcp/client project memory documenting the json-schema-to-typescript artifact: project_jsts_numbered_dupes.md
• Prior precedent (resolved): AgeVerificationMethod / AgeVerificationMethod1 was the same artifact, fixed upstream via single $ref.

🤖 Filed by Claude Code on behalf of @bokelley

[bokelley]

Triage

Classification: Bug (json-schema-to-typescript artifact causing confusing generated type names)
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Option A (new core/assets/asset-variant.json) is the right approach — matches the AgeVerificationMethod precedent of promoting a shared concept to its own schema file. Option B ($defs inside creative-asset.json) works but creates an unusual cross-sibling $ref. Both are non-breaking at the protocol wire level.
• Key constraint: hoistDuplicateInlineEnums in scripts/build-schemas.cjs (lines 672–789) was intentionally scoped to pure-enum schemas with a comment deferring object/oneOf hoisting to a future RFC. Option A sidesteps this entirely (it's a new named schema file, not $defs), but needs one build-pipeline confirmation: that resolveRefs in build-schemas.cjs correctly follows the new cross-file $ref to asset-variant.json and emits a single named type rather than inlining the oneOf a second time.

My take: Option A is execute-eligible once that resolveRefs round-trip is confirmed; it's a one-run npm run build:schemas check against the generated output, not an RFC. The removing of VASTAsset1 etc. from @adcp/client is breaking for that package specifically — the adcp schema PR should be --empty (no protocol wire change), and the @adcp/client follow-up is where the major bump lives.

@bokelley, your call: want the triage routine to draft the Option A schema PR, or do you prefer to own the resolveRefs verification step yourself first?

---

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

---

Generated by Claude Code

[bokelley]

Triage

Classification: Bug (schema organization artifact causing SDK type duplication)
Bucket(s): spec / protocol
Status: drafting-pr
Milestone: 3.0.x patch line

What the experts said:

• ad-tech-protocol-expert: Option A (new asset-union.json with title: AssetVariant) is semantically transparent to validators — $ref-to-oneOf is structurally equivalent to the inline form under draft-07; discriminator placement correct per OAS 3.1; patch bump is right; 0 blockers.
• adtech-product-expert: Fix urgently needed — every SDK release with VASTAsset1 in the public surface is a chance for integrators to import the artifact and create future migration debt; recommends explicit changelog call-out that *1 types were codegen accidents.
• code-reviewer: 0 blockers; flagged minor vs patch bump as a question (new $id is additive); offering-asset-group.json intentional 12-arm subset needed documentation — addressed in the PR.

My take: Experts converge on executing. Draft PR #3462 creates core/assets/asset-union.json, replaces the duplicate inline oneOfs in creative-asset.json and creative-manifest.json, and clarifies the intentional subset in offering-asset-group.json. The changeset bump question (patch vs minor) is called out in the PR body for reviewer discretion — protocol expert says patch (structural equivalence), code-reviewer says minor (new $id). PR targets 3.0.x.

---

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

---

Generated by Claude Code