944 lines
46 KiB
Go
944 lines
46 KiB
Go
// Copyright 2025 The Go Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
// Code generated by alias_gen.go; DO NOT EDIT.
|
|
|
|
//go:build goexperiment.jsonv2 && go1.25
|
|
|
|
// 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
|
|
// [Marshaler], [MarshalerTo], [Unmarshaler], or [UnmarshalerFrom].
|
|
// This provides authors of Go types with control over how their types are
|
|
// serialized as JSON. Alternatively, users can implement functions that match
|
|
// [MarshalFunc], [MarshalToFunc], [UnmarshalFunc], or [UnmarshalFromFunc]
|
|
// 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.
|
|
// Some options also have equivalent behavior controlled by a caller-specified [Options].
|
|
// Field-specified options take precedence over caller-specified options.
|
|
//
|
|
// 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.
|
|
// 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 types that would normally be encoded as a JSON number
|
|
// to instead be encoded as a JSON number quoted within a JSON string,
|
|
// and to be decoded from a JSON string containing the JSON number
|
|
// without any surrounding whitespace.
|
|
// The "string" option only applies to the top-level of the Go struct field value.
|
|
// Specifically, for the default representation of composite Go data types
|
|
// (e.g., array, slice, struct, or map), it will not stringify JSON numbers
|
|
// within such types. Applying this option to invalid types causes a runtime error.
|
|
// This extra level of encoding is often necessary since many JSON parsers
|
|
// cannot precisely represent 64-bit integers.
|
|
//
|
|
// - case: When unmarshaling, the "case" option specifies how
|
|
// JSON object names are matched with the JSON name for Go struct fields.
|
|
// The option is a key-value pair specified as "case:value" where
|
|
// the value must either be 'ignore' or 'strict'.
|
|
// The 'ignore' value specifies that matching is case-insensitive
|
|
// where dashes and underscores are also ignored. If multiple fields match,
|
|
// then the field with an exact name match is selected, otherwise an error
|
|
// is reported due to an ambiguous set of candidate fields to unmarshal into.
|
|
// The 'strict' value specifies that matching is case-sensitive.
|
|
// This takes precedence over the [MatchCaseInsensitiveNames] option.
|
|
//
|
|
// - embed: The "embed" 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 JSON embedded unless
|
|
// an explicit JSON name is specified. The embedded 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,
|
|
// embedded fields from a pointer type are omitted if it is nil.
|
|
// Embedded fields of type [jsontext.Value] and map[~string]T are called
|
|
// “embedded fallbacks” as they can represent all possible
|
|
// JSON object members not directly handled by the parent struct.
|
|
// Only one embedded 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).
|
|
//
|
|
// 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 embedded structs.
|
|
// The set of non-embedded 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:"-"`.
|
|
//
|
|
// # Security Considerations
|
|
//
|
|
// JSON is frequently used as a data interchange format to communicate
|
|
// between different systems, possibly implemented in different languages.
|
|
// For interoperability and security reasons, it is important that
|
|
// all implementations agree upon the semantic meaning of the data.
|
|
//
|
|
// [For example, suppose we have two micro-services.]
|
|
// The first service is responsible for authenticating a JSON request,
|
|
// while the second service is responsible for executing the request
|
|
// (having assumed that the prior service authenticated the request).
|
|
// If an attacker were able to maliciously craft a JSON request such that
|
|
// both services believe that the same request is from different users,
|
|
// it could bypass the authenticator with valid credentials for one user,
|
|
// but maliciously perform an action on behalf of a different user.
|
|
//
|
|
// According to RFC 8259, there unfortunately exist many JSON texts
|
|
// that are syntactically valid but semantically ambiguous.
|
|
// For example, the standard does not define how to interpret duplicate
|
|
// names within an object.
|
|
//
|
|
// The v1 [encoding/json] and [encoding/json/v2] packages
|
|
// interpret some inputs in different ways. In particular:
|
|
//
|
|
// - The standard specifies that JSON must be encoded using UTF-8.
|
|
// By default, v1 replaces invalid bytes of UTF-8 in JSON strings
|
|
// with the Unicode replacement character,
|
|
// while v2 rejects inputs with invalid UTF-8.
|
|
// To change the default, specify the [jsontext.AllowInvalidUTF8] option.
|
|
// The replacement of invalid UTF-8 is a form of data corruption
|
|
// that alters the precise meaning of strings.
|
|
//
|
|
// - The standard does not specify a particular behavior when
|
|
// duplicate names are encountered within a JSON object,
|
|
// which means that different implementations may behave differently.
|
|
// By default, v1 allows for the presence of duplicate names,
|
|
// while v2 rejects duplicate names.
|
|
// To change the default, specify the [jsontext.AllowDuplicateNames] option.
|
|
// If allowed, object members are processed in the order they are observed,
|
|
// meaning that later values will replace or be merged into prior values,
|
|
// depending on the Go value type.
|
|
//
|
|
// - The standard defines a JSON object as an unordered collection of name/value pairs.
|
|
// While ordering can be observed through the underlying [jsontext] API,
|
|
// both v1 and v2 generally avoid exposing the ordering.
|
|
// No application should semantically depend on the order of object members.
|
|
// Allowing duplicate names is a vector through which ordering of members
|
|
// can accidentally be observed and depended upon.
|
|
//
|
|
// - The standard suggests that JSON object names are typically compared
|
|
// based on equality of the sequence of Unicode code points,
|
|
// which implies that comparing names is often case-sensitive.
|
|
// When unmarshaling a JSON object into a Go struct,
|
|
// by default, v1 uses a (loose) case-insensitive match on the name,
|
|
// while v2 uses a (strict) case-sensitive match on the name.
|
|
// To change the default, specify the [MatchCaseInsensitiveNames] option.
|
|
// The use of case-insensitive matching provides another vector through
|
|
// which duplicate names can occur. Allowing case-insensitive matching
|
|
// means that v1 or v2 might interpret JSON objects differently from most
|
|
// other JSON implementations (which typically use a case-sensitive match).
|
|
//
|
|
// - The standard does not specify a particular behavior when
|
|
// an unknown name in a JSON object is encountered.
|
|
// When unmarshaling a JSON object into a Go struct, by default
|
|
// both v1 and v2 ignore unknown names and their corresponding values.
|
|
// To change the default, specify the [RejectUnknownMembers] option.
|
|
//
|
|
// - The standard suggests that implementations may use a float64
|
|
// to represent a JSON number. Consequently, large JSON integers
|
|
// may lose precision when stored as a floating-point type.
|
|
// Both v1 and v2 correctly preserve precision when marshaling and
|
|
// unmarshaling a concrete integer type. However, even if v1 and v2
|
|
// preserve precision for concrete types, other JSON implementations
|
|
// may not be able to preserve precision for outputs produced by v1 or v2.
|
|
// The `string` tag option can be used to specify that an integer type
|
|
// is to be quoted within a JSON string to avoid loss of precision.
|
|
// Furthermore, v1 and v2 may still lose precision when unmarshaling
|
|
// into an any interface value, where unmarshal uses a float64
|
|
// by default to represent a JSON number.
|
|
// To change the default, specify the [WithUnmarshalers] option
|
|
// with a custom unmarshaler that pre-populates the interface value
|
|
// with a concrete Go type that can preserve precision.
|
|
//
|
|
// RFC 8785 specifies a canonical form for any JSON text,
|
|
// which explicitly defines specific behaviors that RFC 8259 leaves undefined.
|
|
// In theory, if a text can successfully [jsontext.Value.Canonicalize]
|
|
// without changing the semantic meaning of the data, then it provides a
|
|
// greater degree of confidence that the data is more secure and interoperable.
|
|
//
|
|
// The v2 API generally chooses more secure defaults than v1,
|
|
// but care should still be taken with large integers or unknown members.
|
|
//
|
|
// [For example, suppose we have two micro-services.]: https://www.youtube.com/watch?v=avilmOcHKHE&t=1057s
|
|
package json
|
|
|
|
import (
|
|
"encoding/json/jsontext"
|
|
"encoding/json/v2"
|
|
"io"
|
|
)
|
|
|
|
// 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 copying the value 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 to 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 [errors.ErrUnsupported],
|
|
// then the value is encoded according to subsequent rules.
|
|
//
|
|
// - If the value type implements [MarshalerTo],
|
|
// then the MarshalJSONTo method is called to encode the value.
|
|
// If the method returns [errors.ErrUnsupported],
|
|
// then the input is encoded according to subsequent rules.
|
|
//
|
|
// - If the value type implements [Marshaler],
|
|
// then the MarshalJSON method is called to encode the value.
|
|
//
|
|
// - If the value type implements [encoding.TextAppender],
|
|
// then the AppendText method is called to encode the value and
|
|
// subsequently encode its result as a JSON string.
|
|
//
|
|
// - 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 as follows:
|
|
//
|
|
// - A Go boolean is encoded as a JSON boolean (e.g., true or false).
|
|
//
|
|
// - A Go string is encoded as a JSON string.
|
|
//
|
|
// - A Go []byte or [N]byte is encoded as a JSON string containing
|
|
// a binary value using Base 64 Encoding per RFC 4648, section 4.
|
|
//
|
|
// - A Go integer is encoded as a JSON number without fractions or exponents.
|
|
// If [StringifyNumbers] is specified or encoding a JSON object name,
|
|
// then the JSON number is encoded within a JSON string.
|
|
//
|
|
// - A Go float is encoded as a JSON number.
|
|
// If [StringifyNumbers] is specified or encoding a JSON object name,
|
|
// then the JSON number is encoded within a JSON string.
|
|
// Encoding a NaN or ±Inf 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]. The Go map is traversed in a non-deterministic order.
|
|
// For deterministic encoding, consider using the [Deterministic] option.
|
|
// By default, a nil map is encoded as an empty JSON object,
|
|
// unless the [FormatNilMapAsNull] option is specified.
|
|
//
|
|
// - 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.
|
|
// By default, a nil slice is encoded as an empty JSON array,
|
|
// unless the [FormatNilSliceAsNull] option is specified.
|
|
//
|
|
// - 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.
|
|
//
|
|
// - A Go pointer is encoded as a JSON null if nil, otherwise it is
|
|
// the recursively JSON-encoded representation 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.
|
|
//
|
|
// - A Go [time.Time] is encoded as a JSON string containing the timestamp
|
|
// formatted in RFC 3339 with nanosecond precision.
|
|
//
|
|
// - A Go [time.Duration] currently has no default representation and
|
|
// results in a [SemanticError], unless the [encoding/json.FormatDurationAsNano]
|
|
// option is specified, in which case it is encoded as a JSON number
|
|
// without fractions or exponents, representing the duration in nanoseconds.
|
|
//
|
|
// - 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 Marshal(in any, opts ...Options) (out []byte, err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.Marshal(in, opts...)
|
|
}
|
|
|
|
// 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 MarshalWrite(out io.Writer, in any, opts ...Options) (err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.MarshalWrite(out, in, opts...)
|
|
}
|
|
|
|
// MarshalEncode serializes a Go value into an [jsontext.Encoder] according to
|
|
// the provided marshal or encode options (while ignoring unmarshal or decode options).
|
|
// The options provided take precedence over options already applied on
|
|
// the [jsontext.Encoder] and only apply for the duration of the marshal call.
|
|
//
|
|
// See [Marshal] for details about the conversion of a Go value into JSON.
|
|
func MarshalEncode(out *jsontext.Encoder, in any, opts ...Options) (err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.MarshalEncode(out, in, opts...)
|
|
}
|
|
|
|
// 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 copying the value if necessary) so that
|
|
// these functions and methods can be consistently called.
|
|
// If a value must be shallow copied to call a pointer-receiver
|
|
// [Unmarshaler], [UnmarshalerFrom], or [encoding.TextUnmarshaler] method,
|
|
// then any mutations performed by the method are shallow copied back
|
|
// into the destination value.
|
|
//
|
|
// The input is decoded into the output according to 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 [errors.ErrUnsupported],
|
|
// then the input is decoded according to subsequent rules.
|
|
//
|
|
// - If the value type implements [UnmarshalerFrom],
|
|
// then the UnmarshalJSONFrom method is called to decode the JSON value.
|
|
// If the method returns [errors.ErrUnsupported],
|
|
// then the input is decoded according to subsequent rules.
|
|
//
|
|
// - If the value type implements [Unmarshaler],
|
|
// 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.
|
|
// 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).
|
|
//
|
|
// - A Go string is decoded from a JSON string.
|
|
//
|
|
// - A Go []byte or [N]byte is decoded from a JSON string containing
|
|
// a binary value using Base 64 Encoding per RFC 4648, section 4.
|
|
// 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 must be decoded from a JSON string containing a JSON number
|
|
// if [StringifyNumbers] is specified or decoding a JSON object name.
|
|
// 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.
|
|
//
|
|
// - A Go float is decoded from a JSON number.
|
|
// It must be decoded from a JSON string containing a JSON number
|
|
// if [StringifyNumbers] is specified or decoding a JSON object name.
|
|
// It fails if it overflows the representation of the Go float type.
|
|
// Since JSON lacks a native representation for a NaN or ±Inf,
|
|
// such values cannot be the result of decoding.
|
|
//
|
|
// - 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. 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.
|
|
//
|
|
// - 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.
|
|
//
|
|
// - 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.
|
|
//
|
|
// - 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.
|
|
//
|
|
// - 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.
|
|
//
|
|
// - A Go [time.Time] is decoded from a JSON string containing the time
|
|
// formatted in RFC 3339 with nanosecond precision.
|
|
//
|
|
// - A Go [time.Duration] currently has no default representation and
|
|
// results in a [SemanticError], unless the [encoding/json.FormatDurationAsNano]
|
|
// option is specified, in which case it is decoded as a JSON number
|
|
// without fractions or exponents, representing the duration in nanoseconds.
|
|
//
|
|
// - 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 Unmarshal(in []byte, out any, opts ...Options) (err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.Unmarshal(in, out, opts...)
|
|
}
|
|
|
|
// 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.
|
|
func UnmarshalRead(in io.Reader, out any, opts ...Options) (err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.UnmarshalRead(in, out, opts...)
|
|
}
|
|
|
|
// UnmarshalDecode deserializes a Go value from a [jsontext.Decoder] according to
|
|
// the provided unmarshal or decode options (while ignoring marshal or encode options).
|
|
// The options provided take precedence over options already applied on
|
|
// the [jsontext.Decoder] and only apply for the duration of the unmarshal call.
|
|
//
|
|
// The input may be a stream of zero or more JSON values,
|
|
// where this only unmarshals the next JSON value in the stream.
|
|
// If there are no more top-level JSON values, it reports [io.EOF].
|
|
// The output must be a non-nil pointer.
|
|
// See [Unmarshal] for details about the conversion of JSON into a Go value.
|
|
func UnmarshalDecode(in *jsontext.Decoder, out any, opts ...Options) (err error) {
|
|
opts = mayAppendSupportFormatTag(opts)
|
|
return json.UnmarshalDecode(in, out, opts...)
|
|
}
|
|
|
|
// 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.
|
|
type Marshalers = json.Marshalers
|
|
|
|
// JoinMarshalers 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 [errors.ErrUnsupported],
|
|
// then the next applicable function is called,
|
|
// otherwise the default marshaling behavior is used.
|
|
//
|
|
// For example:
|
|
//
|
|
// m1 := JoinMarshalers(f1, f2)
|
|
// m2 := JoinMarshalers(f0, m1, f3) // equivalent to m3
|
|
// m3 := JoinMarshalers(f0, f1, f2, f3) // equivalent to m2
|
|
func JoinMarshalers(ms ...*Marshalers) *Marshalers {
|
|
return json.JoinMarshalers(ms...)
|
|
}
|
|
|
|
// 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.
|
|
type Unmarshalers = json.Unmarshalers
|
|
|
|
// JoinUnmarshalers 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 [errors.ErrUnsupported],
|
|
// then the next applicable function is called,
|
|
// otherwise the default unmarshaling behavior is used.
|
|
//
|
|
// For example:
|
|
//
|
|
// u1 := JoinUnmarshalers(f1, f2)
|
|
// u2 := JoinUnmarshalers(f0, u1, f3) // equivalent to u3
|
|
// u3 := JoinUnmarshalers(f0, f1, f2, f3) // equivalent to u2
|
|
func JoinUnmarshalers(us ...*Unmarshalers) *Unmarshalers {
|
|
return json.JoinUnmarshalers(us...)
|
|
}
|
|
|
|
// MarshalFunc 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 is recommended that fn return a []byte buffer that is safe
|
|
// for the caller to retain and potentially mutate.
|
|
// It may not return [errors.ErrUnsupported].
|
|
func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers {
|
|
return json.MarshalFunc[T](fn)
|
|
}
|
|
|
|
// MarshalToFunc 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 [errors.ErrUnsupported] such that marshaling can
|
|
// move on to the next marshal function. However, no mutable method calls may
|
|
// be called on the encoder if [errors.ErrUnsupported] is returned.
|
|
// The pointer to [jsontext.Encoder] and the value of T
|
|
// must not be retained outside the function call.
|
|
func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers {
|
|
return json.MarshalToFunc[T](fn)
|
|
}
|
|
|
|
// UnmarshalFunc 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 [errors.ErrUnsupported].
|
|
func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers {
|
|
return json.UnmarshalFunc[T](fn)
|
|
}
|
|
|
|
// UnmarshalFromFunc 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 [errors.ErrUnsupported] such that unmarshaling can
|
|
// move on to the next unmarshal function. However, no mutable method calls may
|
|
// be called on the decoder if [errors.ErrUnsupported] is returned.
|
|
// The pointer to [jsontext.Decoder] and the value of T
|
|
// must not be retained outside the function call.
|
|
func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers {
|
|
return json.UnmarshalFromFunc[T](fn)
|
|
}
|
|
|
|
// Marshaler is implemented by types that can marshal themselves.
|
|
// It is recommended that types implement [MarshalerTo] 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.
|
|
//
|
|
// If the returned error is a [SemanticError], then unpopulated fields
|
|
// of the error may be populated by [json] with additional context.
|
|
// Errors of other types are wrapped within a [SemanticError].
|
|
type Marshaler = json.Marshaler
|
|
|
|
// MarshalerTo is implemented by types that can marshal themselves.
|
|
// It is recommended that types implement MarshalerTo instead of [Marshaler]
|
|
// since this is both more performant and flexible.
|
|
// If a type implements both Marshaler and MarshalerTo,
|
|
// then MarshalerTo 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.
|
|
// Alternatively, it may return [errors.ErrUnsupported] without mutating
|
|
// the Encoder. The "json" package calling the method will
|
|
// use the next available JSON representation for the receiver type.
|
|
// Implementations must not retain the pointer to [jsontext.Encoder].
|
|
//
|
|
// If the returned error is a [SemanticError], then unpopulated fields
|
|
// of the error may be populated by [json] with additional context.
|
|
// Errors of other types are wrapped within a [SemanticError],
|
|
// unless it is an IO error.
|
|
//
|
|
// The MarshalJSONTo method should not be directly called as it may
|
|
// return sentinel errors that need special handling.
|
|
// Users should instead call [MarshalEncode], which handles such cases.
|
|
type MarshalerTo = json.MarshalerTo
|
|
|
|
// Unmarshaler is implemented by types that can unmarshal themselves.
|
|
// It is recommended that types implement [UnmarshalerFrom] 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.
|
|
//
|
|
// If the returned error is a [SemanticError], then unpopulated fields
|
|
// of the error may be populated by [json] with additional context.
|
|
// Errors of other types are wrapped within a [SemanticError].
|
|
type Unmarshaler = json.Unmarshaler
|
|
|
|
// UnmarshalerFrom is implemented by types that can unmarshal themselves.
|
|
// It is recommended that types implement UnmarshalerFrom instead of [Unmarshaler]
|
|
// since this is both more performant and flexible.
|
|
// If a type implements both Unmarshaler and UnmarshalerFrom,
|
|
// then UnmarshalerFrom 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 UnmarshalJSONFrom implement merge semantics when
|
|
// unmarshaling into a pre-populated value.
|
|
// Alternatively, it may return [errors.ErrUnsupported] without mutating
|
|
// the Decoder. The "json" package calling the method will
|
|
// use the next available JSON representation for the receiver type.
|
|
// Implementations must not retain the pointer to [jsontext.Decoder].
|
|
//
|
|
// If the returned error is a [SemanticError], then unpopulated fields
|
|
// of the error may be populated by [json] with additional context.
|
|
// Errors of other types are wrapped within a [SemanticError],
|
|
// unless it is a [jsontext.SyntacticError] or an IO error.
|
|
//
|
|
// The UnmarshalJSONFrom method should not be directly called as it may
|
|
// return sentinel errors that need special handling.
|
|
// Users should instead call [UnmarshalDecode], which handles such cases.
|
|
type UnmarshalerFrom = json.UnmarshalerFrom
|
|
|
|
// ErrUnknownName indicates that a JSON object member could not be
|
|
// unmarshaled because the name is not known to the target Go struct.
|
|
// This error is directly wrapped within a [SemanticError] when produced.
|
|
//
|
|
// The name of an unknown JSON object member can be extracted as:
|
|
//
|
|
// err := ...
|
|
// serr, ok := errors.AsType[*json.SemanticError](err)
|
|
// if ok && serr.Err == json.ErrUnknownName {
|
|
// ptr := serr.JSONPointer // JSON pointer to unknown name
|
|
// name := ptr.LastToken() // unknown name itself
|
|
// ...
|
|
// }
|
|
//
|
|
// This error is only returned if [RejectUnknownMembers] is true.
|
|
var ErrUnknownName = json.ErrUnknownName
|
|
|
|
// SemanticError describes an error determining the meaning
|
|
// of JSON data as Go data or vice-versa.
|
|
//
|
|
// If a [Marshaler], [MarshalerTo], [Unmarshaler], or [UnmarshalerFrom] method
|
|
// returns a SemanticError when called by the [json] package,
|
|
// then the ByteOffset, JSONPointer, and GoType fields are automatically
|
|
// populated by the calling context if they are the zero value.
|
|
//
|
|
// The contents of this error as produced by this package may change over time.
|
|
type SemanticError = json.SemanticError
|
|
|
|
// 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 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 an 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
|
|
// - [OmitZeroStructFields] affects marshaling only
|
|
// - [MatchCaseInsensitiveNames] affects marshaling and unmarshaling
|
|
// - [RejectUnknownMembers] affects unmarshaling only
|
|
// - [WithMarshalers] affects marshaling only
|
|
// - [WithUnmarshalers] affects unmarshaling only
|
|
//
|
|
// Options that do not affect a particular operation are ignored.
|
|
type Options = json.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 JoinOptions(srcs ...Options) Options {
|
|
return json.JoinOptions(srcs...)
|
|
}
|
|
|
|
// GetOption returns the value stored in opts with the provided setter,
|
|
// reporting whether the value is present.
|
|
// If not present, the returned value is the zero value for type T.
|
|
//
|
|
// Example usage:
|
|
//
|
|
// v, ok := json.GetOption(opts, json.Deterministic)
|
|
//
|
|
// Options are most commonly introspected to alter the JSON representation of
|
|
// [MarshalerTo.MarshalJSONTo] and [UnmarshalerFrom.UnmarshalJSONFrom] methods, and
|
|
// [MarshalToFunc] and [UnmarshalFromFunc] functions.
|
|
// In such cases, the presence bit should generally be ignored.
|
|
func GetOption[T any](opts Options, setter func(T) Options) (T, bool) {
|
|
return json.GetOption[T](opts, setter)
|
|
}
|
|
|
|
// DefaultOptionsV2 is the full set of all options that define v2 semantics.
|
|
// It is equivalent to the set of options in [encoding/json.DefaultOptionsV1]
|
|
// all being set to false. All other options are not present.
|
|
func DefaultOptionsV2() Options {
|
|
return json.DefaultOptionsV2()
|
|
}
|
|
|
|
// StringifyNumbers specifies that types that would normally be
|
|
// encoded as a JSON number to instead be encoded as a JSON string
|
|
// containing the equivalent JSON number value.
|
|
// When unmarshaling, the value is parsed from a JSON string
|
|
// containing the JSON number without any surrounding whitespace.
|
|
//
|
|
// When the `string` tag option is specified on a Go struct field,
|
|
// this option is applied for the top-level JSON value for that field.
|
|
// Unless StringifyNumbers was applied globally, the option does not
|
|
// recursively apply to nested JSON numbers within a JSON object or array.
|
|
// A Go type with custom marshal/unmarshal that represents a JSON number
|
|
// should respect the StringifyNumbers option and if specified
|
|
// serialize as a JSON number within a JSON string.
|
|
//
|
|
// 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 StringifyNumbers(v bool) Options {
|
|
return json.StringifyNumbers(v)
|
|
}
|
|
|
|
// 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 Deterministic(v bool) Options {
|
|
return json.Deterministic(v)
|
|
}
|
|
|
|
// 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).
|
|
//
|
|
// This only affects marshaling and is ignored when unmarshaling.
|
|
func FormatNilSliceAsNull(v bool) Options {
|
|
return json.FormatNilSliceAsNull(v)
|
|
}
|
|
|
|
// FormatNilMapAsNull specifies that a nil Go map should marshal as a
|
|
// JSON null instead of the default representation as an empty JSON object.
|
|
//
|
|
// This only affects marshaling and is ignored when unmarshaling.
|
|
func FormatNilMapAsNull(v bool) Options {
|
|
return json.FormatNilMapAsNull(v)
|
|
}
|
|
|
|
// OmitZeroStructFields specifies that a Go struct should marshal in such a way
|
|
// that all struct fields that are zero are omitted from the marshaled output
|
|
// if the value is zero as determined by the "IsZero() bool" method if present,
|
|
// otherwise based on whether the field is the zero Go value.
|
|
// This is semantically equivalent to specifying the `omitzero` tag option
|
|
// on every field in a Go struct.
|
|
//
|
|
// This only affects marshaling and is ignored when unmarshaling.
|
|
func OmitZeroStructFields(v bool) Options {
|
|
return json.OmitZeroStructFields(v)
|
|
}
|
|
|
|
// MatchCaseInsensitiveNames specifies that JSON object members are matched
|
|
// against Go struct fields using a case-insensitive match of the name.
|
|
// If a name matches multiple fields, it chooses the field with an exact
|
|
// match of the name, otherwise it reports an error.
|
|
// Go struct fields explicitly marked with `case:strict` or `case:ignore`
|
|
// always use case-sensitive (or case-insensitive) name matching,
|
|
// regardless of the value of this option.
|
|
//
|
|
// This affects either marshaling or unmarshaling.
|
|
//
|
|
// By matching names in a case-insensitive manner, it also affects the detection
|
|
// of duplicate names (assuming [jsontext.AllowDuplicateNames] is false) since
|
|
// variations of the same name may match the same Go struct field.
|
|
// For example, when unmarshaling, the names "foo" and "Foo" may both
|
|
// match the same Go struct field and therefore be considered a duplicate name.
|
|
// When marshaling, normally it is impossible for any two Go struct fields to
|
|
// serialize in a way where they unmarshal into the same Go struct field
|
|
// since they all have unique exact names.
|
|
// However, with the use of an embedded fallback, it is possible for the
|
|
// embedded fallback to contain a name that also matches the name for
|
|
// a Go struct field, resulting in a duplicate name error.
|
|
func MatchCaseInsensitiveNames(v bool) Options {
|
|
return json.MatchCaseInsensitiveNames(v)
|
|
}
|
|
|
|
// RejectUnknownMembers specifies that unknown members should be rejected
|
|
// when unmarshaling a JSON object.
|
|
//
|
|
// This only affects unmarshaling and is ignored when marshaling.
|
|
func RejectUnknownMembers(v bool) Options {
|
|
return json.RejectUnknownMembers(v)
|
|
}
|
|
|
|
// 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.
|
|
func WithMarshalers(v *Marshalers) Options {
|
|
return json.WithMarshalers(v)
|
|
}
|
|
|
|
// 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.
|
|
func WithUnmarshalers(v *Unmarshalers) Options {
|
|
return json.WithUnmarshalers(v)
|
|
}
|