json

README

JSON Serialization (v2)

This module hosts an experimental implementation of v2 encoding/json. The API is unstable and breaking changes will regularly be made. Do not depend on this in publicly available modules.

Any commits that make breaking API or behavior changes will be marked with the string "WARNING: " near the top of the commit message. It is your responsibility to inspect the list of commit changes when upgrading the module. Not all breaking changes will lead to build failures.

A Discussion about including this package in Go as encoding/json/v2 has been started on the Go Github project on 2023-10-05. Please provide your feedback there.

Goals and objectives

• Mostly backwards compatible: If possible, v2 should aim to be mostly compatible with v1 in terms of both API and default behavior to ease migration. For example, the Marshal and Unmarshal functions are the most widely used declarations in the v1 package. It seems sensible for equivalent functionality in v2 to be named the same and have a mostly compatible signature. Behaviorally, we should aim for 95% to 99% backwards compatibility. We do not aim for 100% compatibility since we want the freedom to break certain behaviors that are now considered to have been a mistake. We may provide options that can bring the v2 implementation to 100% compatibility, but it will not be the default.

• More flexible: There is a long list of feature requests. We should aim to provide the most flexible features that addresses most usages. We do not want to over fit the v2 API to handle every possible use case. Ideally, the features provided should be orthogonal in nature such that any combination of features results in as few surprising edge cases as possible.

