JSON in Go: tags, omitempty and what encoding/json does silently

What is really being asked

A typical ladder:

1. "How do I make a field have a different name in JSON?" — the warm-up: the json:"name" tag.
2. "What does omitempty do?" — followed straight away by "and an empty struct? and time.Time{}?". This is where people answer from memory and get it wrong.
3. "What happens if the JSON has an extra field? And if a key has different case?" — checks whether the candidate knows that Unmarshal stays quiet.
4. "Why did the wrong id arrive?" — numbers in interface{}.
5. "How does a nil slice differ from an empty one in JSON?" — the API contract with the frontend.
6. "How do you write your own MarshalJSON?" — and where the recursion hides in it.

The ladder has one core: by default encoding/json chooses "carry on" over "report". A field went missing, a key found no field, a number was rounded when float64 was chosen — decoding goes on. That does not mean there are no errors at all: a value of the wrong type or an integer that does not fit into its field gives an error, and it must not be ignored. Each mechanism below is one of the cases where the boundary between the two shows.

What this was checked on: the runs are go1.24.7 and go1.25.1, linux/amd64; documentation quotes were checked against go doc and release notes on 14.10.2026. Everything the lesson calls the behavior of encoding/json refers to v1 — the package "encoding/json". By that date Go 1.26 and 1.27 were out; the lesson was not run on them, and what changed in Go 1.27 according to the release notes is in "Version history".

Base: a field becomes a key, a tag changes the rule

The Marshal documentation states the rule in one sentence:

The same struct without tags and with them.

Fragment of bench/gojson/internals.go — type declarations:

type Address struct {
    City string `json:"city"`
}
 
type Account struct {
    ID       int
    Name     string
    Email    string
    Tags     []string
    Address  Address
    password string
}
 
type AccountTagged struct {
    ID       int      `json:"id"`
    Name     string   `json:"name"`
    Email    string   `json:"email,omitempty"`
    Tags     []string `json:"tags,omitempty"`
    Address  Address  `json:"address,omitempty"`
    Password string   `json:"-"`
}

Output of bench/gojson/internals.go, section 1; labels translated:

1) ONE STRUCT WITHOUT TAGS AND WITH TAGS
────────────────────────────────────────
  no tags:
    {"ID":7,"Name":"Ann","Email":"","Tags":null,"Address":{"city":""}}
  with tags name, omitempty and "-":
    {"id":7,"name":"Ann","address":{"city":""}}

Without tags the key is the Go field name with its capital letter, and all exported fields come out, empty ones too. The unexported password is not there — the package walks the fields through reflect and skips such fields; why is covered in the lesson on reflection. There is one exception — an unexported embedded struct: it is not visible itself, but its exported fields are promoted to the top.

Output, section 1 (continued):

  unexported embedded field:
    Outer{inner{X: 1}, 2}              -> {"X":1,"Y":2}

That lesson also shows how the tag is read through StructTag.Get and what json:"" and json:"-" mean; we will not repeat it.

With tags the keys became lower-case, the empty Email and Tags went away, and Password with the "-" tag did not come out. Yet the empty Address with the same omitempty stayed — that is the first rung of the ladder where people stumble, and Mechanism 1 is about it.

That is enough for a Junior-level answer: exported fields go into JSON; the key is the field name or the name from the json:"…" tag; omitempty skips an empty value, "-" skips the field always. The rest is detail about what "empty" means and what happens on the way back.

Mechanism 1: omitempty — "empty" by the package's rules, not by meaning

The documentation lists what an "empty value" is, in full:

Structs are not on the list — and that is not an oversight. A check with a field of each kind, next to the omitzero option from the same documentation. It exists since Go 1.24 — its release notes say so; on an older Go the omitzero tag will not omit the field.

Output, section 2:

