json package - encoding/json - Go Packages

Common problems companies solve with Go
Stories about how and why companies use Go
How Go can help keep you secure by default
Tips for writing clear, performant, and idiomatic Go code
A complete introduction to building software with Go
Reference documentation for Go's standard library
Learn what's new in each Go release
Reference documentation for the pkg.go.dev API
Videos from prior events
Meet other local Go developers
Learn and network with Go developers from around the world
The Go project's official blog.
Get help and stay informed from Go
This package is not in the latest version of its module.
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Modules with tagged versions give importers more predictable builds.
When a project reaches major version v1 it is considered stable.
Package json implements encoding and decoding of JSON as defined in RFC 7159. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions.
See JSON and Go for an introduction to this package.
See the "Security Considerations" section in encoding/json/v2.
For historical reasons, the default behavior of v1 encoding/json unfortunately operates with less secure defaults. New usages of JSON in Go are encouraged to use encoding/json/v2 instead.
This package (i.e., encoding/json) is now formally known as the v1 package since a v2 package now exists at encoding/json/v2. All the behavior of the v1 package is implemented in terms of the v2 package with the appropriate set of options specified that preserve the historical behavior of v1.
The jsonv2.Marshal function is the newer equivalent of v1 Marshal. The jsonv2.Unmarshal function is the newer equivalent of v1 Unmarshal. The v2 functions have the same calling signature as the v1 equivalent except that they take in variadic Options arguments that can be specified to alter the behavior of marshal or unmarshal. Both v1 and v2 generally behave in similar ways, but there are some notable differences.
The following is a list of differences between v1 and v2:
In v1, JSON object members are unmarshaled into a Go struct using a case-insensitive name match with the JSON name of the fields. In contrast, v2 matches fields using an exact, case-sensitive match. The jsonv2.MatchCaseInsensitiveNames and MatchCaseSensitiveDelimiter options control this behavior difference. To explicitly specify a Go struct field to use a particular name matching scheme, either the `case:ignore` or the `case:strict` field option can be specified. Field-specified options take precedence over caller-specified options.
In v1, when marshaling a Go struct, a field marked as `omitempty` is omitted if the field value is an "empty" Go value, which is defined as false, 0, a nil pointer, a nil interface value, and any empty array, slice, map, or string. In contrast, v2 redefines `omitempty` to omit a field if it encodes as an "empty" JSON value, which is defined as a JSON null, or an empty JSON string, object, or array. The OmitEmptyWithLegacySemantics option controls this behavior difference. Note that `omitempty` behaves identically in both v1 and v2 for a Go array, slice, map, or string (assuming no user-defined MarshalJSON method overrides the default representation). Existing usages of `omitempty` on a Go bool, number, pointer, or interface value should migrate to specifying `omitzero` instead (which is identically supported in both v1 and v2).
In v1, a Go struct field marked as `string` can be used to quote a Go string, bool, number, or pointer to such as a JSON string. In contrast, v2 restricts the `string` option to only quote a value that would normally be represented as a JSON number, but also expands support for it to operate with any Go type that would normally be represented as a JSON number. The StringifyWithLegacySemantics option controls this behavior difference.
In v1, a nil Go slice or Go map is marshaled as a JSON null. In contrast, v2 marshals a nil Go slice or Go map as an empty JSON array or JSON object, respectively. The jsonv2.FormatNilSliceAsNull and jsonv2.FormatNilMapAsNull options control this behavior difference.
In v1, a Go array may be unmarshaled from a JSON array of any length. In contrast, in v2 a Go array must be unmarshaled from a JSON array of the same length, otherwise it results in an error. The UnmarshalArrayFromAnyLength option controls this behavior difference.
In v1, a Go byte array is represented as a JSON array of JSON numbers. In contrast, in v2 a Go byte array is represented as a Base64-encoded JSON string. The FormatByteArrayAsArray option controls this behavior difference.
In v1, MarshalJSON methods declared on a pointer receiver are only called if the Go value is addressable. In contrast, in v2 a MarshalJSON method is always callable regardless of addressability. The CallMethodsWithLegacySemantics option controls this behavior difference.
In v1, MarshalJSON and UnmarshalJSON methods are never called for Go map keys. In contrast, in v2 a MarshalJSON or UnmarshalJSON method is eligible for being called for Go map keys. The CallMethodsWithLegacySemantics option controls this behavior difference.
In v1, a Go map is marshaled in a deterministic order. In contrast, in v2 a Go map is marshaled in a non-deterministic order. The jsonv2.Deterministic option controls this behavior difference.
In v1, JSON strings are encoded with HTML-specific or JavaScript-specific characters being escaped. In contrast, in v2 JSON strings use the minimal encoding and only escape if required by the JSON grammar. The jsontext.EscapeForHTML and jsontext.EscapeForJS options control this behavior difference.
In v1, bytes of invalid UTF-8 within a string are silently replaced with the Unicode replacement character. In contrast, in v2 the presence of invalid UTF-8 results in an error