• More performant: JSON serialization is widely used and any bit of extra performance gains will be greatly appreciated. Some rarely used behaviors of v1 may be dropped in favor of better performance. For example, despite Encoder and Decoder operating on an io.Writer and io.Reader, they do not operate in a truly streaming manner, leading to a loss in performance. The v2 implementation should aim to be truly streaming by default (see #33714).

• Easy to use (hard to misuse): The v2 API should aim to make the common case easy and the less common case at least possible. The API should avoid behavior that goes contrary to user expectation, which may result in subtle bugs (see #36225).

• v1 and v2 maintainability: Since the v1 implementation must stay forever, it would be beneficial if v1 could be implemented under the hood with v2, allowing for less maintenance burden in the future. This probably implies that behavioral changes in v2 relative to v1 need to be exposed as options.

• Avoid unsafe: Standard library packages generally avoid the use of package unsafe even if it could provide a performance boost. We aim to preserve this property.

Expectations

While this module aims to possibly be the v2 implementation of encoding/json, there is no guarantee that this outcome will occur. As with any major change to the Go standard library, this will eventually go through the Go proposal process. At the present moment, this is still in the design and experimentation phase and is not ready for a formal proposal.

There are several possible outcomes from this experiment:

1. We determine that a v2 encoding/json would not provide sufficient benefit over the existing v1 encoding/json package. Thus, we abandon this effort.
2. We propose a v2 encoding/json design, but it is rejected in favor of some other design that is considered superior.
3. We propose a v2 encoding/json design, but rather than adding an entirely new v2 encoding/json package, we decide to merge its functionality into the existing v1 encoding/json package.
4. We propose a v2 encoding/json design and it is accepted, resulting in its addition to the standard library.
5. Some other unforeseen outcome (among the infinite number of possibilities).

Development

This module is primarily developed by @dsnet, @mvdan, and @johanbrandhorst with feedback provided by @rogpeppe, @ChrisHines, and @rsc.

Discussion about semantics occur semi-regularly, where a record of past meetings can be found here.

Design overview

This package aims to provide a clean separation between syntax and semantics. Syntax deals with the structural representation of JSON (as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785). Semantics deals with the meaning of syntactic data as usable application data.

The Encoder and Decoder types are streaming tokenizers concerned with the packing or parsing of JSON data. They operate on Token and Value types which represent the common data structures that are representable in JSON. Encoder and Decoder do not aim to provide any interpretation of the data.

Functions like Marshal, MarshalWrite, MarshalEncode, Unmarshal, UnmarshalRead, and UnmarshalDecode provide semantic meaning by correlating any arbitrary Go type with some JSON representation of that type (as stored in data types like []byte, io.Writer, io.Reader, Encoder, or Decoder).

This diagram provides a high-level overview of the v2 json and jsontext packages. Purple blocks represent types, while blue blocks represent functions or methods. The arrows and their direction represent the approximate flow of data. The bottom half of the diagram contains functionality that is only concerned with syntax (implemented by the jsontext package), while the upper half contains functionality that assigns semantic meaning to syntactic data handled by the bottom half (as implemented by the v2 json package).

In contrast to v1 encoding/json, options are represented as separate types rather than being setter methods on the Encoder or Decoder types. Some options affects JSON serialization at the syntactic layer, while others affect it at the semantic layer. Some options only affect JSON when decoding, while others affect JSON while encoding.

Behavior changes

The v2 json package changes the default behavior of Marshal and Unmarshal relative to the v1 json package to be more sensible. Some of these behavior changes have options and workarounds to opt into behavior similar to what v1 provided.

This table shows an overview of the changes:

v1	v2	Details
JSON object members are unmarshaled into a Go struct using a case-insensitive name match.	JSON object members are unmarshaled into a Go struct using a case-sensitive name match.	CaseSensitivity
When marshaling a Go struct, a struct 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.	When marshaling a Go struct, a struct field marked as omitempty is omitted if the field value would encode as an empty JSON value, which is defined as a JSON null, or an empty JSON string, object, or array.	OmitEmptyOption
The string option does affect Go bools.	The string option does not affect Go bools.	StringOption
The string option does not recursively affect sub-values of the Go field value.	The string option does recursively affect sub-values of the Go field value.	StringOption
The string option sometimes accepts a JSON null escaped within a JSON string.	The string option never accepts a JSON null escaped within a JSON string.	StringOption
A nil Go slice is marshaled as a JSON null.	A nil Go slice is marshaled as an empty JSON array.	NilSlicesAndMaps
A nil Go map is marshaled as a JSON null.	A nil Go map is marshaled as an empty JSON object.	NilSlicesAndMaps
A Go array may be unmarshaled from a JSON array of any length.	A Go array must be unmarshaled from a JSON array of the same length.	Arrays
A Go byte array is represented as a JSON array of JSON numbers.	A Go byte array is represented as a Base64-encoded JSON string.	ByteArrays
MarshalJSON and UnmarshalJSON methods declared on a pointer receiver are inconsistently called.	MarshalJSON and UnmarshalJSON methods declared on a pointer receiver are consistently called.	PointerReceiver
A Go map is marshaled in a deterministic order.	A Go map is marshaled in a non-deterministic order.	MapDeterminism
JSON strings are encoded with HTML-specific characters being escaped.	JSON strings are encoded without any characters being escaped (unless necessary).	EscapeHTML
When marshaling, invalid UTF-8 within a Go string are silently replaced.	When marshaling, invalid UTF-8 within a Go string results in an error.	InvalidUTF8
When unmarshaling, invalid UTF-8 within a JSON string are silently replaced.	When unmarshaling, invalid UTF-8 within a JSON string results in an error.	InvalidUTF8
When marshaling, an error does not occur if the output JSON value contains objects with duplicate names.	When marshaling, an error does occur if the output JSON value contains objects with duplicate names.	DuplicateNames
When unmarshaling, an error does not occur if the input JSON value contains objects with duplicate names.	When unmarshaling, an error does occur if the input JSON value contains objects with duplicate names.	DuplicateNames
Unmarshaling a JSON null into a non-empty Go value inconsistently clears the value or does nothing.	Unmarshaling a JSON null into a non-empty Go value always clears the value.	MergeNull
Unmarshaling a JSON value into a non-empty Go value follows inconsistent and bizarre behavior.	Unmarshaling a JSON value into a non-empty Go value always merges if the input is an object, and otherwise replaces.	MergeComposite
A time.Duration is represented as a JSON number containing the decimal number of nanoseconds.	A time.Duration is represented as a JSON string containing the formatted duration (e.g., "1h2m3.456s").	TimeDurations
Unmarshaling a JSON number into a Go float beyond its representation results in an error.	Unmarshaling a JSON number into a Go float beyond its representation uses the closest representable value (e.g., ±math.MaxFloat).	MaxFloats
A Go struct with only unexported fields can be serialized.	A Go struct with only unexported fields cannot be serialized.	EmptyStructs
A Go struct that embeds an unexported struct type can sometimes be serialized.	A Go struct that embeds an unexported struct type cannot be serialized.	EmbedUnexported

See diff_test.go for details about every change.

Performance

One of the goals of the v2 module is to be more performant than v1, but not at the expense of correctness. In general, v2 is at performance parity with v1 for marshaling, but dramatically faster for unmarshaling.

See https://github.com/go-json-experiment/jsonbench for benchmarks comparing v2 with v1 and a number of other popular JSON implementations.

Documentation

Overview

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

Marshal and Unmarshal encode and decode Go values to/from JSON text contained within a []byte. MarshalWrite and UnmarshalRead operate on JSON text by writing to or reading from an io.Writer or io.Reader. MarshalEncode and UnmarshalDecode operate on JSON text by encoding to or decoding from a jsontext.Encoder or jsontext.Decoder. Options may be passed to each of the marshal or unmarshal functions to configure the semantic behavior of marshaling and unmarshaling (i.e., alter how JSON data is understood as Go data and vice versa). jsontext.Options may also be passed to the marshal or unmarshal functions 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 the closest logical equivalent between the two type systems. For example, a JSON boolean corresponds with a Go bool, a JSON string corresponds with a Go string, a JSON number corresponds with a Go int, uint or float, a JSON array corresponds with a Go slice or array, and a JSON object corresponds with a Go struct or map. See the documentation on Marshal and Unmarshal for a comprehensive list of how the JSON and Go type systems correspond.

Arbitrary Go types can customize their JSON representation by implementing MarshalerV1, MarshalerV2, UnmarshalerV1, or UnmarshalerV2. This provides authors of Go types with control over how their types are serialized as JSON. Alternatively, users can implement functions that match MarshalFuncV1, MarshalFuncV2, UnmarshalFuncV1, or UnmarshalFuncV2 to specify the JSON representation for arbitrary types. This provides callers of JSON functionality with control over how any arbitrary type is serialized as JSON.

JSON Representation of Go structs

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

The representation of each struct field can be customized in the "json" struct field tag, where the tag is a comma separated list of options. As a special case, if the entire tag is `json:"-"`, then the field is ignored with regard to its JSON representation.

The first option is the JSON object name override for the Go struct field. If the name is not specified, then the Go struct field name is used as the JSON object name. JSON names containing commas or quotes, or names identical to "" or "-", can be specified using a single-quoted string literal, where the syntax is identical to the Go grammar for a double-quoted string literal, but instead uses single quotes as the delimiters. By default, unmarshaling uses case-sensitive matching to identify 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 the struct field should be omitted if the field value is zero as determined by the "IsZero() bool" method if present, otherwise based on whether the field is the zero Go value. This option has no effect when unmarshaling.

• omitempty: When marshaling, the "omitempty" option specifies that the struct field should be omitted if the field value would have been encoded as a JSON null, empty string, empty object, or empty array. This option has no effect when unmarshaling.

• string: The "string" option specifies that StringifyNumbers be set when marshaling or unmarshaling a struct field value. This causes numeric types to be encoded as a JSON number within a JSON string, and to be decoded from either a JSON number or a JSON string containing a JSON number. This extra level of encoding is often necessary since many JSON parsers cannot precisely represent 64-bit integers.

• nocase: When unmarshaling, the "nocase" option specifies that if the JSON object name does not exactly match the JSON name for any of the struct fields, then it attempts to match the struct field using a case-insensitive match that also ignores dashes and underscores. If multiple fields match, the first declared field in breadth-first order takes precedence. This takes precedence even if MatchCaseInsensitiveNames is set to false. This cannot be specified together with the "strictcase" option.

• strictcase: When unmarshaling, the "strictcase" option specifies that the JSON object name must exactly match the JSON name for the struct field. This takes precedence even if MatchCaseInsensitiveNames is set to true. This cannot be specified together with the "nocase" option.

• inline: The "inline" option specifies that the JSON representable content of this field type is to be promoted as if they were specified in the parent struct. It is the JSON equivalent of Go struct embedding. A Go embedded field is implicitly inlined unless an explicit JSON name is specified. The inlined field must be a Go struct (that does not implement any JSON methods), jsontext.Value, map[string]T, or an unnamed pointer to such types. When marshaling, inlined fields from a pointer type are omitted if it is nil. Inlined fields of type jsontext.Value and map[string]T are called “inlined fallbacks” as they can represent all possible JSON object members not directly handled by the parent struct. Only one inlined fallback field may be specified in a struct, while many non-fallback fields may be specified. This option must not be specified with any other option (including the JSON name).

• unknown: The "unknown" option is a specialized variant of the inlined fallback to indicate that this Go struct field contains any number of unknown JSON object members. The field type must be a jsontext.Value, map[string]T, or an unnamed pointer to such types. If DiscardUnknownMembers is specified when marshaling, the contents of this field are ignored. If RejectUnknownMembers is specified when unmarshaling, any unknown object members are rejected regardless of whether an inlined fallback with the "unknown" option exists. This option must not be specified with any other option (including the JSON name).

• format: The "format" option specifies a format flag used to specialize the formatting of the field value. The option is a key-value pair specified as "format:value" where the value must be either a literal consisting of letters and numbers (e.g., "format:RFC3339") or a single-quoted string literal (e.g., "format:'2006-01-02'"). The interpretation of the format flag is determined by the struct field type.

The "omitzero" and "omitempty" options are mostly semantically identical. The former is defined in terms of the Go type system, while the latter in terms of the JSON type system. Consequently they behave differently in some circumstances. For example, only a nil slice or map is omitted under "omitzero", while an empty slice or map is omitted under "omitempty" regardless of nilness. The "omitzero" option is useful for types with a well-defined zero value (e.g., net/netip.Addr) or have an IsZero method (e.g., time.Time.IsZero).

Every Go struct corresponds to a list of JSON representable fields which is constructed by performing a breadth-first search over all struct fields (excluding unexported or ignored fields), where the search recursively descends into inlined structs. The set of non-inlined fields in a struct must have unique JSON names. If multiple fields all have the same JSON name, then the one at shallowest depth takes precedence and the other fields at deeper depths are excluded from the list of JSON representable fields. If multiple fields at the shallowest depth have the same JSON name, but exactly one is explicitly tagged with a JSON name, then that field takes precedence and all others are excluded from the list. This is analogous to Go visibility rules for struct field selection with embedded struct types.

Marshaling or unmarshaling a non-empty struct without any JSON representable fields results in a SemanticError. Unexported fields must not have any `json` tags except for `json:"-"`.

Example (CaseSensitivity)

Unmarshal matches JSON object names with Go struct fields using a case-sensitive match, but can be configured to use a case-insensitive match with the "nocase" option. This permits unmarshaling from inputs that use naming conventions such as camelCase, snake_case, or kebab-case.

package main

import (
	"fmt"
	"log"

	"github.com/go-json-experiment/json"
)

func main() {
	// JSON input using various naming conventions.
	const input = `[
		{"firstname": true},
		{"firstName": true},
		{"FirstName": true},
		{"FIRSTNAME": true},
		{"first_name": true},
		{"FIRST_NAME": true},
		{"first-name": true},
		{"FIRST-NAME": true},
		{"unknown": true}
	]`

	// Without "nocase", Unmarshal looks for an exact match.
	var withcase []struct {
		X bool `json:"firstName"`
	}
	if err := json.Unmarshal([]byte(input), &withcase); err != nil {
		log.Fatal(err)
	}
	fmt.Println(withcase) // exactly 1 match found

	// With "nocase", Unmarshal looks first for an exact match,
	// then for a case-insensitive match if none found.
	var nocase []struct {
		X bool `json:"firstName,nocase"`
	}
	if err := json.Unmarshal([]byte(input), &nocase); err != nil {
		log.Fatal(err)
	}
	fmt.Println(nocase) // 8 matches found

}

Output:

[{false} {true} {false} {false} {false} {false} {false} {false} {false}]
[{true} {true} {true} {true} {true} {true} {true} {true} {false}]

Example (FieldNames)

By default, JSON object names for Go struct fields are derived from the Go field name, but may be specified in the `json` tag. Due to JSON's heritage in JavaScript, the most common naming convention used for JSON object names is camelCase.

package main

import (
	"fmt"
	"log"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	var value struct {
		// This field is explicitly ignored with the special "-" name.
		Ignored any `json:"-"`
		// No JSON name is not provided, so the Go field name is used.
		GoName any
		// A JSON name is provided without any special characters.
		JSONName any `json:"jsonName"`
		// No JSON name is not provided, so the Go field name is used.
		Option any `json:",nocase"`
		// An empty JSON name specified using an single-quoted string literal.
		Empty any `json:"''"`
		// A dash JSON name specified using an single-quoted string literal.
		Dash any `json:"'-'"`
		// A comma JSON name specified using an single-quoted string literal.
		Comma any `json:"','"`
		// JSON name with quotes specified using a single-quoted string literal.
		Quote any `json:"'\"\\''"`
		// An unexported field is always ignored.
		unexported any
	}

	b, err := json.Marshal(value)
	if err != nil {
		log.Fatal(err)
	}
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"GoName": null,
	"jsonName": null,
	"Option": null,
	"": null,
	"-": null,
	",": null,
	"\"'": null
}

Example (FormatFlags)

The "format" tag option can be used to alter the formatting of certain types.

package main

import (
	"fmt"
	"log"
	"math"
	"time"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	value := struct {
		BytesBase64    []byte         `json:",format:base64"`
		BytesHex       [8]byte        `json:",format:hex"`
		BytesArray     []byte         `json:",format:array"`
		FloatNonFinite float64        `json:",format:nonfinite"`
		MapEmitNull    map[string]any `json:",format:emitnull"`
		SliceEmitNull  []any          `json:",format:emitnull"`
		TimeDateOnly   time.Time      `json:",format:'2006-01-02'"`
		TimeUnixSec    time.Time      `json:",format:unix"`
		DurationSecs   time.Duration  `json:",format:sec"`
		DurationNanos  time.Duration  `json:",format:nano"`
		DurationBase60 time.Duration  `json:",format:base60"`
	}{
		BytesBase64:    []byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		BytesHex:       [8]byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		BytesArray:     []byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		FloatNonFinite: math.NaN(),
		MapEmitNull:    nil,
		SliceEmitNull:  nil,
		TimeDateOnly:   time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC),
		TimeUnixSec:    time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC),
		DurationSecs:   12*time.Hour + 34*time.Minute + 56*time.Second + 7*time.Millisecond + 8*time.Microsecond + 9*time.Nanosecond,
		DurationNanos:  12*time.Hour + 34*time.Minute + 56*time.Second + 7*time.Millisecond + 8*time.Microsecond + 9*time.Nanosecond,
		DurationBase60: 12*time.Hour + 34*time.Minute + 56*time.Second + 7*time.Millisecond + 8*time.Microsecond + 9*time.Nanosecond,
	}

	b, err := json.Marshal(&value)
	if err != nil {
		log.Fatal(err)
	}
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"BytesBase64": "ASNFZ4mrze8=",
	"BytesHex": "0123456789abcdef",
	"BytesArray": [
		1,
		35,
		69,
		103,
		137,
		171,
		205,
		239
	],
	"FloatNonFinite": "NaN",
	"MapEmitNull": null,
	"SliceEmitNull": null,
	"TimeDateOnly": "2000-01-01",
	"TimeUnixSec": 946684800,
	"DurationSecs": 45296.007008009,
	"DurationNanos": 45296007008009,
	"DurationBase60": "12:34:56.007008009"
}

