Inferred union base makes exported SDK surface a function of unrelated spec edits

[giraffesyo]

No structural rule can capture intent. The union base landed in #57 and generalized in #59 is inferred: when the variants of a oneOf inline the same properties, the generator intersects what they declare and synthesizes <Union>Base from the result. That is the only thing available for producers that flatten composition, and it works, but the analyzer cannot tell a property the variants share on purpose from one they happen to agree on, because in the spec those are the same thing.

The cost

Against a 793-schema spec the inference synthesizes four bases. One of them shows the problem:

synthesized	fields	verdict
AttachedStorageBase	mountPoint, readOnly	genuinely shared
AttachedStorageWriteBase	mountPoint, readOnly	genuinely shared
ClusterCreateBase	7	6 deliberate, 1 coincidental
ClusterDefinitionBase	desktopSession only	pure noise

ClusterCreate's six variants intersect on {description, displayName, duplicatedFrom, name, runTimeAlert, tags}, which is a real base type in the producer, plus desktopSession, which lands there only because all six variable structs happen to declare it.

So an exported SDK type is a function of incidental spec structure. Dropping desktopSession from one cluster type removes a field from ClusterCreateBase, and the person making that edit has no reason to look at the union. Consumers get a compile error, which is the right outcome for them and no help at all to whoever caused it.

At 0.2.x that is a recompile. At 1.0.0 it would be a semver hazard: an unrelated edit to a single variant forces a major version.

Superseded on the timing: no 1.0 is planned, and breaking consumers is not the concern driving this. The case for the extension is now quality, that a base should mean something, rather than release mechanics. See the comments below.

Ruled out: a coverage threshold

Suppressing bases below N shared fields is anti-correlated with the cost. It removes ClusterDefinitionBase, which is inert, and keeps ClusterCreateBase, which is the one with six real fields depending on it and a coincidental seventh that moves. It would also kill legitimate one-field bases, such as a union whose variants genuinely share only id. It cleans up what costs nothing and preserves what costs something.

Proposal: let the producer name the base

An extension on the union schema that names a schema, not a property set:

Pet:
  oneOf: [...]
  discriminator: { propertyName: kind, ... }
  x-go-union-base: "#/components/schemas/CreateClusterMetadata"

The generator then builds Base() *CreateClusterMetadata from the named schema's properties instead of from an intersection.

Two things follow from naming a schema rather than enabling inference:

• The coincidence disappears rather than being mitigated. desktopSession is not a property of CreateClusterMetadata, so it is not in the base, and no edit to a variant can put it there.
• The declaration can be verified. Every variant must declare every property of the named base identically, or generation fails. That turns the extension from a hint into checked intent, which is what makes it worth spending an extension on.

Mechanically this is closer to the synthesis path than to the allOf path: a flattening producer's branches do not embed the base, so Base() still constructs it field by field. Only the source of the field list changes.

An extension that merely enables inference is not worth shipping. ClusterCreateBase would still gain and lose desktopSession with unrelated edits, and the extension would have bought nothing.

The producer side is confirmed

huma can attach this at exactly the right site, with no upstream change:

• huma.Schema has Extensions map[string]any (schema.go:141), marshaled inline by Schema.MarshalJSON (schema.go:177-243), so it lands on any schema object.
• Unions built through Schema(r huma.Registry) *huma.Schema return the oneOf wrapper that carries the discriminator, which is the object the extension goes on.
• The named base is registered with r.Schema(reflect.TypeFor[CreateClusterMetadata](), true, "CreateClusterMetadata"), which both registers the component and returns the ref to put in the extension.

Open question

Ref or property list. A ref carries intent and gives the generated Base() a name the producer already uses, at the cost of requiring the base to exist as a component schema. A property list works when no such schema exists, but it restates the properties in the spec and has no name of its own to return.

Scope

Inference stays. Making the base opt-in would hand back the v0.2.7 behavior for every spec without the extension, which is the case the feature exists for. The extension takes precedence where it appears.

[giraffesyo]

Recording the design decisions and the answer to the question that gates the rest.

The gating question has an answer, and it is yes

Specs for this generator do come from producers this repo does not control.

• The repo has been public and MIT since 2026-03-02.
• Generates identical identifiers for enum values that are non-alphabetical #15, Generates structs with *any fields for "anyOf": [{ "type": "string" }, { "type": "null" }] query params #16, and Generates multipart/form-data requests as submitting application/json content type #17 (May 2026) are bug reports from @antifuchs, who is not a member of the parallelworks org, generating a client for the Mealie API. The spec is attached to Generates identical identifiers for enum values that are non-alphabetical #15 and is FastAPI output: anyOf: [{type: string}, {type: null}] query schemas, title on every schema, operation ids like update_recipe_image_api_recipes__slug__image_put. Three separate defects, all found by driving a third-party spec through the generator.
• test: cover optional security fixture #30 is an outside PR, and there is one fork.
• Repo traffic over the last 14 days: 105 clones from 34 unique cloners against 1 page view. That pattern is automated fetching rather than an audience, so it is weak evidence on its own, but it is not zero.

So the clean path of "land the extension, adopt it everywhere, drop inference at 1.0" is not available. Dropping inference would regress users whose spec producer will never emit x-go-union-base. FastAPI can attach extensions through openapi_extra and json_schema_extra, but expecting the owner of a third-party API to annotate their spec for a Go generator is not a real migration path.

Decision: inference stays past 1.0, documented as derived surface, which #59 already does on the synthesized type itself. The extension is the way a producer states intent, not a replacement for inference. A CLI flag is rejected for the reason already raised: it would make the exported surface depend on how the generator was invoked, so two people generating from one spec would get different types.