2) OMITEMPTY AND OMITZERO: WHAT COUNTS AS EMPTY
───────────────────────────────────────────────
  field value              with omitempty                       with omitzero
  false                    {}                                   {}
  0                        {}                                   {}
  ""                       {}                                   {}
  (*int)(nil)              {}                                   {}
  &zero (pointer to 0)     {"v":0}                              {"v":0}
  any(nil)                 {}                                   {}
  []int(nil)               {}                                   {}
  []int{}                  {}                                   {"v":[]}
  map[string]int{}         {}                                   {"v":{}}
  [2]int{}                 {"v":[0,0]}                          {}
  struct{}{}               {"v":{}}                             {}
  Address{}                {"v":{"city":""}}                    {}
  time.Time{}              {"v":"0001-01-01T00:00:00Z"}         {}

{} in the table means the field was omitted. Four rows are worth remembering.

time.Time{} with omitempty comes out in JSON as "0001-01-01T00:00:00Z". time.Time is a struct, and a struct is never empty for omitempty. Hence the "year one date" in API responses: a CreatedAt field with omitempty that nobody filled in.

[2]int{} is not empty: the array's length is 2, and the "length zero" rule does not cover it, even though both elements are zero.

A pointer to zero is not empty: omitempty looks at the pointer itself, and it is not nil. That is exactly what people use when they need to tell "field not set" from "field equals zero" — more in "Next they ask".

omitzero works differently. It asks the value for an IsZero() method, and if there is none, compares with the zero value of the type. So it omits structs and time.Time{} (time.Time has IsZero), but keeps the empty non-nil slice []int{} — that is not the zero value of a slice. If both meanings are wanted at once, the two options are given together; the Go 1.24 release notes describe that too: "If both omitempty and omitzero are specified, the field will be omitted if the value is either empty or zero (or both)".

In the source the rule is one function, isEmptyValue (encoding/json/encode.go:318–330 in go1.24.7): array, map, slice and string are checked by Len() == 0, numbers, bool, pointer and interface by IsZero(), and for everything else, structs included, it returns false. Both options are checked by one condition while walking the fields (encode.go:715–716).

Mechanism 2: Unmarshal merges and keeps quiet

The way back follows the same "carry on, don't report" principle, and the documentation says so directly:

A Name field with the tag json:"name".

Output, section 3:

3) UNMARSHAL: KEY CASE AND EXTRA KEYS
─────────────────────────────────────
  {"name":"ann"}                     -> Name="ann" err=<nil>
  {"Name":"ann"}                     -> Name="ann" err=<nil>
  {"NAME":"ann"}                     -> Name="ann" err=<nil>
  {"nAmE":"ann"}                     -> Name="ann" err=<nil>
  Unmarshal into Strict{Name}:
    {"name":"ann","role":"user","is_admin":true}
    -> Name="ann" err=<nil>
  Decoder with DisallowUnknownFields, same input:
    -> Name="ann" err=json: unknown field "role"

The tag name does not make the matching strict: all four spellings filled the field. In the source this is two steps in a row — a lookup by exact name, then by a "folded" name without regard to case (encoding/json/decode.go:694–697 in go1.24.7). The extra role and is_admin vanished without a trace.

A strict mode exists, but only on a Decoder, not on the Unmarshal function:

The error in the run is json: unknown field "role", on the first extra key. And Name is already filled at that point: the check does not cancel the decoding, it adds an error to it.

The second thing Unmarshal does silently is merge the input into what is already in the struct.

Output, section 4:

4) UNMARSHAL INTO A FILLED STRUCT
─────────────────────────────────
  before: {ID:1 Name:Ann Email:ann@example.com Tags:[a b c] Meta:map[visits:3]}
  input:  {"name":"Bob","tags":["z"],"meta":{"likes":5},"email":null}
  after:  {ID:1 Name:Bob Email:ann@example.com Tags:[z] Meta:map[likes:5 visits:3]}
  err=<nil>

Four different outcomes in one line. There is no id in the input — ID stayed 1. email: null for a string field changed nothing: the documentation says exactly that — "unmarshaling a JSON null into any other Go type has no effect on the value and produces no error". The tags slice was cut to zero length and refilled — [z] instead of [a b c]. And the meta map was added to: the old key visits stayed next to the new likes.