Example (InlinedFields)

JSON objects can be inlined within a parent object similar to how Go structs can be embedded within a parent struct. The inlining rules are similar to those of Go embedding, but operates upon the JSON namespace.

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	// Base is embedded within Container.
	type Base struct {
		// ID is promoted into the JSON object for Container.
		ID string
		// Type is ignored due to presence of Container.Type.
		Type string
		// Time cancels out with Container.Inlined.Time.
		Time time.Time
	}
	// Other is embedded within Container.
	type Other struct{ Cost float64 }
	// Container embeds Base and Other.
	type Container struct {
		// Base is an embedded struct and is implicitly JSON inlined.
		Base
		// Type takes precedence over Base.Type.
		Type int
		// Inlined is a named Go field, but is explicitly JSON inlined.
		Inlined struct {
			// User is promoted into the JSON object for Container.
			User string
			// Time cancels out with Base.Time.
			Time string
		} `json:",inline"`
		// ID does not conflict with Base.ID since the JSON name is different.
		ID string `json:"uuid"`
		// Other is not JSON inlined since it has an explicit JSON name.
		Other `json:"other"`
	}

	// Format an empty Container to show what fields are JSON serializable.
	var input Container
	b, err := json.Marshal(&input)
	if err != nil {
		log.Fatal(err)
	}
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"ID": "",
	"Type": 0,
	"User": "",
	"uuid": "",
	"other": {
		"Cost": 0
	}
}

Example (OmitFields)

Go struct fields can be omitted from the output depending on either the input Go value or the output JSON encoding of the value. The "omitzero" option omits a field if it is the zero Go value or implements a "IsZero() bool" method that reports true. The "omitempty" option omits a field if it encodes as an empty JSON value, which we define as a JSON null or empty JSON string, object, or array. In many cases, the behavior of "omitzero" and "omitempty" are equivalent. If both provide the desired effect, then using "omitzero" is preferred.

package main

import (
	"fmt"
	"log"
	"net/netip"
	"time"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	type MyStruct struct {
		Foo string `json:",omitzero"`
		Bar []int  `json:",omitempty"`
		// Both "omitzero" and "omitempty" can be specified together,
		// in which case the field is omitted if either would take effect.
		// This omits the Baz field either if it is a nil pointer or
		// if it would have encoded as an empty JSON object.
		Baz *MyStruct `json:",omitzero,omitempty"`
	}

	// Demonstrate behavior of "omitzero".
	b, err := json.Marshal(struct {
		Bool         bool        `json:",omitzero"`
		Int          int         `json:",omitzero"`
		String       string      `json:",omitzero"`
		Time         time.Time   `json:",omitzero"`
		Addr         netip.Addr  `json:",omitzero"`
		Struct       MyStruct    `json:",omitzero"`
		SliceNil     []int       `json:",omitzero"`
		Slice        []int       `json:",omitzero"`
		MapNil       map[int]int `json:",omitzero"`
		Map          map[int]int `json:",omitzero"`
		PointerNil   *string     `json:",omitzero"`
		Pointer      *string     `json:",omitzero"`
		InterfaceNil any         `json:",omitzero"`
		Interface    any         `json:",omitzero"`
	}{
		// Bool is omitted since false is the zero value for a Go bool.
		Bool: false,
		// Int is omitted since 0 is the zero value for a Go int.
		Int: 0,
		// String is omitted since "" is the zero value for a Go string.
		String: "",
		// Time is omitted since time.Time.IsZero reports true.
		Time: time.Date(1, 1, 1, 0, 0, 0, 0, time.UTC),
		// Addr is omitted since netip.Addr{} is the zero value for a Go struct.
		Addr: netip.Addr{},
		// Struct is NOT omitted since it is not the zero value for a Go struct.
		Struct: MyStruct{Bar: []int{}, Baz: new(MyStruct)},
		// SliceNil is omitted since nil is the zero value for a Go slice.
		SliceNil: nil,
		// Slice is NOT omitted since []int{} is not the zero value for a Go slice.
		Slice: []int{},
		// MapNil is omitted since nil is the zero value for a Go map.
		MapNil: nil,
		// Map is NOT omitted since map[int]int{} is not the zero value for a Go map.
		Map: map[int]int{},
		// PointerNil is omitted since nil is the zero value for a Go pointer.
		PointerNil: nil,
		// Pointer is NOT omitted since new(string) is not the zero value for a Go pointer.
		Pointer: new(string),
		// InterfaceNil is omitted since nil is the zero value for a Go interface.
		InterfaceNil: nil,
		// Interface is NOT omitted since (*string)(nil) is not the zero value for a Go interface.
		Interface: (*string)(nil),
	})
	if err != nil {
		log.Fatal(err)
	}
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println("OmitZero:", string(b))    // outputs "Struct", "Slice", "Map", "Pointer", and "Interface"

	// Demonstrate behavior of "omitempty".
	b, err = json.Marshal(struct {
		Bool         bool        `json:",omitempty"`
		Int          int         `json:",omitempty"`
		String       string      `json:",omitempty"`
		Time         time.Time   `json:",omitempty"`
		Addr         netip.Addr  `json:",omitempty"`
		Struct       MyStruct    `json:",omitempty"`
		Slice        []int       `json:",omitempty"`
		Map          map[int]int `json:",omitempty"`
		PointerNil   *string     `json:",omitempty"`
		Pointer      *string     `json:",omitempty"`
		InterfaceNil any         `json:",omitempty"`
		Interface    any         `json:",omitempty"`
	}{
		// Bool is NOT omitted since false is not an empty JSON value.
		Bool: false,
		// Int is NOT omitted since 0 is not a empty JSON value.
		Int: 0,
		// String is omitted since "" is an empty JSON string.
		String: "",
		// Time is NOT omitted since this encodes as a non-empty JSON string.
		Time: time.Date(1, 1, 1, 0, 0, 0, 0, time.UTC),
		// Addr is omitted since this encodes as an empty JSON string.
		Addr: netip.Addr{},
		// Struct is omitted since {} is an empty JSON object.
		Struct: MyStruct{Bar: []int{}, Baz: new(MyStruct)},
		// Slice is omitted since [] is an empty JSON array.
		Slice: []int{},
		// Map is omitted since {} is an empty JSON object.
		Map: map[int]int{},
		// PointerNil is omitted since null is an empty JSON value.
		PointerNil: nil,
		// Pointer is omitted since "" is an empty JSON string.
		Pointer: new(string),
		// InterfaceNil is omitted since null is an empty JSON value.
		InterfaceNil: nil,
		// Interface is omitted since null is an empty JSON value.
		Interface: (*string)(nil),
	})
	if err != nil {
		log.Fatal(err)
	}
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println("OmitEmpty:", string(b))   // outputs "Bool", "Int", and "Time"

}

Output:

OmitZero: {
	"Struct": {},
	"Slice": [],
	"Map": {},
	"Pointer": "",
	"Interface": null
}
OmitEmpty: {
	"Bool": false,
	"Int": 0,
	"Time": "0001-01-01T00:00:00Z"
}

