proxy.golang.org : github.com/quic-go/json
Package json implements encoding and decoding of JSON as defined in RFC 7159. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions. See "JSON and Go" for an introduction to this package: https://golang.org/doc/articles/json_and_go.html See the "Security Considerations" section in encoding/json/v2. For historical reasons, the default behavior of v1 encoding/json unfortunately operates with less secure defaults. New usages of JSON in Go are encouraged to use encoding/json/v2 instead. This package (i.e., encoding/json) is now formally known as the v1 package since a v2 package now exists at encoding/json/v2. All the behavior of the v1 package is implemented in terms of the v2 package with the appropriate set of options specified that preserve the historical behavior of v1. The jsonv2.Marshal function is the newer equivalent of v1 Marshal. The jsonv2.Unmarshal function is the newer equivalent of v1 Unmarshal. The v2 functions have the same calling signature as the v1 equivalent except that they take in variadic Options arguments that can be specified to alter the behavior of marshal or unmarshal. Both v1 and v2 generally behave in similar ways, but there are some notable differences. The following is a list of differences between v1 and v2: In v1, JSON object members are unmarshaled into a Go struct using a case-insensitive name match with the JSON name of the fields. In contrast, v2 matches fields using an exact, case-sensitive match. The jsonv2.MatchCaseInsensitiveNames and MatchCaseSensitiveDelimiter options control this behavior difference. To explicitly specify a Go struct field to use a particular name matching scheme, either the `case:ignore` or the `case:strict` field option can be specified. Field-specified options take precedence over caller-specified options. In v1, when marshaling a Go struct, a field marked as `omitempty` is omitted if the field value is an "empty" Go value, which is defined as false, 0, a nil pointer, a nil interface value, and any empty array, slice, map, or string. In contrast, v2 redefines `omitempty` to omit a field if it encodes as an "empty" JSON value, which is defined as a JSON null, or an empty JSON string, object, or array. The OmitEmptyWithLegacySemantics option controls this behavior difference. Note that `omitempty` behaves identically in both v1 and v2 for a Go array, slice, map, or string (assuming no user-defined MarshalJSON method overrides the default representation). Existing usages of `omitempty` on a Go bool, number, pointer, or interface value should migrate to specifying `omitzero` instead (which is identically supported in both v1 and v2). In v1, a Go struct field marked as `string` can be used to quote a Go string, bool, or number as a JSON string. It does not recursively take effect on composite Go types. In contrast, v2 restricts the `string` option to only quote a Go number as a JSON string. It does recursively take effect on Go numbers within a composite Go type. The StringifyWithLegacySemantics option controls this behavior difference. In v1, a nil Go slice or Go map is marshaled as a JSON null. In contrast, v2 marshals a nil Go slice or Go map as an empty JSON array or JSON object, respectively. The jsonv2.FormatNilSliceAsNull and jsonv2.FormatNilMapAsNull options control this behavior difference. To explicitly specify a Go struct field to use a particular representation for nil, either the `format:emitempty` or `format:emitnull` field option can be specified. Field-specified options take precedence over caller-specified options. In v1, a Go array may be unmarshaled from a JSON array of any length. In contrast, in v2 a Go array must be unmarshaled from a JSON array of the same length, otherwise it results in an error. The UnmarshalArrayFromAnyLength option controls this behavior difference. In v1, a Go byte array is represented as a JSON array of JSON numbers. In contrast, in v2 a Go byte array is represented as a Base64-encoded JSON string. The FormatByteArrayAsArray option controls this behavior difference. To explicitly specify a Go struct field to use a particular representation, either the `format:array` or `format:base64` field option can be specified. Field-specified options take precedence over caller-specified options. In v1, MarshalJSON methods declared on a pointer receiver are only called if the Go value is addressable. In contrast, in v2 a MarshalJSON method is always callable regardless of addressability. The CallMethodsWithLegacySemantics option controls this behavior difference. In v1, MarshalJSON and UnmarshalJSON methods are never called for Go map keys. In contrast, in v2 a MarshalJSON or UnmarshalJSON method is eligible for being called for Go map keys. The CallMethodsWithLegacySemantics option controls this behavior difference. In v1, a Go map is marshaled in a deterministic order. In contrast, in v2 a Go map is marshaled in a non-deterministic order. The jsonv2.Deterministic option controls this behavior difference. In v1, JSON strings are encoded with HTML-specific or JavaScript-specific characters being escaped. In contrast, in v2 JSON strings use the minimal encoding and only escape if required by the JSON grammar. The jsontext.EscapeForHTML and jsontext.EscapeForJS options control this behavior difference. In v1, bytes of invalid UTF-8 within a string are silently replaced with the Unicode replacement character. In contrast, in v2 the presence of invalid UTF-8 results in an error. The jsontext.AllowInvalidUTF8 option controls this behavior difference. In v1, a JSON object with duplicate names is permitted. In contrast, in v2 a JSON object with duplicate names results in an error. The jsontext.AllowDuplicateNames option controls this behavior difference. In v1, when unmarshaling a JSON null into a non-empty Go value it will inconsistently either zero out the value or do nothing. In contrast, in v2 unmarshaling a JSON null will consistently and always zero out the underlying Go value. The MergeWithLegacySemantics option controls this behavior difference. In v1, when unmarshaling a JSON value into a non-zero Go value, it merges into the original Go value for array elements, slice elements, struct fields (but not map values), pointer values, and interface values (only if a non-nil pointer). In contrast, in v2 unmarshal merges into the Go value for struct fields, map values, pointer values, and interface values. In general, the v2 semantic merges when unmarshaling a JSON object, otherwise it replaces the value. The MergeWithLegacySemantics option controls this behavior difference. In v1, a time.Duration is represented as a JSON number containing the decimal number of nanoseconds. In contrast, in v2 a time.Duration has no default representation and results in a runtime error. The FormatDurationAsNano option controls this behavior difference. To explicitly specify a Go struct field to use a particular representation, either the `format:nano` or `format:units` field option can be specified. Field-specified options take precedence over caller-specified options. In v1, errors are never reported at runtime for Go struct types that have some form of structural error (e.g., a malformed tag option). In contrast, v2 reports a runtime error for Go types that are invalid as they relate to JSON serialization. For example, a Go struct with only unexported fields cannot be serialized. The ReportErrorsWithLegacySemantics option controls this behavior difference. As mentioned, the entirety of v1 is implemented in terms of v2, where options are implicitly specified to opt into legacy behavior. For example, Marshal directly calls jsonv2.Marshal with DefaultOptionsV1. Similarly, Unmarshal directly calls jsonv2.Unmarshal with DefaultOptionsV1. The DefaultOptionsV1 option represents the set of all options that specify default v1 behavior. For many of the behavior differences, there are Go struct field options that the author of a Go type can specify to control the behavior such that the type is represented identically in JSON under either v1 or v2 semantics. The availability of DefaultOptionsV1 and jsonv2.DefaultOptionsV2, where later options take precedence over former options allows for a gradual migration from v1 to v2. For example: jsonv1.Marshal(v) uses default v1 semantics. jsonv2.Marshal(v, jsonv1.DefaultOptionsV1()) is semantically equivalent to jsonv1.Marshal and thus uses default v1 semantics. jsonv2.Marshal(v, jsonv1.DefaultOptionsV1(), jsontext.AllowDuplicateNames(false)) uses mostly v1 semantics, but opts into one particular v2-specific behavior. jsonv2.Marshal(v, jsonv1.CallMethodsWithLegacySemantics(true)) uses mostly v2 semantics, but opts into one particular v1-specific behavior. jsonv2.Marshal(v, ..., jsonv2.DefaultOptionsV2()) is semantically equivalent to jsonv2.Marshal since jsonv2.DefaultOptionsV2 overrides any options specified earlier and thus uses default v2 semantics. jsonv2.Marshal(v) uses default v2 semantics. All new usages of "json" in Go should use the v2 package, but the v1 package will forever remain supported.
Registry
-
Source
- Documentation
- JSON
- codemeta.json
purl: pkg:golang/github.com/quic-go/json
License: BSD-3-Clause
Latest release: 11 days ago
Namespace: github.com/quic-go
Last synced: 11 days ago