Skip to content

Commit a758dca

Browse files
fredbiclaude
andcommitted
fix(schema): aliased embeds follow the named-embed dispatch
A struct that embeds an alias of a named struct used to produce allOf composition with a $ref to the alias — a different shape from a struct that embeds the named type directly (flat inline properties). The two embeds reference the same Go type (`types.Unalias(BaseAlias) == Base`); the spec-side asymmetry came from `*types.Alias` taking a separate dispatch arm in `buildEmbedded` and `scanEmbeddedFields`. Two changes align the paths: - `scanEmbeddedFields` no longer treats aliased embeds as implicitly opted into allOf composition (the `!isAliased` gate is removed). Plain (non-`swagger:allOf`) aliased embeds now inline their properties just like direct-named embeds. - `buildEmbedded` routes the `*types.Alias` arm through `types.Unalias` and then re-enters the named-embed path. The same code subsequently handles allOf composition when the embed carries `swagger:allOf`. The documented contract is now uniform across embed kinds: "embeds always inline properties, never $ref unless the embed carries `swagger:allOf`". The annotation is the sole gate for allOf composition. Adds the `alias-calibration-embed` fixture covering all four embed permutations (direct named, alias of struct, pointer, named interface) plus the bidirectional `swagger:allOf` opt-in witnesses for both alias and direct-named embeds. The `coverage_alias_embed_inline_test.go` test pins both halves of the contract. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 4020382 commit a758dca

7 files changed

Lines changed: 400 additions & 137 deletions

File tree

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// Package alias_calibration_embed is the cycle-3 calibration fixture
5+
// for the W3 alias workshop. It tests the composition axis: how the
6+
// schema builder shapes a struct that EMBEDS another type, in four
7+
// permutations of how the embedded type is referenced:
8+
//
9+
// 1. Named struct, direct (EmbedsDirectStruct)
10+
// 2. Alias of struct (EmbedsAlias)
11+
// 3. Pointer to named struct (EmbedsPointer)
12+
// 4. Named interface (EmbedsInterface)
13+
//
14+
// In Go, (1), (2), and (3) refer to the SAME underlying type
15+
// (`Base`); `BaseAlias = Base` is a transparent rename, `*Base` is
16+
// just a pointer-to-Base. The type system cannot distinguish them.
17+
// Yet the schema builder today produces THREE different output
18+
// shapes for the same composition intent — the central Q8 question.
19+
//
20+
// The B2 probe from fix-quirks revealed:
21+
// - EmbedsDirectStruct → FLAT inline (id, name, extra)
22+
// - EmbedsAlias → allOf: [{$ref: BaseAlias}, {extra inline}]
23+
// - EmbedsPointer → FLAT inline (pointer peeled → named-direct)
24+
// - EmbedsInterface → FLAT inline (interface methods promoted)
25+
//
26+
// So the OUTLIER is alias-embed, not interface-embed (the Q8
27+
// original framing was wrong). Cycle 3 calibrates the workshop's
28+
// vocabulary on whether this asymmetry should hold, collapse, or
29+
// invert.
30+
//
31+
// Envelope also includes a field-site comparison (Base vs
32+
// BaseAlias as field types) so the field-reach behaviour is on
33+
// the same canvas as the embed-reach behaviour.
34+
//
35+
// 5 decls × 3 modes = 15 base cells, plus indirect impacts on Base /
36+
// BaseAlias / Methods which may surface as standalone definitions.
37+
//
38+
// See `.claude/plans/workshops/alias-matrix.md` §5 and
39+
// `.claude/plans/workshops/alias-ledger.md` cycle 3.
40+
package alias_calibration_embed
41+
42+
// Base is the canonical struct used as the embedded target in
43+
// every variant below. Two fields so we can see the FLAT vs allOf
44+
// distinction in the output.
45+
//
46+
// swagger:model Base
47+
type Base struct {
48+
// required: true
49+
ID int64 `json:"id"`
50+
51+
Name string `json:"name"`
52+
}
53+
54+
// BaseAlias is a transparent rename of Base. In Go, BaseAlias and
55+
// Base are LITERALLY the same type — `types.Unalias(BaseAlias) ==
56+
// Base`, reflection cannot distinguish them.
57+
type BaseAlias = Base
58+
59+
// Methods is a named interface with one valid property-shaped
60+
// method, used to test embed-of-interface.
61+
type Methods interface {
62+
// Describe returns a human-readable label.
63+
Describe() string
64+
}
65+
66+
// EmbedsDirectStruct embeds Base directly. The B2 probe shape:
67+
// FLAT — `{type: object, properties: {id, name, extra}}` with no
68+
// allOf composition. Q8 baseline.
69+
//
70+
// swagger:model EmbedsDirectStruct
71+
type EmbedsDirectStruct struct {
72+
Base
73+
74+
// Extra is a field unique to the outer struct.
75+
Extra string `json:"extra"`
76+
}
77+
78+
// EmbedsAlias embeds BaseAlias. The B2 probe shape: `allOf:
79+
// [{$ref: BaseAlias}, {properties: {extra}}]`. Q8 OUTLIER — same
80+
// Go type as EmbedsDirectStruct produces a DIFFERENT spec shape.
81+
//
82+
// swagger:model EmbedsAlias
83+
type EmbedsAlias struct {
84+
BaseAlias
85+
86+
Extra string `json:"extra"`
87+
}
88+
89+
// EmbedsPointer embeds *Base. The B2 probe shape: FLAT (pointer is
90+
// peeled, then takes the named-direct path). Consistent with
91+
// EmbedsDirectStruct.
92+
//
93+
// swagger:model EmbedsPointer
94+
type EmbedsPointer struct {
95+
*Base
96+
97+
Extra string `json:"extra"`
98+
}
99+
100+
// EmbedsInterface embeds the named Methods interface. The B2 probe
101+
// shape: FLAT — method properties promoted into the outer schema
102+
// alongside Tag. Consistent with EmbedsDirectStruct (named embed
103+
// of any kind goes through buildNamedEmbedded which inlines).
104+
//
105+
// swagger:model EmbedsInterface
106+
type EmbedsInterface struct {
107+
Methods
108+
109+
Tag string `json:"tag"`
110+
}
111+
112+
// Envelope compares Base and BaseAlias at the FIELD-reach site
113+
// (not embed). Cycles 1-2 showed annotated aliases produce a
114+
// $ref to the def at field sites; we want to see whether the
115+
// alias-vs-named asymmetry persists at the field site or only at
116+
// the embed site.
117+
//
118+
// swagger:model Envelope
119+
type Envelope struct {
120+
// Direct field of type Base.
121+
Direct Base `json:"direct"`
122+
123+
// ViaAlias field of type BaseAlias — same underlying as Direct.
124+
ViaAlias BaseAlias `json:"viaAlias"`
125+
}
126+
127+
// EmbedsAliasOptIn validates the bidirectional Q-D contract: when
128+
// the user EXPLICITLY annotates an aliased embed with
129+
// `swagger:allOf`, the resulting spec MUST use allOf composition
130+
// with a $ref to the embedded type. This is the shape that was
131+
// silently produced (without annotation) before the Q-D fix; it
132+
// remains available as an explicit opt-in.
133+
//
134+
// Combined with EmbedsAlias above, this fixture asserts:
135+
//
136+
// - Without `swagger:allOf` → flat inline (EmbedsAlias)
137+
// - With `swagger:allOf` → allOf with $ref (EmbedsAliasOptIn)
138+
//
139+
// The annotation is the SOLE gate; no other input flips composition.
140+
//
141+
// swagger:model EmbedsAliasOptIn
142+
type EmbedsAliasOptIn struct {
143+
// swagger:allOf
144+
BaseAlias
145+
146+
// Extra is a field unique to the outer struct.
147+
Extra string `json:"extra"`
148+
}
149+
150+
// EmbedsDirectStructOptIn mirrors EmbedsAliasOptIn but with a
151+
// direct named-struct embed instead of an alias embed — checks
152+
// that the explicit annotation works on non-aliased embeds too.
153+
// Pre-Q-D this case ALREADY worked (named-direct embed with
154+
// swagger:allOf → allOf with $ref to Base) — the annotation path
155+
// was never broken; only the *implicit* aliased-embed promotion
156+
// was wrong. Including this here triangulates: same annotation,
157+
// same shape, regardless of alias or direct.
158+
//
159+
// swagger:model EmbedsDirectStructOptIn
160+
type EmbedsDirectStructOptIn struct {
161+
// swagger:allOf
162+
Base
163+
164+
Extra string `json:"extra"`
165+
}