Example (OrderedObject)

The exact order of JSON object can be preserved through the use of a specialized type that implements MarshalerV2 and UnmarshalerV2.

package main

import (
	"fmt"
	"log"
	"reflect"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

// OrderedObject is an ordered sequence of name/value members in a JSON object.
//
// RFC 8259 defines an object as an "unordered collection".
// JSON implementations need not make "ordering of object members visible"
// to applications nor will they agree on the semantic meaning of an object if
// "the names within an object are not unique". For maximum compatibility,
// applications should avoid relying on ordering or duplicity of object names.
type OrderedObject[V any] []ObjectMember[V]

// ObjectMember is a JSON object member.
type ObjectMember[V any] struct {
	Name  string
	Value V
}

// MarshalJSONV2 encodes obj as a JSON object into enc.
func (obj *OrderedObject[V]) MarshalJSONV2(enc *jsontext.Encoder, opts json.Options) error {
	if err := enc.WriteToken(jsontext.ObjectStart); err != nil {
		return err
	}
	for i := range *obj {
		member := &(*obj)[i]
		if err := json.MarshalEncode(enc, &member.Name, opts); err != nil {
			return err
		}
		if err := json.MarshalEncode(enc, &member.Value, opts); err != nil {
			return err
		}
	}
	if err := enc.WriteToken(jsontext.ObjectEnd); err != nil {
		return err
	}
	return nil
}

// UnmarshalJSONV2 decodes a JSON object from dec into obj.
func (obj *OrderedObject[V]) UnmarshalJSONV2(dec *jsontext.Decoder, opts json.Options) error {
	if k := dec.PeekKind(); k != '{' {
		return fmt.Errorf("expected object start, but encountered %v", k)
	}
	if _, err := dec.ReadToken(); err != nil {
		return err
	}
	for dec.PeekKind() != '}' {
		*obj = append(*obj, ObjectMember[V]{})
		member := &(*obj)[len(*obj)-1]
		if err := json.UnmarshalDecode(dec, &member.Name, opts); err != nil {
			return err
		}
		if err := json.UnmarshalDecode(dec, &member.Value, opts); err != nil {
			return err
		}
	}
	if _, err := dec.ReadToken(); err != nil {
		return err
	}
	return nil
}

// The exact order of JSON object can be preserved through the use of a
// specialized type that implements [MarshalerV2] and [UnmarshalerV2].
func main() {
	// Round-trip marshal and unmarshal an ordered object.
	// We expect the order and duplicity of JSON object members to be preserved.
	// Specify jsontext.AllowDuplicateNames since this object contains "fizz" twice.
	want := OrderedObject[string]{
		{"fizz", "buzz"},
		{"hello", "world"},
		{"fizz", "wuzz"},
	}
	b, err := json.Marshal(&want, jsontext.AllowDuplicateNames(true))
	if err != nil {
		log.Fatal(err)
	}
	var got OrderedObject[string]
	err = json.Unmarshal(b, &got, jsontext.AllowDuplicateNames(true))
	if err != nil {
		log.Fatal(err)
	}

	// Sanity check.
	if !reflect.DeepEqual(got, want) {
		log.Fatalf("roundtrip mismatch: got %v, want %v", got, want)
	}

	// Print the serialized JSON object.
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"fizz": "buzz",
	"hello": "world",
	"fizz": "wuzz"
}

Example (ProtoJSON)

Some Go types have a custom JSON representation where the implementation is delegated to some external package. Consequently, the "json" package will not know how to use that external implementation. For example, the google.golang.org/protobuf/encoding/protojson package implements JSON for all google.golang.org/protobuf/proto.Message types. WithMarshalers and WithUnmarshalers can be used to configure "json" and "protojson" to cooperate together.

package main

import (
	"log"

	"github.com/go-json-experiment/json"
)

func main() {
	// Let protoMessage be "google.golang.org/protobuf/proto".Message.
	type protoMessage interface{ ProtoReflect() }
	// Let foopbMyMessage be a concrete implementation of proto.Message.
	type foopbMyMessage struct{ protoMessage }
	// Let protojson be an import of "google.golang.org/protobuf/encoding/protojson".
	var protojson struct {
		Marshal   func(protoMessage) ([]byte, error)
		Unmarshal func([]byte, protoMessage) error
	}

	// This value mixes both non-proto.Message types and proto.Message types.
	// It should use the "json" package to handle non-proto.Message types and
	// should use the "protojson" package to handle proto.Message types.
	var value struct {
		// GoStruct does not implement proto.Message and
		// should use the default behavior of the "json" package.
		GoStruct struct {
			Name string
			Age  int
		}

		// ProtoMessage implements proto.Message and
		// should be handled using protojson.Marshal.
		ProtoMessage *foopbMyMessage
	}

	// Marshal using protojson.Marshal for proto.Message types.
	b, err := json.Marshal(&value,
		// Use protojson.Marshal as a type-specific marshaler.
		json.WithMarshalers(json.MarshalFuncV1(protojson.Marshal)))
	if err != nil {
		log.Fatal(err)
	}

	// Unmarshal using protojson.Unmarshal for proto.Message types.
	err = json.Unmarshal(b, &value,
		// Use protojson.Unmarshal as a type-specific unmarshaler.
		json.WithUnmarshalers(json.UnmarshalFuncV1(protojson.Unmarshal)))
	if err != nil {
		log.Fatal(err)
	}
}

Example (ServeHTTP)

When implementing HTTP endpoints, it is common to be operating with an io.Reader and an io.Writer. The MarshalWrite and UnmarshalRead functions assist in operating on such input/output types. UnmarshalRead reads the entirety of the io.Reader to ensure that io.EOF is encountered without any unexpected bytes after the top-level JSON value.

package main

import (
	"net/http"
	"sync/atomic"

	"github.com/go-json-experiment/json"
)

func main() {
	// Some global state maintained by the server.
	var n int64

	// The "add" endpoint accepts a POST request with a JSON object
	// containing a number to atomically add to the server's global counter.
	// It returns the updated value of the counter.
	http.HandleFunc("/api/add", func(w http.ResponseWriter, r *http.Request) {
		// Unmarshal the request from the client.
		var val struct{ N int64 }
		if err := json.UnmarshalRead(r.Body, &val); err != nil {
			// Inability to unmarshal the input suggests a client-side problem.
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}

		// Marshal a response from the server.
		val.N = atomic.AddInt64(&n, val.N)
		if err := json.MarshalWrite(w, &val); err != nil {
			// Inability to marshal the output suggests a server-side problem.
			// This error is not always observable by the client since
			// json.MarshalWrite may have already written to the output.
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
	})
}

Example (TextMarshal)

If a type implements encoding.TextMarshaler and/or encoding.TextUnmarshaler, then the MarshalText and UnmarshalText methods are used to encode/decode the value to/from a JSON string.

package main

import (
	"fmt"
	"log"
	"net/netip"
	"reflect"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	// Round-trip marshal and unmarshal a hostname map where the netip.Addr type
	// implements both encoding.TextMarshaler and encoding.TextUnmarshaler.
	want := map[netip.Addr]string{
		netip.MustParseAddr("192.168.0.100"): "carbonite",
		netip.MustParseAddr("192.168.0.101"): "obsidian",
		netip.MustParseAddr("192.168.0.102"): "diamond",
	}
	b, err := json.Marshal(&want)
	if err != nil {
		log.Fatal(err)
	}
	var got map[netip.Addr]string
	err = json.Unmarshal(b, &got)
	if err != nil {
		log.Fatal(err)
	}

	// Sanity check.
	if !reflect.DeepEqual(got, want) {
		log.Fatalf("roundtrip mismatch: got %v, want %v", got, want)
	}

	// Print the serialized JSON object. Canonicalize the JSON first since
	// Go map entries are not serialized in a deterministic order.
	(*jsontext.Value)(&b).Canonicalize()
	(*jsontext.Value)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"192.168.0.100": "carbonite",
	"192.168.0.101": "obsidian",
	"192.168.0.102": "diamond"
}

Example (UnknownMembers)

Due to version skew, the set of JSON object members known at compile-time may differ from the set of members encountered at execution-time. As such, it may be useful to have finer grain handling of unknown members. This package supports preserving, rejecting, or discarding such members.

package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	const input = `{
		"Name": "Teal",
		"Value": "#008080",
		"WebSafe": false
	}`
	type Color struct {
		Name  string
		Value string

		// Unknown is a Go struct field that holds unknown JSON object members.
		// It is marked as having this behavior with the "unknown" tag option.
		//
		// The type may be a jsontext.Value or map[string]T.
		Unknown jsontext.Value `json:",unknown"`
	}

	// By default, unknown members are stored in a Go field marked as "unknown"
	// or ignored if no such field exists.
	var color Color
	err := json.Unmarshal([]byte(input), &color)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Unknown members:", string(color.Unknown))

	// Specifying RejectUnknownMembers causes Unmarshal
	// to reject the presence of any unknown members.
	err = json.Unmarshal([]byte(input), new(Color), json.RejectUnknownMembers(true))
	if err != nil {
		fmt.Println("Unmarshal error:", errors.Unwrap(err))
	}

	// By default, Marshal preserves unknown members stored in
	// a Go struct field marked as "unknown".
	b, err := json.Marshal(color)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Output with unknown members:   ", string(b))

	// Specifying DiscardUnknownMembers causes Marshal
	// to discard any unknown members.
	b, err = json.Marshal(color, json.DiscardUnknownMembers(true))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Output without unknown members:", string(b))

}

Output:

Unknown members: {"WebSafe":false}
Unmarshal error: unknown name "WebSafe"
Output with unknown members:    {"Name":"Teal","Value":"#008080","WebSafe":false}
Output without unknown members: {"Name":"Teal","Value":"#008080"}

Index

• Variables
• func GetOption[T any](opts Options, setter func(T) Options) (T, bool)
• func Marshal(in any, opts ...Options) (out []byte, err error)
• func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) (err error)
• func MarshalWrite(out io.Writer, in any, opts ...Options) (err error)
• func Unmarshal(in []byte, out any, opts ...Options) (err error)
• func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) (err error)
• func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error)
• type MarshalerV1
• type MarshalerV2
• type Marshalers
  • func MarshalFuncV1[T any](fn func(T) ([]byte, error)) *Marshalers
  • func MarshalFuncV2[T any](fn func(*jsontext.Encoder, T, Options) error) *Marshalers
  • func NewMarshalers(ms ...*Marshalers) *Marshalers
