11// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
22// SPDX-License-Identifier: Apache-2.0
33
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 and EnvelopeAnnotatedAlias bracket the FIELD-reach
32- // site (Q-E): same Go type as BaseAlias / BaseAliasModeled, but
33- // only one carries `swagger:model`. R6 makes the annotation the
34- // gatekeeper for whether an alias surfaces as a first-class spec
35- // entity (definition + $ref by alias name) or dissolves to its
36- // unaliased target. The two envelopes pin both halves on one
37- // canvas.
38- //
39- // 7 decls × 3 modes = 21 base cells, plus indirect impacts on Base /
40- // BaseAlias / BaseAliasModeled / Methods which may surface as
41- // standalone definitions.
42- //
43- // See `.claude/plans/workshops/alias-matrix.md` §5 and
44- // `.claude/plans/workshops/alias-ledger.md` cycles 3 + 4.
4+ // Package alias_calibration_embed exercises the schema builder's
5+ // alias handling at two reach contexts:
6+ //
7+ // 1. Struct embedding — how does an embed produce inline-vs-allOf
8+ // shape across direct named, alias-of-struct, pointer, and
9+ // named-interface embeds?
10+ // 2. Field site — how does an annotated alias differ from an
11+ // unannotated alias when referenced as a struct field?
12+ //
13+ // The decls below pair each direct / alias / pointer embed against
14+ // its bidirectional companion (annotated vs unannotated alias
15+ // variants) so the per-mode shapes are visible side by side in the
16+ // captured goldens.
17+ //
18+ // See the schema builder's alias-handling contract for the rule:
19+ // [§aliases](../../../internal/builders/schema/README.md#aliases).
4520package alias_calibration_embed
4621
4722// Base is the canonical struct used as the embedded target in
@@ -68,9 +43,9 @@ type Methods interface {
6843 Describe () string
6944}
7045
71- // EmbedsDirectStruct embeds Base directly. The B2 probe shape:
72- // FLAT — `{type: object, properties: {id, name, extra}}` with no
73- // allOf composition. Q8 baseline .
46+ // EmbedsDirectStruct embeds Base directly.
47+ // Expected: FLAT — `{type: object, properties: {id, name, extra}}`
48+ // with no allOf composition .
7449//
7550// swagger:model EmbedsDirectStruct
7651type EmbedsDirectStruct struct {
@@ -80,9 +55,10 @@ type EmbedsDirectStruct struct {
8055 Extra string `json:"extra"`
8156}
8257
83- // EmbedsAlias embeds BaseAlias. The B2 probe shape: `allOf:
84- // [{$ref: BaseAlias}, {properties: {extra}}]`. Q8 OUTLIER — same
85- // Go type as EmbedsDirectStruct produces a DIFFERENT spec shape.
58+ // EmbedsAlias embeds BaseAlias (an unannotated alias of Base).
59+ // Expected: FLAT — same shape as EmbedsDirectStruct, because the
60+ // aliased embed dissolves to its named target and contributes
61+ // inline properties (not allOf composition).
8662//
8763// swagger:model EmbedsAlias
8864type EmbedsAlias struct {
@@ -91,8 +67,8 @@ type EmbedsAlias struct {
9167 Extra string `json:"extra"`
9268}
9369
94- // EmbedsPointer embeds *Base. The B2 probe shape : FLAT (pointer is
95- // peeled, then takes the named-direct path). Consistent with
70+ // EmbedsPointer embeds *Base. Expected : FLAT (pointer is peeled,
71+ // then takes the named-direct path). Consistent with
9672// EmbedsDirectStruct.
9773//
9874// swagger:model EmbedsPointer
@@ -102,10 +78,9 @@ type EmbedsPointer struct {
10278 Extra string `json:"extra"`
10379}
10480
105- // EmbedsInterface embeds the named Methods interface. The B2 probe
106- // shape: FLAT — method properties promoted into the outer schema
107- // alongside Tag. Consistent with EmbedsDirectStruct (named embed
108- // of any kind goes through buildNamedEmbedded which inlines).
81+ // EmbedsInterface embeds the named Methods interface. Expected:
82+ // FLAT — method properties promoted into the outer schema
83+ // alongside Tag.
10984//
11085// swagger:model EmbedsInterface
11186type EmbedsInterface struct {
@@ -115,18 +90,12 @@ type EmbedsInterface struct {
11590}
11691
11792// Envelope compares Base and BaseAlias at the FIELD-reach site
118- // (not embed). BaseAlias is intentionally UNANNOTATED — Q-E asks
119- // whether the spec should expose this implementation-detail alias
120- // or dissolve it to the unaliased target.
121- //
122- // Under R6 (the rule the W3 workshop converged on):
93+ // (not embed). BaseAlias is intentionally UNANNOTATED — at field
94+ // sites the unannotated alias dissolves to its unaliased target,
95+ // and the alias produces no `definitions` entry.
12396//
12497// - direct → {$ref: Base}
125- // - viaAlias → {$ref: Base} (alias dissolves; unannotated → no entity)
126- //
127- // Pre-R6 (current Default / Ref behaviour, witnessed by the golden
128- // captured at commit time) leaks the alias name into the field's
129- // $ref target and manufactures a dangling BaseAlias definition.
98+ // - viaAlias → {$ref: Base} (unannotated alias dissolves)
13099//
131100// swagger:model Envelope
132101type Envelope struct {
@@ -137,19 +106,14 @@ type Envelope struct {
137106 ViaAlias BaseAlias `json:"viaAlias"`
138107}
139108
140- // EmbedsAliasOptIn validates the bidirectional Q-D contract: when
141- // the user EXPLICITLY annotates an aliased embed with
142- // `swagger:allOf`, the resulting spec MUST use allOf composition
143- // with a $ref to the embedded type. This is the shape that was
144- // silently produced (without annotation) before the Q-D fix; it
145- // remains available as an explicit opt-in.
146- //
147- // Combined with EmbedsAlias above, this fixture asserts:
148- //
149- // - Without `swagger:allOf` → flat inline (EmbedsAlias)
150- // - With `swagger:allOf` → allOf with $ref (EmbedsAliasOptIn)
109+ // EmbedsAliasOptIn pins the explicit-opt-in side of the embed
110+ // contract: when the user annotates an aliased embed with
111+ // `swagger:allOf`, the spec uses allOf composition with a $ref.
112+ // The unannotated alias still dissolves to the unaliased target —
113+ // `swagger:allOf` governs composition shape only, not identity.
151114//
152- // The annotation is the SOLE gate; no other input flips composition.
115+ // - Without `swagger:allOf` → flat inline (EmbedsAlias above)
116+ // - With `swagger:allOf` → allOf with $ref to Base
153117//
154118// swagger:model EmbedsAliasOptIn
155119type EmbedsAliasOptIn struct {
@@ -161,13 +125,10 @@ type EmbedsAliasOptIn struct {
161125}
162126
163127// EmbedsDirectStructOptIn mirrors EmbedsAliasOptIn but with a
164- // direct named-struct embed instead of an alias embed — checks
165- // that the explicit annotation works on non-aliased embeds too.
166- // Pre-Q-D this case ALREADY worked (named-direct embed with
167- // swagger:allOf → allOf with $ref to Base) — the annotation path
168- // was never broken; only the *implicit* aliased-embed promotion
169- // was wrong. Including this here triangulates: same annotation,
170- // same shape, regardless of alias or direct.
128+ // direct named-struct embed instead of an alias embed —
129+ // triangulates that the explicit annotation works on non-aliased
130+ // embeds too. Same annotation, same shape, regardless of alias or
131+ // direct.
171132//
172133// swagger:model EmbedsDirectStructOptIn
173134type EmbedsDirectStructOptIn struct {
@@ -182,35 +143,34 @@ type EmbedsDirectStructOptIn struct {
182143// annotation is the user's explicit opt-in to exposing the alias
183144// as a first-class spec entity.
184145//
185- // Q-E / R6 cuts the alias-handling rule along the annotation :
146+ // At field / element / allOf-member use sites :
186147//
187148// - BaseAlias (no annotation): aliasing is a Go implementation
188- // detail; field/element use sites dissolve to `Base`, the
189- // alias does not appear in `definitions`.
149+ // detail; use sites dissolve to `Base`, the alias does not
150+ // appear in `definitions`.
190151// - BaseAliasModeled (swagger:model): the alias is a first-class
191- // entity; field/element use sites keep `$ref:
192- // BaseAliasModeled` and the alias gets its own definition
193- // (chain under RefAliases, full structural under Expand,
194- // dissolved under TransparentAliases — modes only affect the
195- // decl shape, not whether it exists ).
152+ // entity; use sites keep `$ref: BaseAliasModeled` and the alias
153+ // gets its own definition (chain under RefAliases, full
154+ // structural under Expand, structural-copy under
155+ // TransparentAliases — modes only affect the decl shape, not
156+ // whether the alias surfaces ).
196157//
197158// swagger:model BaseAliasModeled
198159type BaseAliasModeled = Base
199160
200161// EmbedsAliasModeledOptIn is the bidirectional sibling of
201162// EmbedsAliasOptIn. Both use `swagger:allOf` on the embedded
202- // alias to opt into allOf composition, but they differ in
203- // whether the alias itself is annotated:
163+ // alias to opt into allOf composition, but they differ in whether
164+ // the alias itself is annotated:
204165//
205166// - EmbedsAliasOptIn embeds BaseAlias (UNannotated)
206- // → allOf $ref dissolves to Base (R6 — alias name not exposed)
167+ // → allOf $ref dissolves to Base (alias name not exposed)
207168// - EmbedsAliasModeledOptIn embeds BaseAliasModeled (annotated)
208- // → allOf $ref preserves BaseAliasModeled (R6 — annotated = first-class)
169+ // → allOf $ref preserves BaseAliasModeled (annotated → first-class)
209170//
210- // The pair pins both halves of the R6 contract under allOf
211- // composition. `swagger:allOf` governs the SHAPE (composition vs
212- // flat inline); `swagger:model` governs the IDENTITY (whether the
213- // alias name appears as a $ref target). They are orthogonal.
171+ // `swagger:allOf` governs the SHAPE (composition vs flat inline);
172+ // `swagger:model` governs the IDENTITY (whether the alias name
173+ // appears as a $ref target). They are orthogonal.
214174//
215175// swagger:model EmbedsAliasModeledOptIn
216176type EmbedsAliasModeledOptIn struct {
@@ -224,11 +184,11 @@ type EmbedsAliasModeledOptIn struct {
224184// It exposes the ANNOTATED alias `BaseAliasModeled` at a field
225185// site, alongside a direct `Base` field for comparison. Combined
226186// with Envelope (which exercises the UNANNOTATED `BaseAlias`),
227- // the two structs pin both halves of the Q-E / R6 contract on one
228- // canvas:
187+ // the two structs pin both halves of the field-site contract on
188+ // one canvas:
229189//
230190// Envelope.direct → {$ref: Base}
231- // Envelope.viaAlias → {$ref: Base} (R6: unannotated dissolves)
191+ // Envelope.viaAlias → {$ref: Base} (unannotated dissolves)
232192// EnvelopeAnnotatedAlias.direct → {$ref: Base}
233193// EnvelopeAnnotatedAlias.viaAliasModeled → {$ref: BaseAliasModeled}
234194//
@@ -237,9 +197,10 @@ type EnvelopeAnnotatedAlias struct {
237197 // Direct field of type Base — control for comparison.
238198 Direct Base `json:"direct"`
239199
240- // ViaAliasModeled — annotated alias as a field type. Under R6
241- // this must keep its alias identity at the use site
200+ // ViaAliasModeled — annotated alias as a field type. The
201+ // annotated alias keeps its identity at the use site
242202 // regardless of mode (Default / Ref); Transparent still
243- // dissolves it because Transparent supersedes annotation.
203+ // dissolves at use sites because Transparent supersedes
204+ // annotation.
244205 ViaAliasModeled BaseAliasModeled `json:"viaAliasModeled"`
245206}
0 commit comments