Third option for the 1.0 surface question

If the goal at 1.0 is specifically "no invented exported types", there is an option between keeping and dropping: infer only bases the spec already names. Take the intersection as today, then look for the largest component schema whose properties are a subset of it, and return that type instead of synthesizing one.

• It never invents a type. Every Base() returns something the spec declares.
• ClusterCreateBase becomes CreateClusterMetadata, and desktopSession stops mattering, since it is not a property of that schema.
• It loses the AttachedStorage bases, because a producer that flattens composition never emits the component, and those are the two where the inferred base is correct and useful today.

That is a real trade rather than a free win, which is why it belongs in the 1.0 decision rather than in the extension work.

Extension design, settled

Ref only, with an explicit negative form. A property list carries neither a name for Base() to return nor a schema to verify against. But ref-only cannot express "there is no base", which is the true statement for ClusterDefinition, whose six variants embed different structs and intersect only on desktopSession by coincidence. Under ref-only the producer's options there are to point at something false or stay silent, and silence already means "infer", which reproduces the invented type.

So the value space is a ref, or an explicit none:

x-go-union-base: "#/components/schemas/CreateClusterMetadata"   # this is the base, verify it
x-go-union-base: false                                          # these variants share nothing, do not infer
# key absent                                                    # infer, as today

Cheap to add now and awkward to retrofit, since the natural encoding of "none" is the absence of the key, which is already taken.

A failed verification is a generation error, not a warning. It only fires for adopters, since no extension means no verification, so the blast radius is self-selected. More importantly it fires in the producer's CI at the change that broke the assertion. The original objection to inference was that a consumer's compile error lands on someone who did not make the change and cannot tell why; erroring at generation moves the failure onto the person who caused it, at the moment they cause it. A warning would put it back where it started.

Adoption is a refactor, not an annotation

Against the 793-schema spec, of the four bases the generator synthesizes today:

base	what declaring it takes
ClusterCreateBase	points at CreateClusterMetadata, which already exists as a component. Pure annotation.
AttachedStorageBase, AttachedStorageWriteBase	the inferred base is correct and useful, but platformAttachedStorage and nfsAttachedStorage each declare mountPoint and readOnly inline. No shared struct exists to name, so declaring it means extracting one first.
ClusterDefinitionBase	x-go-union-base: false. Pure annotation, and only possible with the negative form.

Half of them are producer-side refactors. That does not argue against the design, but it does mean adoption has a longer runway than annotation alone, and it is another reason the negative form matters: it is the one case that costs nothing.

[giraffesyo]

Two corrections to what I recorded above, both of which change the conclusion.

The subset rule is withdrawn

I proposed inferring only bases the spec already names: take the intersection, then return the largest component schema whose properties are a subset of it. Run against the 793-schema spec, it does not find a smaller answer, it finds a wrong one.

union	intersection	largest subset component
ClusterCreate	7 properties	CreateManagedClusterInputBody
AttachedStorage	mountPoint, readOnly	none
ClusterDefinition	desktopSession	none

CreateManagedClusterInputBody is an unrelated request body for creating a managed cluster. Its description, displayName, name, and tags happen to be a subset of the intersection, so the rule would emit func (u ClusterCreate) Base() *CreateManagedClusterInputBody.

That is worse than synthesis in three ways. A borrowed DTO reads as spec-defined and authoritative, so the coincidence is promoted rather than removed, where a synthesized type at least carries a doc comment saying it is derived. It drags an unrelated schema into an API surface it has nothing to do with. And a later edit to that schema silently changes what ClusterCreate.Base() returns, which is the exact failure this issue exists to prevent, now with a longer causal chain.

The reason it fails is structural rather than particular to one spec. A producer that composes already gets the allOf path. A producer that flattens is precisely the one whose real base never reaches the spec: huma inlines embedded structs, so CreateClusterMetadata is absent from components entirely, while hundreds of unrelated DTOs are present. Subset-matching across a large spec will therefore reliably find nothing, which is the honest outcome, or something wrong, which is the harmful one, and it cannot tell the two apart. Any sufficiently large spec has a component whose properties are a subset of any given intersection.

Withdrawn. It is not a trade against the AttachedStorage bases, it is a regression with a wrong answer attached.

The 1.0 framing is withdrawn

No 1.0 is planned, and breaking consumers is not the concern driving this work. The semver argument in the issue body was the wrong frame and is marked as superseded there.

What survives is the quality argument, which is enough on its own: ClusterDefinitionBase is an exported type holding one field that nobody would group that way by hand, and ClusterCreateBase mixes six deliberate properties with one coincidental one. Neither is a release hazard. Both are the generator asserting a relationship the spec does not state.

So: inference stays, synthesized and documented as derived, which #59 already does on the type itself. The extension remains worth building for what it makes possible, not for what it prevents.

Adoption, corrected again

CreateClusterMetadata is not a component, since huma will not emit a schema for an embedded struct. DesktopSessionSettings and RunTimeAlert survive only because they are pointer field types rather than embeds. So naming it requires registering it first:

base	what declaring it takes
ClusterCreateBase	register CreateClusterMetadata as a component, then point at it
AttachedStorageBase, AttachedStorageWriteBase	extract a shared struct first, since the properties are declared inline in each variant
ClusterDefinitionBase	x-go-union-base: false

One registration, two extractions, one annotation. Only the negative form costs nothing, which is an argument for building that half of the extension first: it is the only part any producer can adopt without changing their types.