• type Options
  • func DefaultOptionsV2() Options
  • func Deterministic(v bool) Options
  • func DiscardUnknownMembers(v bool) Options
  • func FormatNilMapAsNull(v bool) Options
  • func FormatNilSliceAsNull(v bool) Options
  • func JoinOptions(srcs ...Options) Options
  • func MatchCaseInsensitiveNames(v bool) Options
  • func RejectUnknownMembers(v bool) Options
  • func StringifyNumbers(v bool) Options
  • func WithMarshalers(v *Marshalers) Options
  • func WithUnmarshalers(v *Unmarshalers) Options
• type SemanticError
  • func (e *SemanticError) Error() string
  • func (e *SemanticError) Unwrap() error
• type UnmarshalerV1
• type UnmarshalerV2
• type Unmarshalers
  • func NewUnmarshalers(us ...*Unmarshalers) *Unmarshalers
  • func UnmarshalFuncV1[T any](fn func([]byte, T) error) *Unmarshalers
  • func UnmarshalFuncV2[T any](fn func(*jsontext.Decoder, T, Options) error) *Unmarshalers

Examples

• Package (CaseSensitivity)
• Package (FieldNames)
• Package (FormatFlags)
• Package (InlinedFields)
• Package (OmitFields)
• Package (OrderedObject)
• Package (ProtoJSON)
• Package (ServeHTTP)
• Package (TextMarshal)
• Package (UnknownMembers)
• WithMarshalers (Errors)
• WithUnmarshalers (RawNumber)
• WithUnmarshalers (RecordOffsets)

Variables

var SkipFunc = errors.New("json: skip function")

SkipFunc may be returned by MarshalFuncV2 and UnmarshalFuncV2 functions.

Any function that returns SkipFunc must not cause observable side effects on the provided jsontext.Encoder or jsontext.Decoder. For example, it is permissible to call jsontext.Decoder.PeekKind, but not permissible to call jsontext.Decoder.ReadToken or jsontext.Encoder.WriteToken since such methods mutate the state.

Functions

func GetOption

func GetOption[T any](opts Options, setter func(T) Options) (T, bool)

GetOption returns the value stored in opts with the provided setter, reporting whether the value is present.

Example usage:

v, ok := json.GetOption(opts, json.Deterministic)

Options are most commonly introspected to alter the JSON representation of [MarshalerV2.MarshalJSONV2] and [MarshalerV2.MarshalJSONV2] methods, and MarshalFuncV2 and UnmarshalFuncV2 functions. In such cases, the presence bit should generally be ignored.

func Marshal

func Marshal(in any, opts ...Options) (out []byte, err error)

Marshal serializes a Go value as a []byte according to the provided marshal and encode options (while ignoring unmarshal or decode options). It does not terminate the output with a newline.

Type-specific marshal functions and methods take precedence over the default representation of a value. Functions or methods that operate on *T are only called when encoding a value of type T (by taking its address) or a non-nil value of *T. Marshal ensures that a value is always addressable (by boxing it on the heap if necessary) so that these functions and methods can be consistently called. For performance, it is recommended that Marshal be passed a non-nil pointer to the value.

The input value is encoded as JSON according the following rules:

• If any type-specific functions in a WithMarshalers option match the value type, then those functions are called to encode the value. If all applicable functions return SkipFunc, then the value is encoded according to subsequent rules.

• If the value type implements MarshalerV2, then the MarshalJSONV2 method is called to encode the value.

• If the value type implements MarshalerV1, then the MarshalJSON method is called to encode the value.

• If the value type implements encoding.TextMarshaler, then the MarshalText method is called to encode the value and subsequently encode its result as a JSON string.

• Otherwise, the value is encoded according to the value's type as described in detail below.

Most Go types have a default JSON representation. Certain types support specialized formatting according to a format flag optionally specified in the Go struct tag for the struct field that contains the current value (see the “JSON Representation of Go structs” section for more details).

The representation of each type is as follows:

• A Go boolean is encoded as a JSON boolean (e.g., true or false). It does not support any custom format flags.

• A Go string is encoded as a JSON string. It does not support any custom format flags.

• A Go []byte or [N]byte is encoded as a JSON string containing the binary value encoded using RFC 4648. If the format is "base64" or unspecified, then this uses RFC 4648, section 4. If the format is "base64url", then this uses RFC 4648, section 5. If the format is "base32", then this uses RFC 4648, section 6. If the format is "base32hex", then this uses RFC 4648, section 7. If the format is "base16" or "hex", then this uses RFC 4648, section 8. If the format is "array", then the bytes value is encoded as a JSON array where each byte is recursively JSON-encoded as each JSON array element.

• A Go integer is encoded as a JSON number without fractions or exponents. If StringifyNumbers is specified, then the JSON number is encoded within a JSON string. It does not support any custom format flags.

• A Go float is encoded as a JSON number. If StringifyNumbers is specified, then the JSON number is encoded within a JSON string. If the format is "nonfinite", then NaN, +Inf, and -Inf are encoded as the JSON strings "NaN", "Infinity", and "-Infinity", respectively. Otherwise, the presence of non-finite numbers results in a SemanticError.

• A Go map is encoded as a JSON object, where each Go map key and value is recursively encoded as a name and value pair in the JSON object. The Go map key must encode as a JSON string, otherwise this results in a SemanticError. When encoding keys, StringifyNumbers is automatically applied so that numeric keys encode as JSON strings. The Go map is traversed in a non-deterministic order. For deterministic encoding, consider using jsontext.Value.Canonicalize. If the format is "emitnull", then a nil map is encoded as a JSON null. If the format is "emitempty", then a nil map is encoded as an empty JSON object, regardless of whether FormatNilMapAsNull is specified. Otherwise by default, a nil map is encoded as an empty JSON object.

• A Go struct is encoded as a JSON object. See the “JSON Representation of Go structs” section in the package-level documentation for more details.

• A Go slice is encoded as a JSON array, where each Go slice element is recursively JSON-encoded as the elements of the JSON array. If the format is "emitnull", then a nil slice is encoded as a JSON null. If the format is "emitempty", then a nil slice is encoded as an empty JSON array, regardless of whether FormatNilSliceAsNull is specified. Otherwise by default, a nil slice is encoded as an empty JSON array.

• A Go array is encoded as a JSON array, where each Go array element is recursively JSON-encoded as the elements of the JSON array. The JSON array length is always identical to the Go array length. It does not support any custom format flags.

• A Go pointer is encoded as a JSON null if nil, otherwise it is the recursively JSON-encoded representation of the underlying value. Format flags are forwarded to the encoding of the underlying value.

• A Go interface is encoded as a JSON null if nil, otherwise it is the recursively JSON-encoded representation of the underlying value. It does not support any custom format flags.

• A Go time.Time is encoded as a JSON string containing the timestamp formatted in RFC 3339 with nanosecond precision. If the format matches one of the format constants declared in the time package (e.g., RFC1123), then that format is used. If the format is "unix", "unixmilli", "unixmicro", or "unixnano", then the timestamp is encoded as a JSON number of the number of seconds (or milliseconds, microseconds, or nanoseconds) since the Unix epoch, which is January 1st, 1970 at 00:00:00 UTC. Otherwise, the format is used as-is with time.Time.Format if non-empty.

