Exported names are mandatory, and the failure is silent

Go's encoding/json package works by reflection, and reflection can only reach exported identifiers — those beginning with a capital letter. A lowercase struct field is simply invisible to the decoder: it is left at its zero value, and no error is returned. You get a struct that looks fine and is quietly empty, which is considerably worse than a crash because nothing points at the cause.

This is why the generator capitalises every field name. userName becomes UserName, user_name becomes UserName, and email_address becomes EmailAddress. If you later "tidy" those back to lowercase to match the JSON, the struct stops unmarshalling and gives you no clue why.

The struct tag is the bridge

Because the Go field is capitalised while the JSON key usually is not, something has to connect the two. That is the backtick-quoted tag:

type Root struct {
	ID     int    `json:"id"`
	Title  string `json:"title"`
	Author Author `json:"author"`
}

Without a tag, Go falls back to matching the field name against the key case-insensitively. That happens to work for simple keys — id finds ID, title finds Title — which is exactly why the tags look optional right up until they are not. A key of user_id will not match a field named UserID, because case-insensitive comparison still leaves the underscore in place and the two strings differ. The same applies to any key containing a hyphen. The tags are load-bearing.

Missing keys leave fields at their zero value

When a key is absent from the JSON, Go assigns the field its zero value and reports nothing: 0 for numbers, "" for strings, false for booleans, nil for slices and maps.

The consequence is that absent and present-but-zero are indistinguishable. A missing count key and an explicit "count": 0 both arrive as Count: 0. Where that distinction carries meaning — a discount that was not supplied versus a discount of zero, a flag that was never set versus one set to false — the fix is a pointer:

Count *int `json:"count"`

Now the field is nil when the key was absent. The cost is a nil check before every use, so apply it to the fields where the difference genuinely matters rather than across the whole struct. The generator does not emit pointer types; this is a change you make by hand.

One JSON number type becomes either int or float64

JSON has a single number type, so the generator has to choose from the sample: a whole number such as 42 produces int, and a decimal such as 3.14 produces float64.

The trap is a value like 2.0 or 100.0. It is mathematically an integer but syntactically a float, so the generator emits float64 — and the reverse also happens, where an API that returns 5 in your sample but 5.5 in production gives you an int field that fails to decode the real response. Neither case is detectable from one sample. Check the API documentation for the intended type and correct it by hand.

What omitempty actually does

This one is widely misunderstood, so it is worth stating precisely. The tag itself affects both directions — it is how keys map on the way in and on the way out. The omitempty option, however, affects encoding only: it tells the encoder to leave zero-valued fields out of the JSON it produces.

It does not make a field optional when decoding. A missing key still leaves the field at its zero value whether omitempty is present or not, because decoding never consults it. The generator emits plain tags without it. Add it yourself only when you control the encoding side and want to slim the output — and note the side effect, that a genuine zero will then be omitted from your JSON too.

The same JSON shape is worth generating types for in whichever language the other end of the wire uses — the JSON to TypeScript converter does the front-end half of exactly this job.