Slices have a subtlety. The documentation describes decoding into a slice like this: "resets the slice length to zero and then appends each element to the slice". The array underneath stays the old one, and struct elements are merged with the old ones just like the struct itself.

Output, section 4 (continued):

  before: {Items:[{A:1 B:2} {A:3 B:4}] Tags:[a b c]}
  input:  {"items":[{"a":5}],"tags":["z"]}
  after:  {Items:[{A:5 B:2}] Tags:[z]}
  err=<nil>
  the old slice old after decoding: [z b c]

B:2 in the new element comes from the old {1 2}: the input had only a. And old, which sat in the Tags field before decoding, now shows [z b c] — z was written into its array.

The practical consequence: a struct that something has already been decoded into cannot be reused for the next message — the fields absent from it will keep their values from before. Each input gets a fresh variable.

And the last thing — a type error does not stop the decoding.

Output, section 4 (end):

  type mismatch:  {"id":"7","name":"Bob"}
    -> ID=0 Name="Bob"
    err=json: cannot unmarshal string into Go struct field Profile.id of type int

ID was skipped, Name was filled, the error was returned. The documentation promises less than the run showed: "it's not guaranteed that all the remaining fields following the problematic one will be unmarshaled into the target object". Code that looks at the fields without checking err gets a half-filled struct — and which half is not known in advance.

Mechanism 3: numbers in any — float64, precision and a range error

When the destination is an interface{} or a map[string]any, there is no field type, and the package chooses one itself. For numbers there is one choice — "float64, for JSON numbers". A float64 has 53 significant bits, and not every integer above 2^53 can be represented.

Output, section 5:

5) NUMBERS IN any: FLOAT64 AND LOST PRECISION
─────────────────────────────────────────────
  input                     {"id":9007199254740993}
  into map[string]any:      9.007199254740992e+15 (float64)
  int64(f)                  9007199254740992
  json.Marshal back         {"id":9007199254740992}

9007199254740993 is 2^53 + 1. It cannot be written exactly in a float64, and decoding rounded it to 2^53 — without an error: that is how strconv.ParseFloat works (convertNumber, encoding/json/decode.go:833–842 in go1.24.7). And on the way back the JSON already carries a different id. A proxy service that decodes a request into map[string]any and forwards it corrupts identifiers without saying a word.

Three ways to avoid it.

Output, section 5 (continued):

  with UseNumber:           9007199254740993 (json.Number)
  n.Int64()                 9007199254740993
  into struct{ ID int64 }:  9007199254740993
  2^53 =                    9007199254740992
  with the ",string" tag:   {"id":"9007199254740993"}
  and back:                 9007199254740993 err=<nil>

Decoder.UseNumber puts a json.Number into the interface — a string with the number's original spelling, and Int64() returns it exactly. A field of type int64 solves the problem without settings: when the type is known, the package decodes the number straight into it. The ,string tag writes the number as a string — {"id":"9007199254740993"}. That is not for Go but for the other side; the documentation names the case directly: "This extra level of encoding is sometimes used when communicating with JavaScript programs". A parser on that side that reads numbers into float64 will corrupt an id above 2^53 exactly as any does in Go.

It is important not to confuse lost precision with an error. Rounding happens when the package itself chose float64 — in an any. If the field type is given and the number does not fit into it, Unmarshal returns an error.

Output, section 11:

11) LOST PRECISION OR AN ERROR: A NUMBER OUTSIDE int64
──────────────────────────────────────────────────────
  input: {"id":9223372036854775808}  (2^63, one more than MaxInt64)
  into struct{ ID int64 }:  ID=0
    err=json: cannot unmarshal number 9223372036854775808 into Go struct field Row.id of type int64
  into map[string]any:      9.223372036854776e+18 err=<nil>

The documentation names this case directly: "if a JSON number overflows the target type, Unmarshal skips that field and completes the unmarshaling as best it can", and returns an UnmarshalTypeError. The ID field stayed zero — without checking err, that zero goes on as a real id.

