Build or adopt a real JSON Schema generator for adcp-go

[bokelley]

Problem

The Go SDK generator is now a structural risk. The current adcp/schemas/generate.py handles simple structs/enums, but the AdCP schemas rely heavily on JSON Schema features that force hand-written Go mirrors today:

• oneOf / anyOf response variants and polymorphic core shapes
• allOf composition and flat merged rows
• inline nested objects, especially response item rows
• absolute $id / $ref paths like /schemas/3.0.12/core/context.json
• optional-vs-zero semantics (*bool, *float64)
• schema drift checks for hand-written inline subshapes

The latest media-buy follow-up needed hand-written CreateMediaBuyResult, MediaBuyData, PackageStatus, and custom marshal logic. That got the wire correct, but it is not a sustainable SDK maintenance model.

Current repo signal

Quick count from the current schema bundle:

• 587 schema files
• 329 oneOf
• 247 anyOf
• 271 allOf
• 4,367 inline object schemas
• 1,094 array item inline object schemas
• 3,248 $ref
• 737 additionalProperties: false

Current Go type ownership is already inverted:

• adcp/types.go: 90 hand-written structs
• adcp/inputs.go: 14 hand-written structs
• adcp/governance_types.go: 12 hand-written structs
• adcp/types_gen.go: 77 generated structs, 142 aliases

Initial candidate smoke tests

github.com/atombender/go-jsonschema

Pros:

• Real JSON Schema generator, not OpenAPI-only.
• Claims support for allOf, anyOf, oneOf, if/then/else, refs, enums, and generated validation.

Smoke-test results:

go run github.com/atombender/go-jsonschema@latest -p adcp adcp/schemas/media-buy/create-media-buy-response.json

Generated only:

type CreateMediaBuyResponseJson map[string]interface{}

That is not acceptable for the main pain point: typed create-media-buy variants.

It also failed to resolve AdCP absolute refs in normal repo layout:

go run github.com/atombender/go-jsonschema@latest --only-models -p adcp \
  adcp/schemas/media-buy/get-media-buys-response.json \
  adcp/schemas/core/context.json \
  adcp/schemas/core/account.json

Failure:

could not follow $ref "/schemas/3.0.12/core/context.json" ... cannot resolve schema

quicktype

Pros:

• Mature multi-language codegen; supports JSON Schema input and Go output.

Smoke-test results:

npx --yes quicktype -s schema -l go --package adcp adcp/schemas/media-buy/create-media-buy-response.json

Failed resolving AdCP absolute refs:

Error: Could not fetch schema , referred to from ...#/oneOf/0/properties/account.

A self-contained oneOf smoke test generated a merged bag-of-fields struct, not a typed union/interface:

type CreateMediaBuyResponse struct {
    Status     *Status `json:"status,omitempty"`
    TaskID     *string `json:"task_id,omitempty"`
    MediaBuyID *string `json:"media_buy_id,omitempty"`
}

This is better than any, but still not the Go SDK shape we want.

OpenAPI generators (ogen, oapi-codegen, OpenAPI Generator)

Worth a deeper spike because ogen advertises generated sum types for oneOf, but these are OpenAPI generators, not direct AdCP JSON Schema generators. We would need a reliable JSON Schema -> OpenAPI components normalization layer first. That may be as much work as building our own generator unless the layer also solves refs, inline extraction, and allOf flattening.

Recommendation

Do a short spike, but bias toward building an AdCP-specific generator unless one candidate clears the acceptance tests below. The generator should be deterministic, repo-local, and generate protocol data shapes only. Response builders and SDK convenience APIs can remain hand-written.

Acceptance criteria

A replacement generator must:

• resolve AdCP $id / $ref paths without filesystem hacks
• emit named structs for inline object schemas using stable, predictable names
• emit typed Go representations for oneOf response variants, preferably sealed interfaces plus variant structs for public SDK APIs
• merge or represent allOf without dropping fields or creating nested shapes that do not match the wire
• preserve nil-vs-zero semantics for optional booleans/numbers
• generate enums with stable names and values
• preserve additionalProperties through Extra map[string]any where appropriate
• support schema pointers in drift lint, e.g. get-media-buys-response.json#/properties/media_buys/items
• produce stable gofmt'd output with low diff churn
• add golden tests for the known hard cases: create media buy response, get media buys response/package rows, delivery response/package delivery, sync creatives assignments, pricing option/deployment/format oneOfs, governance plan inline arrays
• avoid adding runtime dependencies to the root module; generator-only dependencies are acceptable if pinned and isolated under adcp/schemas tooling

First implementation path if we build