‎fixtures/integration/golden/enhancements_embedded_types.json‎

Lines changed: 6 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,17 @@
2121
},
2222
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/embedded-types"
2323
},
24-
"BaseAlias": {
25-
"description": "BaseAlias aliases Base so that embedding it exercises the alias branch\nof buildEmbedded.",
24+
"EmbedsAlias": {
2625
"type": "object",
26+
"title": "EmbedsAlias embeds an aliased named struct.",
2727
"required": [
2828
"id"
2929
],
3030
"properties": {
31+
"extra": {
32+
"type": "string",
33+
"x-go-name": "Extra"
34+
},
3135
"id": {
3236
"type": "integer",
3337
"format": "int64",
@@ -40,24 +44,6 @@
4044
},
4145
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/embedded-types"
4246
},
43-
"EmbedsAlias": {
44-
"title": "EmbedsAlias embeds an aliased named struct.",
45-
"allOf": [
46-
{
47-
"$ref": "#/definitions/BaseAlias"
48-
},
49-
{
50-
"type": "object",
51-
"properties": {
52-
"extra": {
53-
"type": "string",
54-
"x-go-name": "Extra"
55-
}
56-
}
57-
}
58-
],
59-
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/embedded-types"
60-
},
6147
"EmbedsEmptyNamedInterface": {
6248
"type": "object",
6349
"title": "EmbedsEmptyNamedInterface embeds a named empty interface.",

‎fixtures/integration/golden/go123_aliased_spec.json‎

Lines changed: 16 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,16 @@
1212
"x-go-package": "github.com/go-openapi/codescan/fixtures/goparsing/go123/aliased/schema"
1313
},
1414
"ExtendedID": {
15+
"type": "object",
1516
"title": "ExtendedID should be discovered through dependency analysis.",
16-
"allOf": [
17-
{
18-
"$ref": "#/definitions/Empty"
19-
},
20-
{
21-
"type": "object",
22-
"properties": {
23-
"EvenMore": {},
24-
"StillMore": {},
25-
"more": {
26-
"type": "string",
27-
"x-go-name": "More"
28-
}
29-
}
17+
"properties": {
18+
"EvenMore": {},
19+
"StillMore": {},
20+
"more": {
21+
"type": "string",
22+
"x-go-name": "More"
3023
}
31-
],
24+
},
3225
"x-go-package": "github.com/go-openapi/codescan/fixtures/goparsing/go123/aliased/schema"
3326
},
3427
"ShouldSee": {
@@ -75,25 +68,15 @@
7568
"x-go-package": "github.com/go-openapi/codescan/fixtures/goparsing/go123/aliased/schema"
7669
},
7770
"embedded_with_alias": {
78-
"allOf": [
79-
{
80-
"$ref": "#/definitions/Anything"
81-
},
82-
{
83-
"$ref": "#/definitions/UUID"
84-
},
85-
{
86-
"type": "object",
87-
"properties": {
88-
"EvenMore": {},
89-
"StillMore": {},
90-
"more": {
91-
"type": "string",
92-
"x-go-name": "More"
93-
}
94-
}
71+
"type": "object",
72+
"properties": {
73+
"EvenMore": {},
74+
"StillMore": {},
75+
"more": {
76+
"type": "string",
77+
"x-go-name": "More"
9578
}
96-
],
79+
},
9780
"x-go-name": "EmbeddedWithAlias",
9881
"x-go-package": "github.com/go-openapi/codescan/fixtures/goparsing/go123/aliased/schema"
9982
},

‎internal/builders/schema/allof.go‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,14 @@ func (s *Builder) scanEmbeddedFields(
5353
continue
5454
}
5555

56-
_, isAliased := fld.Type().(*types.Alias)
57-
58-
if !fd.IsAllOfMember && !isAliased {
56+
if !fd.IsAllOfMember {
57+
// Plain embed (no `swagger:allOf` annotation) — inline the
58+
// embedded type's properties into the outer schema,
59+
// regardless of whether the embed is a direct named type
60+
// or an alias of one. The previous `!isAliased` guard here
61+
// silently promoted aliased embeds to allOf composition,
62+
// violating the documented contract that allOf is only
63+
// produced for explicitly-annotated embeds.
5964
if target == nil {
6065
target = schema
6166
}

‎internal/builders/schema/embedded.go‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,22 +30,35 @@ func (s *Builder) enterEmbed() func() {
3030

3131
// buildEmbedded routes a struct's embedded-field type to the
3232
// appropriate emitter: pointers are peeled, named types descend into
33-
// `buildNamedEmbedded`, aliases go through `buildAlias`.
33+
// `buildNamedEmbedded`, aliases resolve transparently and dispatch as
34+
// the unaliased type would (so that `type BaseAlias = Base` embedded
35+
// in a struct produces the same inline shape as `Base` embedded
36+
// directly — both Go types are identical to the type system).
3437
//
3538
// # Details
3639
//
3740
// See [§embedded](./README.md#embedded) — the three-arm dispatch and
38-
// the deliberate asymmetry with `buildAllOf` (embeds always inline
39-
// properties, never $ref unless the embed is `swagger:allOf`-tagged).
41+
// the contract that embeds always inline properties, never $ref unless
42+
// the embed is `swagger:allOf`-tagged.
4043
func (s *Builder) buildEmbedded(tpe types.Type, schema *oaispec.Schema, nameByJSON map[string]propOwner) error {
4144
switch ftpe := tpe.(type) {
4245
case *types.Pointer:
4346
return s.buildEmbedded(ftpe.Elem(), schema, nameByJSON)
4447
case *types.Named:
4548
return s.buildNamedEmbedded(ftpe, schema, nameByJSON)
4649
case *types.Alias:
47-
target := NewTypable(schema, 0, s.skipExtensions)
48-
return s.buildAlias(ftpe, target)
50+
// Aliases are transparent in Go; the spec should reflect that.
51+
// Recurse on the unaliased type so the dispatch matches what
52+
// the user would get if they had written the unaliased type
53+
// directly:
54+
// - Alias-to-Named → buildNamedEmbedded (inline)
55+
// - Alias-to-Pointer-to-Named → peel pointer, then inline
56+
// - Alias-to-anonymous-struct → falls to default (warn-skip);
57+
// embedding an anonymous struct via alias is unusual Go
58+
// code that doesn't promote any named fields.
59+
// - Alias-to-primitive / interface → also default; embedding
60+
// these promotes nothing.
61+
return s.buildEmbedded(types.Unalias(ftpe), schema, nameByJSON)
4962
default:
5063
logger.UnsupportedTypeKind("buildEmbedded", ftpe)
5164
return nil

0 commit comments

Comments
 (0)
⌂ 换网址