From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc7158.txt | 899 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 899 insertions(+) create mode 100644 doc/rfc/rfc7158.txt (limited to 'doc/rfc/rfc7158.txt') diff --git a/doc/rfc/rfc7158.txt b/doc/rfc/rfc7158.txt new file mode 100644 index 0000000..db65484 --- /dev/null +++ b/doc/rfc/rfc7158.txt @@ -0,0 +1,899 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Bray, Ed. +Request for Comments: 7158 Google, Inc. +Obsoletes: 4627 March 2013 +Category: Standards Track +ISSN: 2070-1721 + + + The JavaScript Object Notation (JSON) Data Interchange Format + +Abstract + + JavaScript Object Notation (JSON) is a lightweight, text-based, + language-independent data interchange format. It was derived from + the ECMAScript Programming Language Standard. JSON defines a small + set of formatting rules for the portable representation of structured + data. + + This document removes inconsistencies with other specifications of + JSON, repairs specification errors, and offers experience-based + interoperability guidance. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7158. + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 1] + +RFC 7158 JSON March 2013 + + +Copyright Notice + + Copyright (c) 2013 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + + + + + + + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 2] + +RFC 7158 JSON March 2013 + + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Conventions Used in This Document ..........................4 + 1.2. Specifications of JSON .....................................4 + 1.3. Introduction to This Revision ..............................4 + 2. JSON Grammar ....................................................4 + 3. Values ..........................................................5 + 4. Objects .........................................................6 + 5. Arrays ..........................................................6 + 6. Numbers .........................................................6 + 7. Strings .........................................................8 + 8. String and Character Issues .....................................9 + 8.1. Character Encoding .........................................9 + 8.2. Unicode Characters .........................................9 + 8.3. String Comparison ..........................................9 + 9. Parsers ........................................................10 + 10. Generators ....................................................10 + 11. IANA Considerations ...........................................10 + 12. Security Considerations .......................................11 + 13. Examples ......................................................12 + 14. Contributors ..................................................13 + 15. References ....................................................13 + 15.1. Normative References .....................................13 + 15.2. Informative References ...................................13 + Appendix A. Changes from RFC 4627 .................................15 + +1. Introduction + + JavaScript Object Notation (JSON) is a text format for the + serialization of structured data. It is derived from the object + literals of JavaScript, as defined in the ECMAScript Programming + Language Standard, Third Edition [ECMA-262]. + + JSON can represent four primitive types (strings, numbers, booleans, + and null) and two structured types (objects and arrays). + + A string is a sequence of zero or more Unicode characters [UNICODE]. + Note that this citation references the latest version of Unicode + rather than a specific release. It is not expected that future + changes in the UNICODE specification will impact the syntax of JSON. + + An object is an unordered collection of zero or more name/value + pairs, where a name is a string and a value is a string, number, + boolean, null, object, or array. + + An array is an ordered sequence of zero or more values. + + + + +Bray Standards Track [Page 3] + +RFC 7158 JSON March 2013 + + + The terms "object" and "array" come from the conventions of + JavaScript. + + JSON's design goals were for it to be minimal, portable, textual, and + a subset of JavaScript. + +1.1. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The grammatical rules in this document are to be interpreted as + described in [RFC5234]. + +1.2. Specifications of JSON + + This document updates [RFC4627], which describes JSON and registers + the media type "application/json". + + A description of JSON in ECMAScript terms appears in Version 5.1 of + the ECMAScript specification [ECMA-262], Section 15.12. JSON is also + described in [ECMA-404]. + + All of the specifications of JSON syntax agree on the syntactic + elements of the language. + +1.3. Introduction to This Revision + + In the years since the publication of RFC 4627, JSON has found very + wide use. This experience has revealed certain patterns, which, + while allowed by its specifications, have caused interoperability + problems. + + Also, a small number of errata have been reported (see RFC Errata IDs + 607 [Err607] and 3607 [Err3607]). + + This document's goal is to apply the errata, remove inconsistencies + with other specifications of JSON, and highlight practices that can + lead to interoperability problems. + +2. JSON Grammar + + A JSON text is a sequence of tokens. The set of tokens includes six + structural characters, strings, numbers, and three literal names. + + A JSON text is a serialized value. Note that certain previous + specifications of JSON constrained a JSON text to be an object or an + + + +Bray Standards Track [Page 4] + +RFC 7158 JSON March 2013 + + + array. Implementations that generate only objects or arrays where a + JSON text is called for will be interoperable in the sense that all + implementations will accept these as conforming JSON texts. + + JSON-text = ws value ws + + These are the six structural characters: + + begin-array = ws %x5B ws ; [ left square bracket + + begin-object = ws %x7B ws ; { left curly bracket + + end-array = ws %x5D ws ; ] right square bracket + + end-object = ws %x7D ws ; } right curly bracket + + name-separator = ws %x3A ws ; : colon + + value-separator = ws %x2C ws ; , comma + + Insignificant whitespace is allowed before or after any of the six + structural characters. + + ws = *( + %x20 / ; Space + %x09 / ; Horizontal tab + %x0A / ; Line feed or New line + %x0D ) ; Carriage return + +3. Values + + A JSON value MUST be an object, array, number, or string, or one of + the following three literal names: + + false null true + + The literal names MUST be lowercase. No other literal names are + allowed. + + value = false / null / true / object / array / number / string + + false = %x66.61.6c.73.65 ; false + + null = %x6e.75.6c.6c ; null + + true = %x74.72.75.65 ; true + + + + + +Bray Standards Track [Page 5] + +RFC 7158 JSON March 2013 + + +4. Objects + + An object structure is represented as a pair of curly brackets + surrounding zero or more name/value pairs (or members). A name is a + string. A single colon comes after each name, separating the name + from the value. A single comma separates a value from a following + name. The names within an object SHOULD be unique. + + object = begin-object [ member *( value-separator member ) ] + end-object + + member = string name-separator value + + An object whose names are all unique is interoperable in the sense + that all software implementations receiving that object will agree on + the name-value mappings. When the names within an object are not + unique, the behavior of software that receives such an object is + unpredictable. Many implementations report the last name/value pair + only. Other implementations report an error or fail to parse the + object, and some implementations report all of the name/value pairs, + including duplicates. + + JSON parsing libraries have been observed to differ as to whether or + not they make the ordering of object members visible to calling + software. Implementations whose behavior does not depend on member + ordering will be interoperable in the sense that they will not be + affected by these differences. + +5. Arrays + + An array structure is represented as square brackets surrounding zero + or more values (or elements). Elements are separated by commas. + + array = begin-array [ value *( value-separator value ) ] end-array + + There is no requirement that the values in an array be of the same + type. + +6. Numbers + + The representation of numbers is similar to that used in most + programming languages. A number is represented in base 10 using + decimal digits. It contains an integer component that may be + prefixed with an optional minus sign, which may be followed by a + fraction part and/or an exponent part. Leading zeros are not + allowed. + + A fraction part is a decimal point followed by one or more digits. + + + +Bray Standards Track [Page 6] + +RFC 7158 JSON March 2013 + + + An exponent part begins with the letter E in upper or lower case, + which may be followed by a plus or minus sign. The E and optional + sign are followed by one or more digits. + + Numeric values that cannot be represented in the grammar below (such + as Infinity and NaN) are not permitted. + + number = [ minus ] int [ frac ] [ exp ] + + decimal-point = %x2E ; . + + digit1-9 = %x31-39 ; 1-9 + + e = %x65 / %x45 ; e E + + exp = e [ minus / plus ] 1*DIGIT + + frac = decimal-point 1*DIGIT + + int = zero / ( digit1-9 *DIGIT ) + + minus = %x2D ; - + + plus = %x2B ; + + + zero = %x30 ; 0 + + This specification allows implementations to set limits on the range + and precision of numbers accepted. Since software that implements + IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is + generally available and widely used, good interoperability can be + achieved by implementations that expect no more precision or range + than these provide, in the sense that implementations will + approximate JSON numbers within the expected precision. A JSON + number such as 1E400 or 3.141592653589793238462643383279 may indicate + potential interoperability problems, since it suggests that the + software that created it expects receiving software to have greater + capabilities for numeric magnitude and precision than is widely + available. + + Note that when such software is used, numbers that are integers and + are in the range [-(2**53)+1, (2**53)-1] are interoperable in the + sense that implementations will agree exactly on their numeric + values. + + + + + + + +Bray Standards Track [Page 7] + +RFC 7158 JSON March 2013 + + +7. Strings + + The representation of strings is similar to conventions used in the C + family of programming languages. A string begins and ends with + quotation marks. All Unicode characters may be placed within the + quotation marks, except for the characters that must be escaped: + quotation mark, reverse solidus, and the control characters (U+0000 + through U+001F). + + Any character may be escaped. If the character is in the Basic + Multilingual Plane (U+0000 through U+FFFF), then it may be + represented as a six-character sequence: a reverse solidus, followed + by the lowercase letter u, followed by four hexadecimal digits that + encode the character's code point. The hexadecimal letters A though + F can be upper or lower case. So, for example, a string containing + only a single reverse solidus character may be represented as + "\u005C". + + Alternatively, there are two-character sequence escape + representations of some popular characters. So, for example, a + string containing only a single reverse solidus character may be + represented more compactly as "\\". + + To escape an extended character that is not in the Basic Multilingual + Plane, the character is represented as a 12-character sequence, + encoding the UTF-16 surrogate pair. So, for example, a string + containing only the G clef character (U+1D11E) may be represented as + "\uD834\uDD1E". + + string = quotation-mark *char quotation-mark + + char = unescaped / + escape ( + %x22 / ; " quotation mark U+0022 + %x5C / ; \ reverse solidus U+005C + %x2F / ; / solidus U+002F + %x62 / ; b backspace U+0008 + %x66 / ; f form feed U+000C + %x6E / ; n line feed U+000A + %x72 / ; r carriage return U+000D + %x74 / ; t tab U+0009 + %x75 4HEXDIG ) ; uXXXX U+XXXX + + escape = %x5C ; \ + + quotation-mark = %x22 ; " + + unescaped = %x20-21 / %x23-5B / %x5D-10FFFF + + + +Bray Standards Track [Page 8] + +RFC 7158 JSON March 2013 + + +8. String and Character Issues + +8.1. Character Encoding + + JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32. The default + encoding is UTF-8, and JSON texts that are encoded in UTF-8 are + interoperable in the sense that they will be read successfully by the + maximum number of implementations; there are many implementations + that cannot successfully read texts in other encodings (such as + UTF-16 and UTF-32). + + Implementations MUST NOT add a byte order mark to the beginning of a + JSON text. In the interests of interoperability, implementations + that parse JSON texts MAY ignore the presence of a byte order mark + rather than treating it as an error. + +8.2. Unicode Characters + + When all the strings represented in a JSON text are composed entirely + of Unicode characters [UNICODE] (however escaped), then that JSON + text is interoperable in the sense that all software implementations + that parse it will agree on the contents of names and of string + values in objects and arrays. + + However, the ABNF in this specification allows member names and + string values to contain bit sequences that cannot encode Unicode + characters; for example, "\uDEAD" (a single unpaired UTF-16 + surrogate). Instances of this have been observed, for example, when + a library truncates a UTF-16 string without checking whether the + truncation split a surrogate pair. The behavior of software that + receives JSON texts containing such values is unpredictable; for + example, implementations might return different values for the length + of a string value or even suffer fatal runtime exceptions. + +8.3. String Comparison + + Software implementations are typically required to test names of + object members for equality. Implementations that transform the + textual representation into sequences of Unicode code units and then + perform the comparison numerically, code unit by code unit, are + interoperable in the sense that implementations will agree in all + cases on equality or inequality of two strings. For example, + implementations that compare strings with escaped characters + unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not + equal. + + + + + + +Bray Standards Track [Page 9] + +RFC 7158 JSON March 2013 + + +9. Parsers + + A JSON parser transforms a JSON text into another representation. A + JSON parser MUST accept all texts that conform to the JSON grammar. + A JSON parser MAY accept non-JSON forms or extensions. + + An implementation may set limits on the size of texts that it + accepts. An implementation may set limits on the maximum depth of + nesting. An implementation may set limits on the range and precision + of numbers. An implementation may set limits on the length and + character contents of strings. + +10. Generators + + A JSON generator produces JSON text. The resulting text MUST + strictly conform to the JSON grammar. + +11. IANA Considerations + + The MIME media type for JSON text is application/json. + + Type name: application + + Subtype name: json + + Required parameters: n/a + + Optional parameters: n/a + + Encoding considerations: binary + + Security considerations: See [RFC7158], Section 12. + + Interoperability considerations: Described in [RFC7158] + + Published specification: [RFC7158] + + Applications that use this media type: + JSON has been used to exchange data between applications written + in all of these programming languages: ActionScript, C, C#, + Clojure, ColdFusion, Common Lisp, E, Erlang, Go, Java, JavaScript, + Lua, Objective CAML, Perl, PHP, Python, Rebol, Ruby, Scala, and + Scheme. + + + + + + + + +Bray Standards Track [Page 10] + +RFC 7158 JSON March 2013 + + + Additional information: + Magic number(s): n/a + File extension(s): .json + Macintosh file type code(s): TEXT + + Person & email address to contact for further information: + IESG + + + Intended usage: COMMON + + Restrictions on usage: none + + Author: + Douglas Crockford + + + Change controller: + IESG + + + Note: No "charset" parameter is defined for this registration. + Adding one really has no effect on compliant recipients. + +12. Security Considerations + + Generally, there are security issues with scripting languages. JSON + is a subset of JavaScript but excludes assignment and invocation. + + Since JSON's syntax is borrowed from JavaScript, it is possible to + use that language's "eval()" function to parse JSON texts. This + generally constitutes an unacceptable security risk, since the text + could contain executable code along with data declarations. The same + consideration applies to the use of eval()-like functions in any + other programming language in which JSON texts conform to that + language's syntax. + + + + + + + + + + + + + + + +Bray Standards Track [Page 11] + +RFC 7158 JSON March 2013 + + +13. Examples + + This is a JSON object: + + { + "Image": { + "Width": 800, + "Height": 600, + "Title": "View from 15th Floor", + "Thumbnail": { + "Url": "http://www.example.com/image/481989943", + "Height": 125, + "Width": 100 + }, + "Animated" : false, + "IDs": [116, 943, 234, 38793] + } + } + + Its Image member is an object whose Thumbnail member is an object and + whose IDs member is an array of numbers. + + This is a JSON array containing two objects: + + [ + { + "precision": "zip", + "Latitude": 37.7668, + "Longitude": -122.3959, + "Address": "", + "City": "SAN FRANCISCO", + "State": "CA", + "Zip": "94107", + "Country": "US" + }, + { + "precision": "zip", + "Latitude": 37.371991, + "Longitude": -122.026020, + "Address": "", + "City": "SUNNYVALE", + "State": "CA", + "Zip": "94085", + "Country": "US" + } + ] + + + + + +Bray Standards Track [Page 12] + +RFC 7158 JSON March 2013 + + + Here are three small JSON texts containing only values: + + "Hello world!" + + 42 + + true + +14. Contributors + + RFC 4627 was written by Douglas Crockford. This document was + constructed by making a relatively small number of changes to that + document; thus, the vast majority of the text here is his. + +15. References + +15.1. Normative References + + [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE + Standard 754, August 2008, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [UNICODE] The Unicode Consortium, "The Unicode Standard", + . + +15.2. Informative References + + [ECMA-262] Ecma International, "ECMAScript Language Specification + Edition 5.1", Standard ECMA-262, June 2011, + . + + [ECMA-404] Ecma International, "The JSON Data Interchange Format", + Standard ECMA-404, October 2013, + . + + [Err3607] RFC Errata, Errata ID 3607, RFC 3607, + . + + + + + + +Bray Standards Track [Page 13] + +RFC 7158 JSON March 2013 + + + [Err607] RFC Errata, Errata ID 607, RFC 607, + . + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, July 2006. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 14] + +RFC 7158 JSON March 2013 + + +Appendix A. Changes from RFC 4627 + + This section lists changes between this document and the text in RFC + 4627. + + o Changed the title and abstract of the document. + + o Changed the reference to [UNICODE] to be not version specific. + + o Added a "Specifications of JSON" section. + + o Added an "Introduction to This Revision" section. + + o Changed the definition of "JSON text" so that it can be any JSON + value, removing the constraint that it be an object or array. + + o Added language about duplicate object member names, member + ordering, and interoperability. + + o Clarified the absence of a requirement that values in an array be + of the same JSON type. + + o Applied erratum #607 from RFC 4627 to correctly align the artwork + for the definition of "object". + + o Changed "as sequences of digits" to "in the grammar below" in the + "Numbers" section, and made base-10-ness explicit. + + o Added language about number interoperability as a function of + IEEE754, and added an IEEE754 reference. + + o Added language about interoperability and Unicode characters and + about string comparisons. To do this, turned the old "Encoding" + section into a "String and Character Issues" section, with three + subsections: "Character Encoding", "Unicode Characters", and + "String Comparison". + + o Changed guidance in the "Parsers" section to point out that + implementations may set limits on the range "and precision" of + numbers. + + o Updated and tidied the "IANA Considerations" section. + + o Made a real "Security Considerations" section and lifted the text + out of the previous "IANA Considerations" section. + + + + + + +Bray Standards Track [Page 15] + +RFC 7158 JSON March 2013 + + + o Applied erratum #3607 from RFC 4627 by removing the security + consideration that begins "A JSON text can be safely passed" and + the JavaScript code that went with that consideration. + + o Added a note to the "Security Considerations" section pointing out + the risks of using the "eval()" function in JavaScript or any + other language in which JSON texts conform to that language's + syntax. + + o Added a note to the "IANA Considerations" clarifying the absence + of a "charset" parameter for the application/json media type. + + o Changed "100" to 100 and added a boolean field, both in the first + example. + + o Added examples of JSON texts with simple values, neither objects + nor arrays. + + o Added a "Contributors" section crediting Douglas Crockford. + + o Added a reference to RFC 4627. + + o Moved the ECMAScript reference from Normative to Informative and + updated it to reference ECMAScript 5.1, and added a reference to + ECMA 404. + +Author's Address + + Tim Bray (editor) + Google, Inc. + + EMail: tbray@textuality.com + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 16] + -- cgit v1.2.3