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