• A Go time.Duration is encoded as a JSON string containing the duration formatted according to time.Duration.String. If the format is "sec", "milli", "micro", or "nano", then the duration is encoded as a JSON number of the number of seconds (or milliseconds, microseconds, or nanoseconds) in the duration. If the format is "base60", it is encoded as a JSON string using the "H:MM:SS.SSSSSSSSS" representation. If the format is "units", it uses time.Duration.String.

• All other Go types (e.g., complex numbers, channels, and functions) have no default representation and result in a SemanticError.

JSON cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures will result in an error.

func MarshalEncode

func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) (err error)

MarshalEncode serializes a Go value into an jsontext.Encoder according to the provided marshal options (while ignoring unmarshal, encode, or decode options). Unlike Marshal and MarshalWrite, encode options are ignored because they must have already been specified on the provided jsontext.Encoder. See Marshal for details about the conversion of a Go value into JSON.

func MarshalWrite

func MarshalWrite(out io.Writer, in any, opts ...Options) (err error)

MarshalWrite serializes a Go value into an io.Writer according to the provided marshal and encode options (while ignoring unmarshal or decode options). It does not terminate the output with a newline. See Marshal for details about the conversion of a Go value into JSON.

func Unmarshal

func Unmarshal(in []byte, out any, opts ...Options) (err error)

Unmarshal decodes a []byte input into a Go value according to the provided unmarshal and decode options (while ignoring marshal or encode options). The input must be a single JSON value with optional whitespace interspersed. The output must be a non-nil pointer.

Type-specific unmarshal functions and methods take precedence over the default representation of a value. Functions or methods that operate on *T are only called when decoding a value of type T (by taking its address) or a non-nil value of *T. Unmarshal ensures that a value is always addressable (by boxing it on the heap if necessary) so that these functions and methods can be consistently called.

The input is decoded into the output according the following rules:

• If any type-specific functions in a WithUnmarshalers option match the value type, then those functions are called to decode the JSON value. If all applicable functions return SkipFunc, then the input is decoded according to subsequent rules.

• If the value type implements UnmarshalerV2, then the UnmarshalJSONV2 method is called to decode the JSON value.

• If the value type implements UnmarshalerV1, then the UnmarshalJSON method is called to decode the JSON value.

• If the value type implements encoding.TextUnmarshaler, then the input is decoded as a JSON string and the UnmarshalText method is called with the decoded string value. This fails with a SemanticError if the input is not a JSON string.

• Otherwise, the JSON value is decoded according to the value's type as described in detail below.

Most Go types have a default JSON representation. Certain types support specialized formatting according to a format flag optionally specified in the Go struct tag for the struct field that contains the current value (see the “JSON Representation of Go structs” section for more details). A JSON null may be decoded into every supported Go value where it is equivalent to storing the zero value of the Go value. If the input JSON kind is not handled by the current Go value type, then this fails with a SemanticError. Unless otherwise specified, the decoded value replaces any pre-existing value.

The representation of each type is as follows:

• A Go boolean is decoded from a JSON boolean (e.g., true or false). It does not support any custom format flags.

• A Go string is decoded from a JSON string. It does not support any custom format flags.

• A Go []byte or [N]byte is decoded from a JSON string containing the binary value encoded using RFC 4648. If the format is "base64" or unspecified, then this uses RFC 4648, section 4. If the format is "base64url", then this uses RFC 4648, section 5. If the format is "base32", then this uses RFC 4648, section 6. If the format is "base32hex", then this uses RFC 4648, section 7. If the format is "base16" or "hex", then this uses RFC 4648, section 8. If the format is "array", then the Go slice or array is decoded from a JSON array where each JSON element is recursively decoded for each byte. When decoding into a non-nil []byte, the slice length is reset to zero and the decoded input is appended to it. When decoding into a [N]byte, the input must decode to exactly N bytes, otherwise it fails with a SemanticError.

• A Go integer is decoded from a JSON number. It may also be decoded from a JSON string containing a JSON number if StringifyNumbers is specified. It fails with a SemanticError if the JSON number has a fractional or exponent component. It also fails if it overflows the representation of the Go integer type. It does not support any custom format flags.

• A Go float is decoded from a JSON number. It may also be decoded from a JSON string containing a JSON number if StringifyNumbers is specified. The JSON number is parsed as the closest representable Go float value. If the format is "nonfinite", then the JSON strings "NaN", "Infinity", and "-Infinity" are decoded as NaN, +Inf, and -Inf. Otherwise, the presence of such strings results in a SemanticError.

• A Go map is decoded from a JSON object, where each JSON object name and value pair is recursively decoded as the Go map key and value. When decoding keys, StringifyNumbers is automatically applied so that numeric keys can decode from JSON strings. Maps are not cleared. If the Go map is nil, then a new map is allocated to decode into. If the decoded key matches an existing Go map entry, the entry value is reused by decoding the JSON object value into it. The formats "emitnull" and "emitempty" have no effect when decoding.

• A Go struct is decoded from a JSON object. See the “JSON Representation of Go structs” section in the package-level documentation for more details.

• A Go slice is decoded from a JSON array, where each JSON element is recursively decoded and appended to the Go slice. Before appending into a Go slice, a new slice is allocated if it is nil, otherwise the slice length is reset to zero. The formats "emitnull" and "emitempty" have no effect when decoding.

• A Go array is decoded from a JSON array, where each JSON array element is recursively decoded as each corresponding Go array element. Each Go array element is zeroed before decoding into it. It fails with a SemanticError if the JSON array does not contain the exact same number of elements as the Go array. It does not support any custom format flags.

• A Go pointer is decoded based on the JSON kind and underlying Go type. If the input is a JSON null, then this stores a nil pointer. Otherwise, it allocates a new underlying value if the pointer is nil, and recursively JSON decodes into the underlying value. Format flags are forwarded to the decoding of the underlying type.

• A Go interface is decoded based on the JSON kind and underlying Go type. If the input is a JSON null, then this stores a nil interface value. Otherwise, a nil interface value of an empty interface type is initialized with a zero Go bool, string, float64, map[string]any, or []any if the input is a JSON boolean, string, number, object, or array, respectively. If the interface value is still nil, then this fails with a SemanticError since decoding could not determine an appropriate Go type to decode into. For example, unmarshaling into a nil io.Reader fails since there is no concrete type to populate the interface value with. Otherwise an underlying value exists and it recursively decodes the JSON input into it. It does not support any custom format flags.

• A Go time.Time is decoded from a JSON string containing the time formatted in RFC 3339 with nanosecond precision. If the format matches one of the format constants declared in the time package (e.g., RFC1123), then that format is used for parsing. If the format is "unix", "unixmilli", "unixmicro", or "unixnano", then the timestamp is decoded from a JSON number of the number of seconds (or milliseconds, microseconds, or nanoseconds) since the Unix epoch, which is January 1st, 1970 at 00:00:00 UTC. Otherwise, the format is used as-is with time.Time.Parse if non-empty.

• A Go time.Duration is decoded from a JSON string by passing the decoded string to time.ParseDuration. If the format is "sec", "milli", "micro", or "nano", then the duration is decoded from a JSON number of the number of seconds (or milliseconds, microseconds, or nanoseconds) in the duration. If the format is "base60", it is decoded from a JSON string using the "H:MM:SS.SSSSSSSSS" representation. If the format is "units", it uses time.ParseDuration.

• All other Go types (e.g., complex numbers, channels, and functions) have no default representation and result in a SemanticError.

In general, unmarshaling follows merge semantics (similar to RFC 7396) where the decoded Go value replaces the destination value for any JSON kind other than an object. For JSON objects, the input object is merged into the destination value where matching object members recursively apply merge semantics.

func UnmarshalDecode

func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) (err error)

UnmarshalDecode deserializes a Go value from a jsontext.Decoder according to the provided unmarshal options (while ignoring marshal, encode, or decode options). Unlike Unmarshal and UnmarshalRead, decode options are ignored because they must have already been specified on the provided jsontext.Decoder. The input may be a stream of one or more JSON values, where this only unmarshals the next JSON value in the stream. The output must be a non-nil pointer. See Unmarshal for details about the conversion of JSON into a Go value.

func UnmarshalRead

func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error)

UnmarshalRead deserializes a Go value from an io.Reader according to the provided unmarshal and decode options (while ignoring marshal or encode options). The input must be a single JSON value with optional whitespace interspersed. It consumes the entirety of io.Reader until io.EOF is encountered, without reporting an error for EOF. The output must be a non-nil pointer. See Unmarshal for details about the conversion of JSON into a Go value.

Types

type MarshalerV1

type MarshalerV1 interface {
	MarshalJSON() ([]byte, error)
}

MarshalerV1 is implemented by types that can marshal themselves. It is recommended that types implement MarshalerV2 unless the implementation is trying to avoid a hard dependency on the "jsontext" package.

It is recommended that implementations return a buffer that is safe for the caller to retain and potentially mutate.

