Struct tags
The default is go.yaml.in/yaml/v3, exactly
A field with no yaml tag is named after its Go field, lowercased. A json tag
is not read.
A json tag alone does nothing
The document says foo, the field wants a, nothing matches, and the decode
succeeds. There is no error and no warning. The same struct marshals to
a: 7, not foo: 7.
That is v3’s model, and a 35-row parity table in the test suite holds it against
v3 itself. If you want encoding/json’s model, ask for it.
Three naming layers, behind two booleans
| option | what it adds |
|---|---|
| (default) | the yaml tag, else the lowercased Go name — v3’s model |
UseJSONTags(true) | the json tag is read, the way encoding/json reads it |
UseInferredNames(true) | an untagged field takes its Go name verbatim, the way encoding/json does |
When a field carries both tags, yaml wins:
The encoder has the mirror pair, WriteJSONTags and WriteInferredNames.
Note
The two directions are separate options. Setting UseJSONTags on a decode
without setting WriteJSONTags on the matching encode gives you an asymmetric
round trip, and nothing reports it.
The tag itself
| option | effect |
|---|---|
- | the field is never read or written |
,inline | an embedded struct’s fields, or a map’s entries, sit in the parent mapping |
,flow | written in flow style: [1, 2, 3] |
,omitempty | not written when empty, or when IsZero() says so |
,omitzero | not written when the Go zero value |
,anchor | written with an anchor — see Anchors and aliases |
,alias | written as an alias to a matching anchor |
The tag name is yaml, spelled by codec.StructTagName.
Related options
AllowFieldPrefixes accepts a key that begins with one of the prefixes you give
it. There is no counterpart on the encoder, so a document read that way does not
round-trip.