Skip to content

Commit 53747ca

Browse files
fredbiclaude
andcommitted
fix(schema): emit the properties encoding/json actually marshals
Two readings of the `json:"-"` tag diverged from the wire, in opposite directions. A promoted field re-declared with `json:"-"` was deleted from the schema. Go does not hide it: a `-` field is ignored entirely, never enters the name set, and so shadows nothing — the embedded field keeps marshalling. The schema understated what the API returns. The property stays now, and the existing hint continues to point at `swagger:omit`, which drops it for real; the intent behind the tag is real even though the mechanism does not work. The `json:"-,"` escape, which names a field literally `-`, was dropped instead of emitted. encoding/json compares the whole tag to `-`, so a trailing comma names rather than skips; splitting on the comma first conflated the two. `-` is now accepted as a name from the json tag alone — no other tag type has an encoding rule to appeal to. Both were pinned as contracts. `TestOverridingOneIgnore` asserted two properties where the wire carries three, and the corpus has carried `IgnoredOther string` under `json:"-,omitempty"` since long before this, its name recording the assumption rather than the behaviour. A fixture comment likewise credited Go's depth rule for shadowing a `-` re-declaration, which it does not do. All three now say what Go does. The witness is differential, because this corpus has an oracle: the right answer is not a design choice but whatever encoding/json produces. The fixture module marshals its own types and commits the resulting key sets; the integration test scans the same types and asserts the property sets match. Neither side writes an expectation down. Controls for the shapes that were already correct — a re-declaration under a real name, an ignore with nothing to shadow, and an embed tagged `-` — travel with them, so a future change cannot quietly trade one for another. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 23a9d1e commit 53747ca

14 files changed

Lines changed: 535 additions & 25 deletions

File tree

‎fixtures/enhancements/default-allof-embeds-override/api.go‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,15 @@
55
// field-override embed under Options.DefaultAllOfForEmbeds.
66
//
77
// The override idiom (go-swagger#1992): a struct embeds a shared, annotation-free
8-
// domain type and RE-DECLARES one of the promoted fields — either to decorate it
9-
// (`read only: true`, description, validations) or to drop it from the wire with
10-
// `json:"-"`. Go resolves this by depth: the outer field shadows the promoted one,
11-
// so exactly one field of that name exists at the shallowest depth.
8+
// domain type and RE-DECLARES one of the promoted fields to decorate it
9+
// (`read only: true`, description, validations). Go resolves this by depth: the
10+
// outer field shadows the promoted one, so exactly one field of that name exists
11+
// at the shallowest depth.
12+
//
13+
// `json:"-"` is NOT part of that idiom, though it looks like it. encoding/json
14+
// ignores a `-` field entirely — it never enters the name set, so it shadows
15+
// nothing and the promoted field keeps marshalling. `swagger:omit` on the embed is
16+
// what actually drops a promoted field.
1217
//
1318
// Inlined (the default), the schema builder mirrors that: the re-declaration wins
1419
// and one property is emitted. Composed into `allOf` by DefaultAllOfForEmbeds, the
@@ -36,7 +41,10 @@ type Decorated struct {
3641
ID int64
3742
}
3843

