doc.go 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. // Copyright 2023 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 jsontext implements syntactic processing of JSON
  5. // as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785.
  6. // JSON is a simple data interchange format that can represent
  7. // primitive data types such as booleans, strings, and numbers,
  8. // in addition to structured data types such as objects and arrays.
  9. //
  10. // The [Encoder] and [Decoder] types are used to encode or decode
  11. // a stream of JSON tokens or values.
  12. //
  13. // # Tokens and Values
  14. //
  15. // A JSON token refers to the basic structural elements of JSON:
  16. //
  17. // - a JSON literal (i.e., null, true, or false)
  18. // - a JSON string (e.g., "hello, world!")
  19. // - a JSON number (e.g., 123.456)
  20. // - a start or end delimiter for a JSON object (i.e., '{' or '}')
  21. // - a start or end delimiter for a JSON array (i.e., '[' or ']')
  22. //
  23. // A JSON token is represented by the [Token] type in Go. Technically,
  24. // there are two additional structural characters (i.e., ':' and ','),
  25. // but there is no [Token] representation for them since their presence
  26. // can be inferred by the structure of the JSON grammar itself.
  27. // For example, there must always be an implicit colon between
  28. // the name and value of a JSON object member.
  29. //
  30. // A JSON value refers to a complete unit of JSON data:
  31. //
  32. // - a JSON literal, string, or number
  33. // - a JSON object (e.g., `{"name":"value"}`)
  34. // - a JSON array (e.g., `[1,2,3,]`)
  35. //
  36. // A JSON value is represented by the [Value] type in Go and is a []byte
  37. // containing the raw textual representation of the value. There is some overlap
  38. // between tokens and values as both contain literals, strings, and numbers.
  39. // However, only a value can represent the entirety of a JSON object or array.
  40. //
  41. // The [Encoder] and [Decoder] types contain methods to read or write the next
  42. // [Token] or [Value] in a sequence. They maintain a state machine to validate
  43. // whether the sequence of JSON tokens and/or values produces a valid JSON.
  44. // [Options] may be passed to the [NewEncoder] or [NewDecoder] constructors
  45. // to configure the syntactic behavior of encoding and decoding.
  46. //
  47. // # Terminology
  48. //
  49. // The terms "encode" and "decode" are used for syntactic functionality
  50. // that is concerned with processing JSON based on its grammar, and
  51. // the terms "marshal" and "unmarshal" are used for semantic functionality
  52. // that determines the meaning of JSON values as Go values and vice-versa.
  53. // This package (i.e., [jsontext]) deals with JSON at a syntactic layer,
  54. // while [encoding/json/v2] deals with JSON at a semantic layer.
  55. // The goal is to provide a clear distinction between functionality that
  56. // is purely concerned with encoding versus that of marshaling.
  57. // For example, one can directly encode a stream of JSON tokens without
  58. // needing to marshal a concrete Go value representing them.
  59. // Similarly, one can decode a stream of JSON tokens without
  60. // needing to unmarshal them into a concrete Go value.
  61. //
  62. // This package uses JSON terminology when discussing JSON, which may differ
  63. // from related concepts in Go or elsewhere in computing literature.
  64. //
  65. // - a JSON "object" refers to an unordered collection of name/value members.
  66. // - a JSON "array" refers to an ordered sequence of elements.
  67. // - a JSON "value" refers to either a literal (i.e., null, false, or true),
  68. // string, number, object, or array.
  69. //
  70. // See RFC 8259 for more information.
  71. //
  72. // # Specifications
  73. //
  74. // Relevant specifications include RFC 4627, RFC 7159, RFC 7493, RFC 8259,
  75. // and RFC 8785. Each RFC is generally a stricter subset of another RFC.
  76. // In increasing order of strictness:
  77. //
  78. // - RFC 4627 and RFC 7159 do not require (but recommend) the use of UTF-8
  79. // and also do not require (but recommend) that object names be unique.
  80. // - RFC 8259 requires the use of UTF-8,
  81. // but does not require (but recommends) that object names be unique.
  82. // - RFC 7493 requires the use of UTF-8
  83. // and also requires that object names be unique.
  84. // - RFC 8785 defines a canonical representation. It requires the use of UTF-8
  85. // and also requires that object names be unique and in a specific ordering.
  86. // It specifies exactly how strings and numbers must be formatted.
  87. //
  88. // The primary difference between RFC 4627 and RFC 7159 is that the former
  89. // restricted top-level values to only JSON objects and arrays, while
  90. // RFC 7159 and subsequent RFCs permit top-level values to additionally be
  91. // JSON nulls, booleans, strings, or numbers.
  92. //
  93. // By default, this package operates on RFC 7493, but can be configured
  94. // to operate according to the other RFC specifications.
  95. // RFC 7493 is a stricter subset of RFC 8259 and fully compliant with it.
  96. // In particular, it makes specific choices about behavior that RFC 8259
  97. // leaves as undefined in order to ensure greater interoperability.
  98. package jsontext
  99. // requireKeyedLiterals can be embedded in a struct to require keyed literals.
  100. type requireKeyedLiterals struct{}
  101. // nonComparable can be embedded in a struct to prevent comparability.
  102. type nonComparable [0]func()