Unknown Fields and Drift

## What actually happens during the decode When you call `json.Unmarshal(data, &c)` with a struct destination, the decoder walks the JSON object one key at a time. For each key it builds the list of candidate fields on the destination struct and looks for one whose name matches. If it finds a field, it decodes the value into it. **If it finds no field, it does not fail — it parses the value just far enough to skip past it and continues with the next key.** So three separate things are true at once after a decode of `{"maxConnnections": 50}` into a struct whose field is `MaxConns int`: - The input was valid JSON, so there is no syntax error. - No field matched the key, so nothing was assigned. - Nothing failed, so `Unmarshal` returns `nil` and the field is still `0`. The caller sees a successful decode. The only evidence that something was wrong is a value that happens to equal the zero value — which is indistinguishable from "the operator did not set it". ## Why the standard library chose silence The default is tolerant on purpose. A JSON document is often written by something you do not control and evolves faster than your reader does: a payload gains a field, a config template gains a setting for a newer build, an API adds metadata. If an unrecognised key were fatal, every reader would break the moment a writer added anything. Skipping unknown keys lets a program decode the part of a document it understands and ignore the rest. That tolerance is exactly the property that turns a typo into a silent misconfiguration, so the library is asymmetric by design: **lenient by default, strict only when you ask.** ## The two shapes this takes in practice **The typo.** Someone hand-edits a config file or a request body and writes `"reties"`, `"time_out"`, or `"maxConnnections"`. Nothing matches, the setting is dropped, and the process runs on defaults. This is the case the operator experiences as "my change had no effect". **The drift.** A field is renamed in the Go struct — or a writer starts emitting a new key name — and the two sides stop agreeing. Every document still decodes cleanly; the affected field just quietly stops being populated. Because nothing errors, this can survive a deploy, a rollback, and several weeks of production. ## What a zero value does and does not tell you A zero value after a decode has at least three causes that the decoder does not distinguish: the key was absent, the key was present but unmatched (the case here), or the key was present with an explicit zero — `0`, `""`, `false`. Decoding JSON `null` into most Go types is also a no-op that leaves the field as it was. Any code that reasons about "did the user set this?" from the value alone is guessing. ## How to make it visible The direct tool is a `json.Decoder` with `DisallowUnknownFields()` called before `Decode`, which turns the first unmatched key into an error whose text names it: `json: unknown field "maxConnnections"`. `json.Unmarshal` itself has no such option, so when you only have bytes you wrap them: `json.NewDecoder(bytes.NewReader(b))`. Even when you do not want strict decoding to be fatal in production, you can get the report cheaply: decode leniently into your struct as usual, then decode the same bytes a second time with the strict decoder purely to log what it complains about. The service still starts, but the offending key is now named in a log line instead of being invisible. ## The rules worth memorising - An unmatched JSON key is skipped; the decode still succeeds. - An unmatched key leaves the corresponding field at its Go zero value. - Matching is not exact-only: a key that differs from the field name only in letter case does match, so not every "typo" is dropped — some land on the field anyway. - `json.Unmarshal` cannot report unknown keys; only a `json.Decoder` configured with `DisallowUnknownFields` can. - The struct populated by a failed strict decode may already hold the fields that did match, so treat that error as fatal and throw the value away.