,string has a flip side — it demands a string when reading, too.

Output, section 5 (end):

  ",string", but a number came: err=json: invalid use of ,string struct tag, trying to unmarshal unquoted value into int64

Mechanism 4: value shapes the package picks by itself

Some decisions the package makes for you without asking.

Output, section 6:

6) VALUE SHAPES
───────────────
  []string(nil)                  -> null
  []string{}                     -> []
  map[string]int(nil)            -> null
  []byte("hi")                   -> "aGk="
  []uint8{1, 2, 3}               -> "AQID"
  map{zeta alpha Mid beta}       -> {"Mid":3,"alpha":2,"beta":4,"zeta":1}
  map[int]string{10:"a", 9:"b"}  -> {"10":"a","9":"b"}
  "<b>Tom & Jerry</b>"           -> "\u003cb\u003eTom \u0026 Jerry\u003c/b\u003e"
  Encoder, SetEscapeHTML(false)  -> "<b>Tom & Jerry</b>"
  math.NaN()                     -> error: json: unsupported value: NaN
  math.Inf(1)                    -> error: json: unsupported value: +Inf
  struct{ V float64 }{NaN}       -> error: json: unsupported value: NaN
  make(chan int)                 -> error: json: unsupported type: chan int

A nil slice is null, an empty one is []. For Go the two are almost the same; for a client they are not: it expected an array and got null. A slice that could have stayed nil — var items []Item without a single append — goes out as null. If the API contract promises an array, the slice is created explicitly: items := []Item{} or make([]Item, 0).

[]byte is a base64 string, not an array of numbers: []uint8{1, 2, 3} is "AQID". The documentation calls this an exception to the rule for slices: "except that []byte encodes as a base64-encoded string, and a nil slice encodes as the null JSON value".

Map keys are sorted — and the sort is byte-wise: "Mid" comes before "alpha" because upper-case letters come before lower-case ones in ASCII, and the integer keys 10 and 9 are turned into strings and compared as strings — "10" before "9" (slices.SortFunc with strings.Compare, encode.go:762–776). That is why Marshal output for a map is deterministic and can be compared in tests.

<, > and & are escaped as \u003c, \u003e, \u0026 — so that the JSON can be placed in HTML: the documentation explains it by the JSON having to be "safe to embed inside HTML <script> tags". The string after decoding is the same, the bytes are different — whoever compares texts or signs them will see the difference. It can be turned off only on an Encoder: SetEscapeHTML(false).

An error comes only where JSON cannot express the value. NaN and ±Inf do not exist in JSON, and Marshal returns an UnsupportedValueError (encode.go:540–543); channels and functions give an UnsupportedTypeError. One NaN deep inside a struct — and the whole response is not built.

Mechanism 5: your own MarshalJSON — the address and the recursion

A type controls its own JSON if it implements json.Marshaler — the method MarshalJSON() ([]byte, error). There are two traps here.

The first is the pointer receiver. Cents declares MarshalJSON on *Cents and writes the amount as the string "12.34". The sign and the magnitude are formatted separately — why, right after the run block.

Fragment of bench/gojson/internals.go:

type Cents int64
 
func (c *Cents) MarshalJSON() ([]byte, error) {
    n := int64(*c)
    sign, u := "", uint64(n)
    if n < 0 {
        sign, u = "-", -u
    }
    return []byte(fmt.Sprintf(`"%s%d.%02d"`, sign, u/100, u%100)), nil
}
 
type Invoice struct {
    Total Cents `json:"total"`
}

Output, section 7:

7) MARSHALJSON ON A POINTER: WHEN IT IS NOT CALLED
──────────────────────────────────────────────────
  json.Marshal(c)                -> 1234
  json.Marshal(&c)               -> "12.34"
  json.Marshal(inv)              -> {"total":1234}
  json.Marshal(&inv)             -> {"total":"12.34"}
  []Invoice{inv}                 -> [{"total":"12.34"}]
  map[string]Invoice{"a": inv}   -> {"a":{"total":1234}}

