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