Source file src/encoding/json/v2/doc.go
1 // Copyright 2020 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 //go:build goexperiment.jsonv2 6 7 // Package json implements semantic processing of JSON as specified in RFC 8259. 8 // JSON is a simple data interchange format that can represent 9 // primitive data types such as booleans, strings, and numbers, 10 // in addition to structured data types such as objects and arrays. 11 // 12 // This package (encoding/json/v2) is experimental, 13 // and not subject to the Go 1 compatibility promise. 14 // It only exists when building with the GOEXPERIMENT=jsonv2 environment variable set. 15 // Most users should use [encoding/json]. 16 // 17 // [Marshal] and [Unmarshal] encode and decode Go values 18 // to/from JSON text contained within a []byte. 19 // [MarshalWrite] and [UnmarshalRead] operate on JSON text 20 // by writing to or reading from an [io.Writer] or [io.Reader]. 21 // [MarshalEncode] and [UnmarshalDecode] operate on JSON text 22 // by encoding to or decoding from a [jsontext.Encoder] or [jsontext.Decoder]. 23 // [Options] may be passed to each of the marshal or unmarshal functions 24 // to configure the semantic behavior of marshaling and unmarshaling 25 // (i.e., alter how JSON data is understood as Go data and vice versa). 26 // [jsontext.Options] may also be passed to the marshal or unmarshal functions 27 // to configure the syntactic behavior of encoding or decoding. 28 // 29 // The data types of JSON are mapped to/from the data types of Go based on 30 // the closest logical equivalent between the two type systems. For example, 31 // a JSON boolean corresponds with a Go bool, 32 // a JSON string corresponds with a Go string, 33 // a JSON number corresponds with a Go int, uint or float, 34 // a JSON array corresponds with a Go slice or array, and 35 // a JSON object corresponds with a Go struct or map. 36 // See the documentation on [Marshal] and [Unmarshal] for a comprehensive list 37 // of how the JSON and Go type systems correspond. 38 // 39 // Arbitrary Go types can customize their JSON representation by implementing 40 // [Marshaler], [MarshalerTo], [Unmarshaler], or [UnmarshalerFrom]. 41 // This provides authors of Go types with control over how their types are 42 // serialized as JSON. Alternatively, users can implement functions that match 43 // [MarshalFunc], [MarshalToFunc], [UnmarshalFunc], or [UnmarshalFromFunc] 44 // to specify the JSON representation for arbitrary types. 45 // This provides callers of JSON functionality with control over 46 // how any arbitrary type is serialized as JSON. 47 // 48 // # JSON Representation of Go structs 49 // 50 // A Go struct is naturally represented as a JSON object, 51 // where each Go struct field corresponds with a JSON object member. 52 // When marshaling, all Go struct fields are recursively encoded in depth-first 53 // order as JSON object members except those that are ignored or omitted. 54 // When unmarshaling, JSON object members are recursively decoded 55 // into the corresponding Go struct fields. 56 // Object members that do not match any struct fields, 57 // also known as “unknown members”, are ignored by default or rejected 58 // if [RejectUnknownMembers] is specified. 59 // 60 // The representation of each struct field can be customized in the 61 // "json" struct field tag, where the tag is a comma separated list of options. 62 // As a special case, if the entire tag is `json:"-"`, 63 // then the field is ignored with regard to its JSON representation. 64 // Some options also have equivalent behavior controlled by a caller-specified [Options]. 65 // Field-specified options take precedence over caller-specified options. 66 // 67 // The first option is the JSON object name override for the Go struct field. 68 // If the name is not specified, then the Go struct field name 69 // is used as the JSON object name. JSON names containing commas or quotes, 70 // or names identical to "" or "-", can be specified using 71 // a single-quoted string literal, where the syntax is identical to 72 // the Go grammar for a double-quoted string literal, 73 // but instead uses single quotes as the delimiters. 74 // By default, unmarshaling uses case-sensitive matching to identify 75 // the Go struct field associated with a JSON object name. 76 // 77 // After the name, the following tag options are supported: 78 // 79 // - omitzero: When marshaling, the "omitzero" option specifies that 80 // the struct field should be omitted if the field value is zero 81 // as determined by the "IsZero() bool" method if present, 82 // otherwise based on whether the field is the zero Go value. 83 // This option has no effect when unmarshaling. 84 // 85 // - omitempty: When marshaling, the "omitempty" option specifies that 86 // the struct field should be omitted if the field value would have been 87 // encoded as a JSON null, empty string, empty object, or empty array. 88 // This option has no effect when unmarshaling. 89 // 90 // - string: The "string" option specifies that [StringifyNumbers] 91 // be set when marshaling or unmarshaling a struct field value. 92 // This causes numeric types to be encoded as a JSON number 93 // within a JSON string, and to be decoded from a JSON string 94 // containing the JSON number without any surrounding whitespace. 95 // This extra level of encoding is often necessary since 96 // many JSON parsers cannot precisely represent 64-bit integers. 97 // 98 // - case: When unmarshaling, the "case" option specifies how 99 // JSON object names are matched with the JSON name for Go struct fields. 100 // The option is a key-value pair specified as "case:value" where 101 // the value must either be 'ignore' or 'strict'. 102 // The 'ignore' value specifies that matching is case-insensitive 103 // where dashes and underscores are also ignored. If multiple fields match, 104 // the first declared field in breadth-first order takes precedence. 105 // The 'strict' value specifies that matching is case-sensitive. 106 // This takes precedence over the [MatchCaseInsensitiveNames] option. 107 // 108 // - inline: The "inline" option specifies that 109 // the JSON representable content of this field type is to be promoted 110 // as if they were specified in the parent struct. 111 // It is the JSON equivalent of Go struct embedding. 112 // A Go embedded field is implicitly inlined unless an explicit JSON name 113 // is specified. The inlined field must be a Go struct 114 // (that does not implement any JSON methods), [jsontext.Value], 115 // map[~string]T, or an unnamed pointer to such types. When marshaling, 116 // inlined fields from a pointer type are omitted if it is nil. 117 // Inlined fields of type [jsontext.Value] and map[~string]T are called 118 // “inlined fallbacks” as they can represent all possible 119 // JSON object members not directly handled by the parent struct. 120 // Only one inlined fallback field may be specified in a struct, 121 // while many non-fallback fields may be specified. This option 122 // must not be specified with any other option (including the JSON name). 123 // 124 // - unknown: The "unknown" option is a specialized variant 125 // of the inlined fallback to indicate that this Go struct field 126 // contains any number of unknown JSON object members. The field type must 127 // be a [jsontext.Value], map[~string]T, or an unnamed pointer to such types. 128 // If [DiscardUnknownMembers] is specified when marshaling, 129 // the contents of this field are ignored. 130 // If [RejectUnknownMembers] is specified when unmarshaling, 131 // any unknown object members are rejected regardless of whether 132 // an inlined fallback with the "unknown" option exists. This option 133 // must not be specified with any other option (including the JSON name). 134 // 135 // - format: The "format" option specifies a format flag 136 // used to specialize the formatting of the field value. 137 // The option is a key-value pair specified as "format:value" where 138 // the value must be either a literal consisting of letters and numbers 139 // (e.g., "format:RFC3339") or a single-quoted string literal 140 // (e.g., "format:'2006-01-02'"). The interpretation of the format flag 141 // is determined by the struct field type. 142 // 143 // The "omitzero" and "omitempty" options are mostly semantically identical. 144 // The former is defined in terms of the Go type system, 145 // while the latter in terms of the JSON type system. 146 // Consequently they behave differently in some circumstances. 147 // For example, only a nil slice or map is omitted under "omitzero", while 148 // an empty slice or map is omitted under "omitempty" regardless of nilness. 149 // The "omitzero" option is useful for types with a well-defined zero value 150 // (e.g., [net/netip.Addr]) or have an IsZero method (e.g., [time.Time.IsZero]). 151 // 152 // Every Go struct corresponds to a list of JSON representable fields 153 // which is constructed by performing a breadth-first search over 154 // all struct fields (excluding unexported or ignored fields), 155 // where the search recursively descends into inlined structs. 156 // The set of non-inlined fields in a struct must have unique JSON names. 157 // If multiple fields all have the same JSON name, then the one 158 // at shallowest depth takes precedence and the other fields at deeper depths 159 // are excluded from the list of JSON representable fields. 160 // If multiple fields at the shallowest depth have the same JSON name, 161 // but exactly one is explicitly tagged with a JSON name, 162 // then that field takes precedence and all others are excluded from the list. 163 // This is analogous to Go visibility rules for struct field selection 164 // with embedded struct types. 165 // 166 // Marshaling or unmarshaling a non-empty struct 167 // without any JSON representable fields results in a [SemanticError]. 168 // Unexported fields must not have any `json` tags except for `json:"-"`. 169 package json 170 171 // requireKeyedLiterals can be embedded in a struct to require keyed literals. 172 type requireKeyedLiterals struct{} 173 174 // nonComparable can be embedded in a struct to prevent comparability. 175 type nonComparable [0]func() 176