One and the same Invoice gave two different JSONs — and not a single error. A method with a *Cents receiver exists only for something whose address can be taken. inv, passed by value, sits in the interface as a copy without an address — there is no method, and the field is encoded as an ordinary number. A slice element is addressable, a map value is not. In the source this is a separate encoder that asks CanAddr() on every value and picks the path (condAddrEncoder, encode.go:396 and 913–918). The rule is the same as in the lesson on method receivers; here it just produces no compile error, because Marshal takes an any.

About the formula inside the method. Shorter would be n/100 and n%100, but in Go the quotient is truncated towards zero, and the remainder carries the sign of the dividend — in the specification's table -5 % 3 equals -2. For negative amounts such a formula prints the minus twice.

Output, section 10:

10) CENTS: THE NAIVE FORMULA AND NEGATIVE AMOUNTS
─────────────────────────────────────────────────
  value                  n/100, n%100               sign and magnitude apart
  0                      "0.00"                     "0.00"
  1                      "0.01"                     "0.01"
  99                     "0.99"                     "0.99"
  100                    "1.00"                     "1.00"
  -1                     "0.-1"                     "-0.01"
  -100                   "-1.00"                    "-1.00"
  -123                   "-1.-23"                   "-1.23"
  9223372036854775807    "92233720368547758.07"     "92233720368547758.07"
  -9223372036854775808   "-92233720368547758.-8"    "-92233720368547758.08"

The JSON is syntactically valid — what is wrong is the amount inside the string. The magnitude is taken as a uint64: there -u does not overflow, and the formula is right even for math.MinInt64, where -n in int64 would overflow.

Hence the advice: declare MarshalJSON on the value if it does not need to change the receiver. UnmarshalJSON is declared on the pointer — otherwise it writes into a copy.

The second trap is recursion. A common task: "produce the usual JSON, but add one field". The first thing people write.

Fragment — deliberately wrong; the full file is bench/gojson/cases/recursion/main.go:

func (e Event) MarshalJSON() ([]byte, error) {
    b, err := json.Marshal(e)
    ...
}

json.Marshal(e) finds the same MarshalJSON on e and calls it. This is not a panic but a stack overflow — a fatal runtime error. The test program has a defer with recover in main, and it did not fire.

Output of bench/gojson/recursion.sh, section 1; labels translated:

1) json.Marshal(e) CALLED INSIDE MARSHALJSON
────────────────────────────────────────────
  runtime: goroutine stack exceeds 1048576-byte limit
  fatal error: stack overflow
  recover in main did not fire: no "recover caught" line in the output
  exit code: 2
  one turn of the cycle in the stack trace of goroutine 1 (callee on top):
    encoding/json.Marshal
    main.Event.MarshalJSON
    main.(*Event).MarshalJSON
    encoding/json.marshalerEncoder
    encoding/json.condAddrEncoder.encode
    encoding/json.condAddrEncoder.encode-fm
    encoding/json.(*encodeState).reflectValue
    encoding/json.(*encodeState).marshal
    encoding/json.Marshal

The stack limit in the test program is lowered to 1 MB so that the crash comes quickly. The usual limit on a 64-bit platform is 1 GB (runtime/proc.go:157–158 in go1.24.7), but the recursion is infinite and will hit any limit. The whole process goes down, not one request.

The cure is a twin type: inside the method, a new type with the same fields is declared, and that is what gets encoded. The specification guarantees that the new type does not inherit the methods of Event itself — but only those:

Fragment of bench/gojson/internals.go — the fix:

func (e Event) MarshalJSON() ([]byte, error) {
    type event Event
    return json.Marshal(struct {
        event
        At   int64  `json:"at"`
        Kind string `json:"kind"`
    }{event(e), e.At.Unix(), "event:" + e.Kind})
}

Output of bench/gojson/internals.go, section 8:

8) MARSHALJSON WITHOUT RECURSION: A TWIN TYPE
─────────────────────────────────────────────
  json.Marshal(ev)         -> {"id":5,"at":1790856000,"kind":"event:login"}
  json.Marshal(plain(ev))  -> {"id":5,"at":"2026-10-01T12:00:00Z"}

event is embedded in an anonymous struct, and its fields came out at the top level; the outer At and Kind at depth 0 overrode the same-named ones at depth 1 — as in the lesson on embedding. The second line is the same Event without the method: the time as a string, no kind.

The second half of the quote is the caveat people forget: the methods of embedded fields stay with the twin. If Event embeds time.Time, its MarshalJSON is promoted into the anonymous struct, and a bare time string comes out instead of the object — without an error.

Output, section 9:

9) THE TWIN DOES NOT SAVE YOU FROM AN EMBEDDED FIELD'S METHODS
──────────────────────────────────────────────────────────────
  json.Marshal(st)  -> "2026-10-01T12:00:00Z" err=<nil>
  type stampTwin Stamp implements json.Marshaler: true

Stamp here is the same Event, except the time is embedded rather than held in an At field. id and kind are gone. That is why a field with its own MarshalJSON is not embedded in such a struct but declared as a named field.

The twin must be a new type, not an alias. type event = Event with the = sign is just another name for the same type, and its methods are the same. Worse: embedded in an anonymous struct, it promotes MarshalJSON into that struct itself — the cycle now goes through the anonymous type.

Output of bench/gojson/recursion.sh, section 2 — the deliberately wrong variant:

2) ALIAS TWIN: type event = Event
─────────────────────────────────
  runtime: goroutine stack exceeds 1048576-byte limit
  fatal error: stack overflow
  exit code: 2
  one turn of the cycle in the stack trace of goroutine 1 (callee on top):
    encoding/json.Marshal
    main.Event.MarshalJSON
    go:(*struct { main.event = main.Event; Kind string "json:\"kind\"" }).MarshalJSON

A single = character is the difference between a working method and a dead process.

Deeper: what encoding/json costs and where the cost is

"JSON in Go is slow because of reflection" is a phrase said more often than measured. Below is what was observed in one configuration; the mechanism explains why the two sides differ, and your own ratios must be measured on your side. And this measures the old implementation: in Go 1.27 encoding/json runs on v2, and the release notes promise "significantly faster" Unmarshal with Marshal at parity — the lesson did not measure that. A five-field struct, four ways.

Output of bench/gojson/cost.go; labels translated:

1) ONE STRUCT WITH FIVE FIELDS
──────────────────────────────
  {"id":90210,"customer":"Ann Smith","total":12345,"paid":true,"items":["book","pen","lamp"]}
  91 bytes; manual assembly gives the same bytes: true

  method                               ns/op allocs bytes
  json.Marshal(&o)                     340.0      1    96
  manual assembly (strconv.Append*)    184.3      1    96
  json.Unmarshal into Order           2044.3     13   432
  json.Unmarshal into map[string]any  2498.8     33   896

  Marshal vs manual assembly            1.8x
  Unmarshal into a struct vs Marshal    6.0x
  Unmarshal into a map vs into Order    1.2x

In this measurement Marshal cost 1.8 times more than assembling the same string by hand — and allocated just as much: one allocation of 96 bytes, the result itself. The package parses tags and finds fields once per type and caches the result — that cache and the cost of looking a field up by name are covered in detail in the lesson on reflection. What remains per call is walking the fields by a ready-made description plus checks, not "reflection" in the sense of searching by names.

The expensive side was Unmarshal: 6.0 times more than Marshal in the run record, and 13 allocations instead of one. The allocation count is an observation of the go1.24.7 implementation, not a contract of the package. Every string of the input is copied into a new Go string (encoding/json/decode.go:953–957 in go1.24.7), and the items slice grows as decoding proceeds — Grow when the capacity runs out (decode.go:545–548). And the package goes over the input twice: before filling the struct, Unmarshal checks the whole syntax — "Avoids filling out half a data structure before discovering a JSON syntax error" (checkValid, encoding/json/decode.go:102 in go1.24.7). Decoding into map[string]any is more expensive still — 1.2 times in the run record — and gives 33 allocations: an interface for each value, a map for the object.