39-
// Muted re-declares a promoted field to drop it from the wire.
44+
// Muted re-declares a promoted field with `json:"-"`, INTENDING to drop it from
45+
// the wire — and fails to, because Go ignores such a field rather than letting it
46+
// shadow. Created stays on the wire and in the schema; the scan raises
47+
// `scan.shadowed-embed-field` pointing at swagger:omit.
4048
//
4149
// swagger:model Muted
4250
type Muted struct {
Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// Package json_tag_fidelity witnesses that the emitted property set matches what
5+
// `encoding/json` actually puts on the wire, for every shape of the `json:"-"`
6+
// tag.
7+
//
8+
// This corpus has an ORACLE, which is unusual: the correct answer is not a design
9+
// choice, it is whatever encoding/json does. `wire_test.go` marshals each type
10+
// here and captures the resulting key set as `wire.golden.json`; the integration
11+
// test scans the same types and asserts the property sets agree. Neither side
12+
// hard-codes an expectation.
13+
//
14+
// Values are chosen non-zero so `omitempty` never hides a key that the wire would
15+
// otherwise carry.
16+
package json_tag_fidelity
17+
18+
// Base is the shared embedded type. Every promoted name below comes from here.
19+
type Base struct {
20+
// ID is a plain promoted field.
21+
ID int64 `json:"id"`
22+
23+
// Name is a plain promoted field.
24+
Name string `json:"name"`
25+
26+
// Age is the field the outer structs re-declare.
27+
Age int32 `json:"age"`
28+
}
29+
30+
// IgnoreShadow re-declares a promoted field with `json:"-"`.
31+
//
32+
// encoding/json ignores a `-` field ENTIRELY: it never enters the name set, so it
33+
// does not shadow the promoted `age`, which Go still marshals. An author writing
34+
// this usually means "drop it" — `swagger:omit` on the embed is the honest way to
35+
// say that, and the scan raises a Hint pointing there.
36+
//
37+
// swagger:model IgnoreShadow
38+
type IgnoreShadow struct {
39+
Base
40+
41+
Age int32 `json:"-"`
42+
}
43+
44+
// RenameShadow re-declares a promoted field under a real name — the control.
45+
// Here Go's depth rule DOES apply and the outer declaration wins.
46+
//
47+
// swagger:model RenameShadow
48+
type RenameShadow struct {
49+
Base
50+
51+
Age int32 `json:"age"`
52+
}
53+
54+
// PlainIgnore carries `json:"-"` with nothing to shadow — the control for the
55+
// common case, where dropping the property is correct.
56+
//
57+
// swagger:model PlainIgnore
58+
type PlainIgnore struct {
59+
// Keep stays on the wire.
60+
Keep string `json:"keep"`
61+
62+
// Drop is ignored entirely by encoding/json.
63+
Drop string `json:"-"`
64+
}
65+
66+
// DashName uses the `json:"-,"` escape, which names the field literally `-`
67+
// rather than ignoring it. The trailing comma is the whole difference.
68+
//
69+
// swagger:model DashName
70+
type DashName struct {
71+
// Weird is emitted under the name "-".
72+
Weird string `json:"-,"`
73+
}
74+
75+
// DashNameOmitEmpty is the `-,omitempty` variant, which the historic corpus
76+
// already contains (classification/models/nomodel.go). Non-zero here, so the key
77+
// is present on the wire.
78+
//
79+
// swagger:model DashNameOmitEmpty
80+
type DashNameOmitEmpty struct {
81+
// Weird is emitted under the name "-" when non-empty.
82+
Weird string `json:"-,omitempty"`
83+
}
84+
85+
// EmbedIgnored tags the EMBED itself `json:"-"`, which does drop the whole embed
86+
// — the control showing that `-` on an embed and `-` on a re-declaration are
87+
// different acts.
88+
//
89+
// swagger:model EmbedIgnored
90+
type EmbedIgnored struct {
91+
Base `json:"-"`
92+
93+
// Extra is the only field that survives.
94+
Extra string `json:"extra"`
95+
}
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"DashName": [
3+
"-"
4+
],
5+
"DashNameOmitEmpty": [
6+
"-"
7+
],
8+
"EmbedIgnored": [
9+
"extra"
10+
],
11+
"IgnoreShadow": [
12+
"age",
13+
"id",
14+
"name"
15+
],
16+
"PlainIgnore": [
17+
"keep"
18+
],
19+
"RenameShadow": [
20+
"age",
21+
"id",
22+
"name"
23+
]
24+
}
Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package json_tag_fidelity
5+
6+
import (
7+
"encoding/json"
8+
"os"
9+
"path/filepath"
10+
"reflect"
11+
"sort"
12+
"testing"
13+
)
14+
15+
// This is the only test in the fixtures module, and it earns the exception: it
16+
// produces the ORACLE for the json-tag-fidelity corpus.
17+
//
18+
// The types live here, so only this package can marshal them. The integration
19+
// test cannot import across the module boundary (the library must not gain a
20+
// dependency on its own fixtures), so the two sides meet at a committed
21+
// artifact instead: this test writes the wire key set, the integration test
22+
// asserts the emitted property set matches it. Neither hard-codes an answer.
23+
//
24+
// Regenerate with UPDATE_GOLDEN=1, like every other golden in the repo.
25+
const wireGolden = "wire.golden.json"
26+
27+
func TestWireShapes(t *testing.T) {
28+
// Non-zero values throughout, so `omitempty` never hides a key.
29+
subjects := map[string]any{
30+
"IgnoreShadow": IgnoreShadow{Base: Base{ID: 1, Name: "n", Age: 42}, Age: 99},
31+
"RenameShadow": RenameShadow{Base: Base{ID: 1, Name: "n", Age: 42}, Age: 99},
32+
"PlainIgnore": PlainIgnore{Keep: "k", Drop: "d"},
33+
"DashName": DashName{Weird: "w"},
34+
"DashNameOmitEmpty": DashNameOmitEmpty{Weird: "w"},
35+
"EmbedIgnored": EmbedIgnored{Base: Base{ID: 1, Name: "n", Age: 42}, Extra: "x"},
36+
}
37+
38+
got := make(map[string][]string, len(subjects))
39+
for name, v := range subjects {
40+
raw, err := json.Marshal(v)
41+
if err != nil {
42+
t.Fatalf("marshal %s: %v", name, err)
43+
}
44+
var obj map[string]json.RawMessage
45+
if err := json.Unmarshal(raw, &obj); err != nil {
46+
t.Fatalf("unmarshal %s (%s): %v", name, raw, err)
47+
}
48+
keys := make([]string, 0, len(obj))
49+
for k := range obj {
50+
keys = append(keys, k)
51+
}
52+
sort.Strings(keys)
53+
got[name] = keys
54+
}
55+
56+
data, err := json.MarshalIndent(got, "", " ")
57+
if err != nil {
58+
t.Fatal(err)
59+
}
60+
data = append(data, '\n')
61+
62+
path := filepath.Join(".", wireGolden)
63+
if os.Getenv("UPDATE_GOLDEN") == "1" {
64+
const filePerm = 0o600
65+
if err := os.WriteFile(path, data, filePerm); err != nil {
66+
t.Fatal(err)
67+
}
68+
t.Logf("wrote %s", wireGolden)
69+
70+
return
71+
}
72+
73+
want, err := os.ReadFile(path)
74+
if err != nil {
75+
t.Fatalf("missing %s — run with UPDATE_GOLDEN=1 to create: %v", wireGolden, err)
76+
}
77+
if !reflect.DeepEqual(string(want), string(data)) {
78+
t.Errorf("wire shapes drifted.\nwant:\n%s\ngot:\n%s", want, data)
79+
}
80+
}