1. Add a schema loader that indexes every schema by $id, relative path, and local file path.
2. Build an intermediate representation with resolved refs and explicit schema pointers.
3. Extract inline object schemas into named Go types using path-based names plus an override table.
4. Implement allOf object merge for AdCP's common composition patterns.
5. Implement oneOf strategies:
   • discriminated const/status branches -> sealed interface + variants
   • structural object variants -> generated wrapper with custom marshal/unmarshal, or explicit override
   • ambiguous/primitive variants -> documented any fallback with lint warning
6. Replace KNOWN_TYPES / EXEMPT with a typed override config that records why a type is hand-written and which schema pointer it must drift-check against.
7. Port one area first: media-buy response/request types.

Related follow-up from PR #142 expert pass

MIGRATING.md should explicitly document that Config.GetMediaBuys now returns *GetMediaBuysResponse instead of []MediaBuyData.

[bokelley]

Triage

Classification: Feature request / RFC / Epic
Bucket(s): schema-codegen tooling (no matching repo label exists — flagged in run summary); cross-repo (generator consumes adcontextprotocol/adcp schema bundle)
Status: ready-for-human
Milestone: (omit — no matching open milestone)

---

What the experts said:

• code-reviewer: Problem statement confirmed accurate. generate.py lines 399–403 unconditionally fall back to any for oneOf/anyOf/inline nested objects; the $ref resolver strips /schemas/ but doesn't handle the version path segment (/schemas/3.0.12/…). The 90-vs-77 hand-vs-generated struct count is consistent with the 95-entry KNOWN_TYPES set. Raises three issues: (1) the proposed any-fallback path needs a CI lint gate to prevent silent escape from static typing — not a style nit, a protocol-safety issue; (2) PRs feat(schemas): release-precision version negotiation (allOf envelope) #107 and feat(codegen): propagate JSON Schema deprecated:true as // Deprecated: doc comment #135 both touch generate.py and will have non-trivial merge conflicts with any rewrite; they must be explicitly sequenced. (3) Step 4's allOf merge must union required arrays across branches, not just fields — common omission.
• ad-tech-protocol-expert: Confirmed the any fallback is an active protocol fidelity problem today, not just future risk: GetMediaBuyDeliveryResponse.MediaBuyDeliveries []any means the delivery response fields required by the AdCP 3.0 spec get no static verification. Sealed-interface + variant structs is the correct Go pattern for AdCP's polymorphic variants (already hand-implemented correctly for CreateMediaBuyResult in responses.go:23–50). The MIGRATING.md note about Config.GetMediaBuys → *GetMediaBuysResponse is NOT yet in the doc (contrary to the code-reviewer's initial read) — the "Next" section covers MediaBuyData scoping and CreateMediaBuy, but not the Config.GetMediaBuys return-type change. This is a valid, separable documentation gap. Epic-scale work; a spike could narrow it: fix $ref resolution for versioned paths (2-line bug), implement allOf merge, and emit typed interfaces for the 4 top-level = any aliases before committing to the full 4,367 inline-object extraction.
• security-reviewer: No TEE surface implications — generator only writes to package adcp; protected paths (identity/, pinhole*, metrics*, internal/sanitize/) are in separate packages and untouched. One design note: Go has no exhaustive switch enforcement on interface types; sealed-interface dispatch without an exhaustiveness lint gate (e.g. staticcheck or a discriminator-coverage test) is a latent protocol-confusion path — must be called out as a requirement in the implementation spec. The any-fallback is a pre-existing condition not worsened by this issue, but any any that reaches TEE-adjacent handler code must carry a CI block rather than silent pass. Generator-only deps under adcp/schemas adequately isolates the zero-deps invariant provided no PyPI deps are introduced without pinned hashes. No prompt injection detected in issue body.

---

My take:

This is a well-diagnosed RFC. The generator is genuinely inverted — hand-written types outnumber generated ones, and the any fallback for oneOf/anyOf is an active protocol-fidelity gap, not a future problem. The 7-step implementation plan is sound but epic-scale (weeks of work, cross-repo coordination with the schema bundle in adcontextprotocol/adcp). Three open questions need human decision before any implementation begins: (a) whether to rewrite generate.py in-place or replace it with a new tool; (b) how to sequence against open PRs #107 (allOf) and #135 (deprecated) which will conflict with any generator rewrite; and (c) whether to require staticcheck exhaustiveness coverage for all new sealed-interface oneOf dispatchers (security-reviewer recommends yes).

---

Immediately actionable: MIGRATING.md docs gap (ready to implement)