Conclusions for design:

Manual assembly won by less than a factor of two in the measurement, and it produced the same bytes only because the strings here are ASCII without quotes: in general strconv.AppendQuote escapes differently from JSON. Rewriting Marshal by hand for such a difference is rarely justified; in the measurement the expensive side is decoding the input.

How to answer in an interview

Short answer: exported fields go into JSON, the key is the field name or the json:"…" tag. omitempty skips false, 0, "", nil and empty slices, maps and arrays of length zero, but not structs — which is why time.Time{} comes out as "0001-01-01T00:00:00Z". Unmarshal matches fields without regard to case, skips extra keys silently and does not touch fields absent from the input.

That is enough to answer correctly. What follows is what people add if the interviewer digs.

If the interviewer digs deeper

On "and an empty struct with omitempty?" — the rule and the replacement. "A struct is never empty for omitempty: in the run Address{} came out as {"city":""}, and time.Time{} as a year-one date. omitzero omits them — on Go 1.24 and newer: it asks IsZero() or compares with the zero value."

On "what happens to an extra field" — strict mode. "It disappears without an error. To reject it — a Decoder with DisallowUnknownFields, error json: unknown field "role". And the key "NAME" fills the field name: case is ignored."

On "why is the id wrong" — float64. "In an any a number becomes a float64, and 9007199254740993 turns into 9007199254740992. The remedies are an int64 field, Decoder.UseNumber, or the ,string tag for JavaScript clients."

On "nil slice" — the contract. "A nil slice is null, an empty one is []. If the API promises an array, the slice is created explicitly."

On "your own MarshalJSON" — two traps. "On a pointer the method is not called for a value without an address: json.Marshal(inv) gave {"total":1234}. And json.Marshal(e) inside the method is infinite recursion and a dead process; inside, declare type event Event — a new type without the methods of Event itself, not an alias."

Next they ask

1) KEY CASE ON UNMARSHAL
────────────────────────
  {"name":"ann"}   v1: Name="ann"  err=<nil>
                   v2: Name="ann"  err=<nil>
  {"NAME":"ann"}   v1: Name="ann"  err=<nil>
                   v2: Name=""     err=<nil>

2) NIL SLICE AND NIL MAP
────────────────────────
  List{}  v1: {"tags":null,"meta":null}
  List{}  v2: {"tags":[],"meta":{}}

3) OMITEMPTY ON A NUMBER
────────────────────────
  Counter{N: 0}  v1: {}
  Counter{N: 0}  v2: {"n":0}

4) MARSHALJSON ON A POINTER, VALUE WITHOUT AN ADDRESS
─────────────────────────────────────────────────────
  json.Marshal(inv)  v1: {"total":1234}
  json.Marshal(inv)  v2: {"total":"12.34"}

5) NULL INTO A FILLED FIELD
───────────────────────────
  {"email":null}  v1: {Name:Ann Email:ann@example.com}
  {"email":null}  v2: {Name:Ann Email:}

6) A REPEATED KEY
─────────────────
  {"name":"a","name":"b"}  v1: Name="b" err=<nil>
  {"name":"a","name":"b"}  v2: Name="a" err=jsontext: duplicate object member name "name"

//go:build ignore
 
// Strict decoding of an HTTP request body: the complete example from the
// encoding/json lesson. Comments and output are in English on purpose: the
// same file is shown in both locales of the lesson.
//
// DisallowUnknownFields alone does not make decoding strict: one Decode call
// reads one value and ignores what follows it, and v1 silently accepts
// duplicate keys. The handler adds the missing steps — a second Decode must
// return io.EOF, and the body size is capped by http.MaxBytesReader — and is
// run on eight request bodies through httptest, without a network.
//
// RUN:
//
//	go run bench/gojson/strict.go
package main
 
import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"runtime"
	"strings"
)
 