type MarshalerV2

type MarshalerV2 interface {
	MarshalJSONV2(*jsontext.Encoder, Options) error
}

MarshalerV2 is implemented by types that can marshal themselves. It is recommended that types implement MarshalerV2 instead of MarshalerV1 since this is both more performant and flexible. If a type implements both MarshalerV1 and MarshalerV2, then MarshalerV2 takes precedence. In such a case, both implementations should aim to have equivalent behavior for the default marshal options.

The implementation must write only one JSON value to the Encoder and must not retain the pointer to jsontext.Encoder or the Options value.

type Marshalers

type Marshalers = typedMarshalers

Marshalers is a list of functions that may override the marshal behavior of specific types. Populate WithMarshalers to use it with Marshal, MarshalWrite, or MarshalEncode. A nil *Marshalers is equivalent to an empty list. There are no exported fields or methods on Marshalers.

func MarshalFuncV1

func MarshalFuncV1[T any](fn func(T) ([]byte, error)) *Marshalers

MarshalFuncV1 constructs a type-specific marshaler that specifies how to marshal values of type T. T can be any type except a named pointer. The function is always provided with a non-nil pointer value if T is an interface or pointer type.

The function must marshal exactly one JSON value. The value of T must not be retained outside the function call. It may not return SkipFunc.

func MarshalFuncV2

func MarshalFuncV2[T any](fn func(*jsontext.Encoder, T, Options) error) *Marshalers

MarshalFuncV2 constructs a type-specific marshaler that specifies how to marshal values of type T. T can be any type except a named pointer. The function is always provided with a non-nil pointer value if T is an interface or pointer type.

The function must marshal exactly one JSON value by calling write methods on the provided encoder. It may return SkipFunc such that marshaling can move on to the next marshal function. However, no mutable method calls may be called on the encoder if SkipFunc is returned. The pointer to jsontext.Encoder, the value of T, and the Options value must not be retained outside the function call.

func NewMarshalers

func NewMarshalers(ms ...*Marshalers) *Marshalers

NewMarshalers constructs a flattened list of marshal functions. If multiple functions in the list are applicable for a value of a given type, then those earlier in the list take precedence over those that come later. If a function returns SkipFunc, then the next applicable function is called, otherwise the default marshaling behavior is used.

For example:

m1 := NewMarshalers(f1, f2)
m2 := NewMarshalers(f0, m1, f3)     // equivalent to m3
m3 := NewMarshalers(f0, f1, f2, f3) // equivalent to m2

type Options

type Options = jsonopts.Options

Options configure Marshal, MarshalWrite, MarshalEncode, Unmarshal, UnmarshalRead, and UnmarshalDecode with specific features. Each function takes in a variadic list of options, where properties set in later options override the value of previously set properties.

The Options type is identical to encoding/json.Options and encoding/json/jsontext.Options. Options from the other packages can be used interchangeably with functionality in this package.

Options represent either a singular option or a set of options. It can be functionally thought of as a Go map of option properties (even though the underlying implementation avoids Go maps for performance).

The constructors (e.g., Deterministic) return a singular option value:

opt := Deterministic(true)

which is analogous to creating a single entry map:

opt := Options{"Deterministic": true}

JoinOptions composes multiple options values to together:

out := JoinOptions(opts...)

which is analogous to making a new map and copying the options over:

out := make(Options)
for _, m := range opts {
	for k, v := range m {
		out[k] = v
	}
}

GetOption looks up the value of options parameter:

v, ok := GetOption(opts, Deterministic)

which is analogous to a Go map lookup:

v, ok := Options["Deterministic"]

There is a single Options type, which is used with both marshal and unmarshal. Some options affect both operations, while others only affect one operation:

• StringifyNumbers affects marshaling and unmarshaling
• Deterministic affects marshaling only
• FormatNilSliceAsNull affects marshaling only
• FormatNilMapAsNull affects marshaling only
• MatchCaseInsensitiveNames affects marshaling and unmarshaling
• DiscardUnknownMembers affects marshaling only
• RejectUnknownMembers affects unmarshaling only
• WithMarshalers affects marshaling only
• WithUnmarshalers affects unmarshaling only

Options that do not affect a particular operation are ignored.

func DefaultOptionsV2

func DefaultOptionsV2() Options

DefaultOptionsV2 is the full set of all options that define v2 semantics. It is equivalent to all options under Options, encoding/json.Options, and encoding/json/jsontext.Options being set to false or the zero value, except for the options related to whitespace formatting.

func Deterministic

func Deterministic(v bool) Options

Deterministic specifies that the same input value will be serialized as the exact same output bytes. Different processes of the same program will serialize equal values to the same bytes, but different versions of the same program are not guaranteed to produce the exact same sequence of bytes.

This only affects marshaling and is ignored when unmarshaling.

func DiscardUnknownMembers

func DiscardUnknownMembers(v bool) Options

DiscardUnknownMembers specifies that marshaling should ignore any JSON object members stored in Go struct fields dedicated to storing unknown JSON object members.

This only affects marshaling and is ignored when unmarshaling.

func FormatNilMapAsNull

func FormatNilMapAsNull(v bool) Options

FormatNilMapAsNull specifies that a nil Go map should marshal as a JSON null instead of the default representation as an empty JSON object. Map fields explicitly marked with `format:emitempty` still marshal as an empty JSON object.

This only affects marshaling and is ignored when unmarshaling.

func FormatNilSliceAsNull

func FormatNilSliceAsNull(v bool) Options

FormatNilSliceAsNull specifies that a nil Go slice should marshal as a JSON null instead of the default representation as an empty JSON array (or an empty JSON string in the case of ~[]byte). Slice fields explicitly marked with `format:emitempty` still marshal as an empty JSON array.

This only affects marshaling and is ignored when unmarshaling.

func JoinOptions

func JoinOptions(srcs ...Options) Options

JoinOptions coalesces the provided list of options into a single Options. Properties set in later options override the value of previously set properties.

func MatchCaseInsensitiveNames

func MatchCaseInsensitiveNames(v bool) Options

MatchCaseInsensitiveNames specifies that JSON object members are matched against Go struct fields using a case-insensitive match of the name. Go struct fields explicitly marked with `strictcase` or `nocase` always use case-sensitive (or case-insensitive) name matching, regardless of the value of this option.

This affects either marshaling or unmarshaling. For marshaling, this option may alter the detection of duplicate names (assuming jsontext.AllowDuplicateNames is false) from inlined fields if it matches one of the declared fields in the Go struct.

func RejectUnknownMembers

func RejectUnknownMembers(v bool) Options

RejectUnknownMembers specifies that unknown members should be rejected when unmarshaling a JSON object, regardless of whether there is a field to store unknown members.

This only affects unmarshaling and is ignored when marshaling.

func StringifyNumbers

func StringifyNumbers(v bool) Options

StringifyNumbers specifies that numeric Go types should be marshaled as a JSON string containing the equivalent JSON number value. When unmarshaling, numeric Go types can be parsed from either a JSON number or a JSON string containing the JSON number without any surrounding whitespace.

According to RFC 8259, section 6, a JSON implementation may choose to limit the representation of a JSON number to an IEEE 754 binary64 value. This may cause decoders to lose precision for int64 and uint64 types. Quoting JSON numbers as a JSON string preserves the exact precision.

This affects either marshaling or unmarshaling.

func WithMarshalers

func WithMarshalers(v *Marshalers) Options

WithMarshalers specifies a list of type-specific marshalers to use, which can be used to override the default marshal behavior for values of particular types.

This only affects marshaling and is ignored when unmarshaling.

Example (Errors)

Many error types are not serializable since they tend to be Go structs without any exported fields (e.g., errors constructed with errors.New). Some applications, may desire to marshal an error as a JSON string even if these errors cannot be unmarshaled.

package main

import (
	"fmt"
	"log"
	"os"
	"strconv"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	// Response to serialize with some Go errors encountered.
	response := []struct {
		Result string `json:",omitzero"`
		Error  error  `json:",omitzero"`
	}{
		{Result: "Oranges are a good source of Vitamin C."},
		{Error: &strconv.NumError{Func: "ParseUint", Num: "-1234", Err: strconv.ErrSyntax}},
		{Error: &os.PathError{Op: "ReadFile", Path: "/path/to/secret/file", Err: os.ErrPermission}},
	}

	b, err := json.Marshal(&response,
		// Intercept every attempt to marshal an error type.
		json.WithMarshalers(json.NewMarshalers(
			// Suppose we consider strconv.NumError to be a safe to serialize:
			// this type-specific marshal function intercepts this type
			// and encodes the error message as a JSON string.
			json.MarshalFuncV2(func(enc *jsontext.Encoder, err *strconv.NumError, opts json.Options) error {
				return enc.WriteToken(jsontext.String(err.Error()))
			}),
			// Error messages may contain sensitive information that may not
			// be appropriate to serialize. For all errors not handled above,
			// report some generic error message.
			json.MarshalFuncV1(func(error) ([]byte, error) {
				return []byte(`"internal server error"`), nil
			}),
		)),
		jsontext.Multiline(true)) // expand for readability
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))

}