The last item in this issue is separable and small. MIGRATING.md's "Next: typed seller media-buy helpers" section documents CreateMediaBuyResult, MediaBuyData, and PackageStatus changes, but does not document that Config.GetMediaBuys now returns *GetMediaBuysResponse instead of []MediaBuyData. seller.go:331 confirms the type is already correct in code — the docs are the gap.

Scope: One bullet in MIGRATING.md, under the existing "Next" section.
Likely file: MIGRATING.md only.
Suggested text:

- `Config.GetMediaBuys` now returns `*adcp.GetMediaBuysResponse` instead of
  `[]adcp.MediaBuyData`. Read pagination, context, and error envelope fields from
  the response struct; extract items via `response.MediaBuys`.

Non-breaking rationale: Docs-only change; no Go API surface affected.
Required checks: Markdown review only (no build step needed for docs-only diff).

This can be done as a standalone PR with Refs #145 (not Closes #145) since the codegen epic remains open.

---

Open PR coordination required before any codegen rewrite begins

• PR feat(codegen): propagate JSON Schema deprecated:true as // Deprecated: doc comment #135 (feat(codegen): propagate deprecated:true) — touches generate.py; 8 lines changed in schema_to_struct. A full generator rewrite would supersede or conflict with this.
• PR feat(schemas): release-precision version negotiation (allOf envelope) #107 (feat(schemas): release-precision version negotiation allOf envelope) — adds _inline_root_allof helper to generate.py. Step 4 of this issue's plan implements the same functionality at a broader scope; PR feat(schemas): release-precision version negotiation (allOf envelope) #107 would need to be closed, merged, or explicitly rebased before the rewrite begins.

Recommend commenting on both PRs noting that #145 is in flight and agreeing on sequencing before the generator work starts.

---

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

---

Generated by Claude Code

[bokelley]

ogen spike results

Tested github.com/ogen-go/ogen v1.20.3.

Positive signal

ogen does generate useful Go for OpenAPI allOf. A minimal PackageDelivery = DeliveryMetrics allOf package fields spec generated a flat merged struct with required Spend and required package fields, plus optional wrappers for optional numbers/bools:

type PackageDelivery struct {
    Impressions  OptFloat64 `json:"impressions"`
    Spend        float64    `json:"spend"`
    Clicks       OptFloat64 `json:"clicks"`
    Ctr          OptFloat64 `json:"ctr"`
    Views        OptFloat64 `json:"views"`
    Conversions  OptFloat64 `json:"conversions"`
    PackageID    string     `json:"package_id"`
    PricingModel string     `json:"pricing_model"`
    Rate         float64    `json:"rate"`
    Currency     string     `json:"currency"`
    PacingIndex  OptFloat64 `json:"pacing_index"`
    Paused       OptBool    `json:"paused"`
}

This is materially better than our hand-written partial PackageDelivery.

Negative signal

A minimal OpenAPI CreateMediaBuyResponse with the real AdCP-style shape failed:

Feature "type-based discrimination with same jxType" is not implemented yet.

The issue is not simply that ogen lacks oneOf; it generated a sum type for a clean unique-field object oneOf. It fails on the AdCP create response because success and submitted both contain status, with success status optional/non-submitted and submitted status const submitted.

If I normalize the success branch by removing status, ogen generates a sum type:

type CreateMediaBuyResponse struct {
    Type                    CreateMediaBuyResponseType
    CreateMediaBuySuccess   CreateMediaBuySuccess
    CreateMediaBuyError     CreateMediaBuyError
    CreateMediaBuySubmitted CreateMediaBuySubmitted
}

But removing status from success is not an acceptable schema-preserving generation strategy.

Using ignore_not_implemented just skips the media/operation; it does not produce a useful fallback.

Integration cost

ogen is OpenAPI-first. AdCP schemas are draft-07 JSON Schema files with absolute $id/$ref paths like /schemas/3.0.12/core/context.json, inline response item shapes, and no OpenAPI paths/components source document. To use ogen, we would still need a normalization layer that:

• indexes schemas by $id
• bundles/rewrites refs into OpenAPI components
• extracts inline object schemas into named components
• rewrites or annotates ambiguous oneOfs
• decides how to map additionalProperties and optional wrappers to the SDK API
• suppresses or isolates generated client/server/router code if we only want models

Current recommendation

ogen is useful as a reference and maybe as a backend for some generated model families, especially allOf merges. It does not remove the need for an AdCP-specific generator/normalizer. The hard part remains AdCP schema normalization and SDK-facing type policy.

My bias after this spike: build an AdCP-specific generator, but borrow ideas from ogen for optional wrappers, allOf flattening, and sum-type encoding. A pure ogen adoption is unlikely to be less work than owning our generator unless we are willing to substantially reshape source schemas or generated public types.