json package - encoding/json/v2 - Go Packages

json

package

standard library

Version:<br>go1.26.5

Opens a new window with list of versions in this module.

Latest

Latest

This package is not in the latest version of its module.

Go to latest

Published: Jul 7, 2026

License: BSD-3-Clause

Opens a new window with license information.

Imports: 25

Opens a new window with list of imports.

Imported by: 438

Opens a new window with list of known importers.

Main

Versions

Licenses

Imports

Imported By

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management<br>solution for Go.

Redistributable license

Redistributable licenses place minimal restrictions on how software can be used,<br>modified, and redistributed.

Tagged version

Modules with tagged versions give importers more predictable builds.

Stable version

When a project reaches major version v1 it is considered stable.

Learn more about best practices

Repository

cs.opensource.google/go/go

Links

Report a Vulnerability

Documentation

Overview ¶

JSON Representation of Go structs

Security Considerations

Package json implements semantic processing of JSON as specified in RFC 8259.<br>JSON is a simple data interchange format that can represent<br>primitive data types such as booleans, strings, and numbers,<br>in addition to structured data types such as objects and arrays.

This package (encoding/json/v2) is experimental,<br>and not subject to the Go 1 compatibility promise.<br>It only exists when building with the GOEXPERIMENT=jsonv2 environment variable set.<br>Most users should use encoding/json.

Marshal and Unmarshal encode and decode Go values<br>to/from JSON text contained within a []byte.<br>MarshalWrite and UnmarshalRead operate on JSON text<br>by writing to or reading from an io.Writer or io.Reader.<br>MarshalEncode and UnmarshalDecode operate on JSON text<br>by encoding to or decoding from a jsontext.Encoder or jsontext.Decoder.<br>Options may be passed to each of the marshal or unmarshal functions<br>to configure the semantic behavior of marshaling and unmarshaling<br>(i.e., alter how JSON data is understood as Go data and vice versa).<br>jsontext.Options may also be passed to the marshal or unmarshal functions<br>to configure the syntactic behavior of encoding or decoding.

The data types of JSON are mapped to/from the data types of Go based on<br>the closest logical equivalent between the two type systems. For example,<br>a JSON boolean corresponds with a Go bool,<br>a JSON string corresponds with a Go string,<br>a JSON number corresponds with a Go int, uint or float,<br>a JSON array corresponds with a Go slice or array, and<br>a JSON object corresponds with a Go struct or map.<br>See the documentation on Marshal and Unmarshal for a comprehensive list<br>of how the JSON and Go type systems correspond.

Arbitrary Go types can customize their JSON representation by implementing<br>Marshaler, MarshalerTo, Unmarshaler, or UnmarshalerFrom.<br>This provides authors of Go types with control over how their types are<br>serialized as JSON. Alternatively, users can implement functions that match<br>MarshalFunc, MarshalToFunc, UnmarshalFunc, or UnmarshalFromFunc<br>to specify the JSON representation for arbitrary types.<br>This provides callers of JSON functionality with control over<br>how any arbitrary type is serialized as JSON.

JSON Representation of Go structs ¶<br>A Go struct is naturally represented as a JSON object,<br>where each Go struct field corresponds with a JSON object member.<br>When marshaling, all Go struct fields are recursively encoded in depth-first<br>order as JSON object members except those that are ignored or omitted.<br>When unmarshaling, JSON object members are recursively decoded<br>into the corresponding Go struct fields.<br>Object members that do not match any struct fields,<br>also known as “unknown members”, are ignored by default or rejected<br>if RejectUnknownMembers is specified.

The representation of each struct field can be customized in the<br>"json" struct field tag, where the tag is a comma separated list of options.<br>As a special case, if the entire tag is `json:"-"`,<br>then the field is ignored with regard to its JSON representation.<br>Some options also have equivalent behavior controlled by a caller-specified Options.<br>Field-specified options take precedence over caller-specified options.

The first option is the JSON object name override for the Go struct field.<br>If the name is not specified, then the Go struct field name<br>is used as the JSON object name. JSON names containing commas or quotes,<br>or names identical to "" or "-", can be specified using<br>a single-quoted string literal, where the syntax is identical to<br>the Go grammar for a double-quoted string literal,<br>but instead uses single quotes as the delimiters.<br>By default, unmarshaling uses case-sensitive matching to identify<br>the Go struct field associated with a JSON object name.

After the name, the following tag options are supported:

omitzero: When marshaling, the "omitzero" option specifies that<br>the struct field...