type CreateUser struct {
	Name string `json:"name"`
}
 
// decodeStrict decodes exactly one JSON value with no unknown keys.
func decodeStrict(r io.Reader, v any) error {
	dec := json.NewDecoder(r)
	dec.DisallowUnknownFields()
	if err := dec.Decode(v); err != nil {
		return err
	}
	// Nothing but whitespace may follow the value.
	if err := dec.Decode(&struct{}{}); err != io.EOF {
		return errors.New("unexpected data after the JSON value")
	}
	return nil
}
 
func createUser(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 64) // at most 64 bytes
	var u CreateUser
	if err := decodeStrict(r.Body, &u); err != nil {
		var tooBig *http.MaxBytesError
		if errors.As(err, &tooBig) {
			http.Error(w, err.Error(), http.StatusRequestEntityTooLarge)
			return
		}
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}
	fmt.Fprintf(w, "ok: name=%q", u.Name)
}
 
func main() {
	fmt.Printf("%s %s/%s | strict decoding of an HTTP request body\n",
		runtime.Version(), runtime.GOOS, runtime.GOARCH)
	fmt.Println()
	fmt.Println("1) HANDLER createUser ON EIGHT REQUEST BODIES")
	fmt.Println("─────────────────────────────────────────────")
	long := `{"name":"` + strings.Repeat("a", 100) + `"}`
	cases := []struct{ label, body string }{
		{`{"name":"ann"}`, `{"name":"ann"}`},
		{`{"name":"ann"}` + "\\n", `{"name":"ann"}` + "\n"},
		{`{"name":"ann","role":"admin"}`, `{"name":"ann","role":"admin"}`},
		{`{"name":"ann"} {}`, `{"name":"ann"} {}`},
		{`{"name":"ann"}x`, `{"name":"ann"}x`},
		{`{"name":"a","name":"b"}`, `{"name":"a","name":"b"}`},
		{`(empty body)`, ``},
		{`{"name":"<100 x a>"}`, long},
	}
	for _, c := range cases {
		req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(c.body))
		rec := httptest.NewRecorder()
		createUser(rec, req)
		fmt.Printf("  %-31s -> %d %s\n", c.label, rec.Code, strings.TrimSpace(rec.Body.String()))
	}
}

1) HANDLER createUser ON EIGHT REQUEST BODIES
─────────────────────────────────────────────
  {"name":"ann"}                  -> 200 ok: name="ann"
  {"name":"ann"}\n                -> 200 ok: name="ann"
  {"name":"ann","role":"admin"}   -> 400 json: unknown field "role"
  {"name":"ann"} {}               -> 400 unexpected data after the JSON value
  {"name":"ann"}x                 -> 400 unexpected data after the JSON value
  {"name":"a","name":"b"}         -> 200 ok: name="b"
  (empty body)                    -> 400 EOF
  {"name":"<100 x a>"}            -> 413 http: request body too large

Common misconceptions

Version history

The lesson's measurements were taken on go1.24.7 and go1.25.1, linux/amd64; quotes were checked on 14.10.2026. The Go 1.24 and Go 1.27 rows rest on the release notes. Without the flag, the behavior of encoding/json did not change between go1.24.7 and go1.25.1 in the run: internals.go prints the same output apart from the version line (runs/internals-go1.25.txt).

Practice

Two tasks. Answer first, then check against the real output: in both, the correct answer is taken from the script's run, not assigned.

b, _ := json.Marshal(Item{})
fmt.Println(string(b))
var u User
err := json.Unmarshal(input, &u)
fmt.Println(u.Name, err)
var m map[string]any
json.Unmarshal(big, &m)
fmt.Println(int64(m["id"].(float64)))

{"created":"0001-01-01T00:00:00Z"}
ann <nil>
9007199254740992

{}
ann <nil>
9007199254740993

{"created":"0001-01-01T00:00:00Z"}
ann json: unknown field "role"
9007199254740993

{}
ann <nil>
9007199254740992

Knowledge check