Output:

[
	{
		"Result": "Oranges are a good source of Vitamin C."
	},
	{
		"Error": "strconv.ParseUint: parsing \"-1234\": invalid syntax"
	},
	{
		"Error": "internal server error"
	}
]

func WithUnmarshalers

func WithUnmarshalers(v *Unmarshalers) Options

WithUnmarshalers specifies a list of type-specific unmarshalers to use, which can be used to override the default unmarshal behavior for values of particular types.

This only affects unmarshaling and is ignored when marshaling.

Example (RawNumber)

In some applications, the exact precision of JSON numbers needs to be preserved when unmarshaling. This can be accomplished using a type-specific unmarshal function that intercepts all any types and pre-populates the interface value with a jsontext.Value, which can represent a JSON number exactly.

package main

import (
	"fmt"
	"log"
	"reflect"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	// Input with JSON numbers beyond the representation of a float64.
	const input = `[false, 1e-1000, 3.141592653589793238462643383279, 1e+1000, true]`

	var value any
	err := json.Unmarshal([]byte(input), &value,
		// Intercept every attempt to unmarshal into the any type.
		json.WithUnmarshalers(
			json.UnmarshalFuncV2(func(dec *jsontext.Decoder, val *any, opts json.Options) error {
				// If the next value to be decoded is a JSON number,
				// then provide a concrete Go type to unmarshal into.
				if dec.PeekKind() == '0' {
					*val = jsontext.Value(nil)
				}
				// Return SkipFunc to fallback on default unmarshal behavior.
				return json.SkipFunc
			}),
		))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(value)

	// Sanity check.
	want := []any{false, jsontext.Value("1e-1000"), jsontext.Value("3.141592653589793238462643383279"), jsontext.Value("1e+1000"), true}
	if !reflect.DeepEqual(value, want) {
		log.Fatalf("value mismatch:\ngot  %v\nwant %v", value, want)
	}

}

Output:

[false 1e-1000 3.141592653589793238462643383279 1e+1000 true]

Example (RecordOffsets)

When using JSON for parsing configuration files, the parsing logic often needs to report an error with a line and column indicating where in the input an error occurred.

package main

import (
	"bytes"
	"fmt"
	"log"
	"net/netip"
	"strings"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	// Hypothetical configuration file.
	const input = `[
		{"Source": "192.168.0.100:1234", "Destination": "192.168.0.1:80"},
		{"Source": "192.168.0.251:4004"},
		{"Source": "192.168.0.165:8080", "Destination": "0.0.0.0:80"}
	]`
	type Tunnel struct {
		Source      netip.AddrPort
		Destination netip.AddrPort

		// ByteOffset is populated during unmarshal with the byte offset
		// within the JSON input of the JSON object for this Go struct.
		ByteOffset int64 `json:"-"` // metadata to be ignored for JSON serialization
	}

	var tunnels []Tunnel
	err := json.Unmarshal([]byte(input), &tunnels,
		// Intercept every attempt to unmarshal into the Tunnel type.
		json.WithUnmarshalers(
			json.UnmarshalFuncV2(func(dec *jsontext.Decoder, tunnel *Tunnel, opts json.Options) error {
				// Decoder.InputOffset reports the offset after the last token,
				// but we want to record the offset before the next token.
				//
				// Call Decoder.PeekKind to buffer enough to reach the next token.
				// Add the number of leading whitespace, commas, and colons
				// to locate the start of the next token.
				dec.PeekKind()
				unread := dec.UnreadBuffer()
				n := len(unread) - len(bytes.TrimLeft(unread, " \n\r\t,:"))
				tunnel.ByteOffset = dec.InputOffset() + int64(n)

				// Return SkipFunc to fallback on default unmarshal behavior.
				return json.SkipFunc
			}),
		))
	if err != nil {
		log.Fatal(err)
	}

	// lineColumn converts a byte offset into a one-indexed line and column.
	// The offset must be within the bounds of the input.
	lineColumn := func(input string, offset int) (line, column int) {
		line = 1 + strings.Count(input[:offset], "\n")
		column = 1 + offset - (strings.LastIndex(input[:offset], "\n") + len("\n"))
		return line, column
	}

	// Verify that the configuration file is valid.
	for _, tunnel := range tunnels {
		if !tunnel.Source.IsValid() || !tunnel.Destination.IsValid() {
			line, column := lineColumn(input, int(tunnel.ByteOffset))
			fmt.Printf("%d:%d: source and destination must both be specified", line, column)
		}
	}

}

Output:

3:3: source and destination must both be specified

type SemanticError

type SemanticError struct {

	// ByteOffset indicates that an error occurred after this byte offset.
	ByteOffset int64
	// JSONPointer indicates that an error occurred within this JSON value
	// as indicated using the JSON Pointer notation (see RFC 6901).
	JSONPointer jsontext.Pointer

	// JSONKind is the JSON kind that could not be handled.
	JSONKind jsontext.Kind // may be zero if unknown
	// GoType is the Go type that could not be handled.
	GoType reflect.Type // may be nil if unknown

	// Err is the underlying error.
	Err error // may be nil
	// contains filtered or unexported fields
}

SemanticError describes an error determining the meaning of JSON data as Go data or vice-versa.

The contents of this error as produced by this package may change over time.

func (*SemanticError) Error

func (e *SemanticError) Error() string

func (*SemanticError) Unwrap

func (e *SemanticError) Unwrap() error

type UnmarshalerV1

type UnmarshalerV1 interface {
	UnmarshalJSON([]byte) error
}

UnmarshalerV1 is implemented by types that can unmarshal themselves. It is recommended that types implement UnmarshalerV2 unless the implementation is trying to avoid a hard dependency on the "jsontext" package.

The input can be assumed to be a valid encoding of a JSON value if called from unmarshal functionality in this package. UnmarshalJSON must copy the JSON data if it is retained after returning. It is recommended that UnmarshalJSON implement merge semantics when unmarshaling into a pre-populated value.

Implementations must not retain or mutate the input []byte.

type UnmarshalerV2

type UnmarshalerV2 interface {
	UnmarshalJSONV2(*jsontext.Decoder, Options) error
}

UnmarshalerV2 is implemented by types that can unmarshal themselves. It is recommended that types implement UnmarshalerV2 instead of UnmarshalerV1 since this is both more performant and flexible. If a type implements both UnmarshalerV1 and UnmarshalerV2, then UnmarshalerV2 takes precedence. In such a case, both implementations should aim to have equivalent behavior for the default unmarshal options.

The implementation must read only one JSON value from the Decoder. It is recommended that UnmarshalJSONV2 implement merge semantics when unmarshaling into a pre-populated value.

Implementations must not retain the pointer to jsontext.Decoder or the Options value.

type Unmarshalers

type Unmarshalers = typedUnmarshalers

Unmarshalers is a list of functions that may override the unmarshal behavior of specific types. Populate WithUnmarshalers to use it with Unmarshal, UnmarshalRead, or UnmarshalDecode. A nil *Unmarshalers is equivalent to an empty list. There are no exported fields or methods on Unmarshalers.

func NewUnmarshalers

func NewUnmarshalers(us ...*Unmarshalers) *Unmarshalers

NewUnmarshalers constructs a flattened list of unmarshal functions. If multiple functions in the list are applicable for a value of a given type, then those earlier in the list take precedence over those that come later. If a function returns SkipFunc, then the next applicable function is called, otherwise the default unmarshaling behavior is used.

For example:

u1 := NewUnmarshalers(f1, f2)
u2 := NewUnmarshalers(f0, u1, f3)     // equivalent to u3
u3 := NewUnmarshalers(f0, f1, f2, f3) // equivalent to u2

func UnmarshalFuncV1

func UnmarshalFuncV1[T any](fn func([]byte, T) error) *Unmarshalers

UnmarshalFuncV1 constructs a type-specific unmarshaler that specifies how to unmarshal values of type T. T must be an unnamed pointer or an interface type. The function is always provided with a non-nil pointer value.

The function must unmarshal exactly one JSON value. The input []byte must not be mutated. The input []byte and value T must not be retained outside the function call. It may not return SkipFunc.

func UnmarshalFuncV2

func UnmarshalFuncV2[T any](fn func(*jsontext.Decoder, T, Options) error) *Unmarshalers

UnmarshalFuncV2 constructs a type-specific unmarshaler that specifies how to unmarshal values of type T. T must be an unnamed pointer or an interface type. The function is always provided with a non-nil pointer value.

The function must unmarshal exactly one JSON value by calling read methods on the provided decoder. It may return SkipFunc such that unmarshaling can move on to the next unmarshal function. However, no mutable method calls may be called on the decoder if SkipFunc is returned. The pointer to jsontext.Decoder, the value of T, and Options value must not be retained outside the function call.