‎fixtures/goparsing/classification/models/nomodel.go‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,12 @@ type NoModel struct {
3636
// default: 11
3737
ID int64 `json:"id"`
3838

39-
Ignored string `json:"-"`
39+
// Ignored is skipped entirely: the whole json tag is "-".
40+
Ignored string `json:"-"`
41+
42+
// IgnoredOther is NOT ignored, despite the name it was given here long ago: the
43+
// trailing comma makes "-" the field's literal wire name. encoding/json compares
44+
// the whole tag to "-", so `-,omitempty` names rather than skips.
4045
IgnoredOther string `json:"-,omitempty"`
4146

4247
// A field which has omitempty set but no name

‎fixtures/integration/golden/enhancements_embed_override.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,12 @@
3737
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/default-allof-embeds-override"
3838
},
3939
"Muted": {
40+
"description": "Muted re-declares a promoted field with `json:\"-\"`, INTENDING to drop it from\nthe wire — and fails to, because Go ignores such a field rather than letting it\nshadow. Created stays on the wire and in the schema; the scan raises\n`scan.shadowed-embed-field` pointing at swagger:omit.",
4041
"type": "object",
41-
"title": "Muted re-declares a promoted field to drop it from the wire.",
4242
"properties": {
43+
"Created": {
44+
"type": "string"
45+
},
4346
"ID": {
4447
"type": "integer",
4548
"format": "int64"

‎fixtures/integration/golden/enhancements_embed_override_allof.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/default-allof-embeds-override"
5151
},
5252
"Muted": {
53-
"title": "Muted re-declares a promoted field to drop it from the wire.",
53+
"description": "Muted re-declares a promoted field with `json:\"-\"`, INTENDING to drop it from\nthe wire — and fails to, because Go ignores such a field rather than letting it\nshadow. Created stays on the wire and in the schema; the scan raises\n`scan.shadowed-embed-field` pointing at swagger:omit.",
5454
"allOf": [
5555
{
5656
"type": "object",
Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
{
2+
"swagger": "2.0",
3+
"paths": {},
4+
"definitions": {
5+
"Base": {
6+
"type": "object",
7+
"title": "Base is the shared embedded type. Every promoted name below comes from here.",
8+
"properties": {
9+
"age": {
10+
"description": "Age is the field the outer structs re-declare.",
11+
"type": "integer",
12+
"format": "int32",
13+
"x-go-name": "Age"
14+
},
15+
"id": {
16+
"description": "ID is a plain promoted field.",
17+
"type": "integer",
18+
"format": "int64",
19+
"x-go-name": "ID"
20+
},
21+
"name": {
22+
"description": "Name is a plain promoted field.",
23+
"type": "string",
24+
"x-go-name": "Name"
25+
}
26+
},
27+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
28+
},
29+
"DashName": {
30+
"description": "DashName uses the `json:\"-,\"` escape, which names the field literally `-`\nrather than ignoring it. The trailing comma is the whole difference.",
31+
"type": "object",
32+
"properties": {
33+
"-": {
34+
"description": "Weird is emitted under the name \"-\".",
35+
"type": "string",
36+
"x-go-name": "Weird"
37+
}
38+
},
39+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
40+
},
41+
"DashNameOmitEmpty": {
42+
"description": "DashNameOmitEmpty is the `-,omitempty` variant, which the historic corpus\nalready contains (classification/models/nomodel.go). Non-zero here, so the key\nis present on the wire.",
43+
"type": "object",
44+
"properties": {
45+
"-": {
46+
"description": "Weird is emitted under the name \"-\" when non-empty.",
47+
"type": "string",
48+
"x-go-name": "Weird"
49+
}
50+
},
51+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
52+
},
53+
"EmbedIgnored": {
54+
"description": "EmbedIgnored tags the EMBED itself `json:\"-\"`, which does drop the whole embed\n— the control showing that `-` on an embed and `-` on a re-declaration are\ndifferent acts.",
55+
"type": "object",
56+
"properties": {
57+
"extra": {
58+
"description": "Extra is the only field that survives.",
59+
"type": "string",
60+
"x-go-name": "Extra"
61+
}
62+
},
63+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
64+
},
65+
"IgnoreShadow": {
66+
"description": "encoding/json ignores a `-` field ENTIRELY: it never enters the name set, so it\ndoes not shadow the promoted `age`, which Go still marshals. An author writing\nthis usually means \"drop it\" — `swagger:omit` on the embed is the honest way to\nsay that, and the scan raises a Hint pointing there.",
67+
"type": "object",
68+
"title": "IgnoreShadow re-declares a promoted field with `json:\"-\"`.",
69+
"properties": {
70+
"age": {
71+
"description": "Age is the field the outer structs re-declare.",
72+
"type": "integer",
73+
"format": "int32",
74+
"x-go-name": "Age"
75+
},
76+
"id": {
77+
"description": "ID is a plain promoted field.",
78+
"type": "integer",
79+
"format": "int64",
80+
"x-go-name": "ID"
81+
},
82+
"name": {
83+
"description": "Name is a plain promoted field.",
84+
"type": "string",
85+
"x-go-name": "Name"
86+
}
87+
},
88+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
89+
},
90+
"PlainIgnore": {
91+
"description": "PlainIgnore carries `json:\"-\"` with nothing to shadow — the control for the\ncommon case, where dropping the property is correct.",
92+
"type": "object",
93+
"properties": {
94+
"keep": {
95+
"description": "Keep stays on the wire.",
96+
"type": "string",
97+
"x-go-name": "Keep"
98+
}
99+
},
100+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
101+
},
102+
"RenameShadow": {
103+
"description": "Here Go's depth rule DOES apply and the outer declaration wins.",
104+
"type": "object",
105+
"title": "RenameShadow re-declares a promoted field under a real name — the control.",
106+
"properties": {
107+
"age": {
108+
"type": "integer",
109+
"format": "int32",
110+
"x-go-name": "Age"
111+
},
112+
"id": {
113+
"description": "ID is a plain promoted field.",
114+
"type": "integer",
115+
"format": "int64",
116+
"x-go-name": "ID"
117+
},
118+
"name": {
119+
"description": "Name is a plain promoted field.",
120+
"type": "string",
121+
"x-go-name": "Name"
122+
}
123+
},
124+
"x-go-package": "github.com/go-openapi/codescan/fixtures/enhancements/json-tag-fidelity"
125+
}
126+
}
127+
}

0 commit comments

Comments
 (0)
⌂ 换网址