doc.go 9.4 KB

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