RFC 7158
The JavaScript Object Notation (JSON) Data Interchange Format
RFC 7158 📜✨
Internet Engineering Task Force (IETF) 💖 Request for Comments: 7158 🎀 Category: Standards Track 🌸 ISSN: 2070-1721 🦋
Okay bestie, the author is T. Bray, Ed. from Google, Inc. 💅 It was published in March 2013 ✨ and it's a Standards Track doc, so this is the real deal, not just a suggestion 👑. It obsoletes RFC 4627 💀 (so 4627 is officially retired, RIP 🕯️) and it also updates RFC 4627 🔥, which we'll get into in Section 1.2.
The title is 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, and it defines a small set of formatting rules so structured data can be represented in a portable way 🎀.
This document cleans up inconsistencies with other JSON specs, fixes some spec errors, and gives interoperability advice based on real-world experience 🫶.
Status of This Memo 🌸
This is an Internet Standards Track document 💖.
It's a product of the Internet Engineering Task Force (IETF) and represents the consensus of the IETF community 👑. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 💅. If you want more info on Internet Standards, check out Section 2 of RFC 5741 ✨.
For the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7158 🦋.
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) as they stand on the publication date 📜. Read these carefully, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes 🔥.
This document may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008 🍓. The person(s) controlling the copyright in some of that material may not have given the IETF Trust the right to allow modifications outside the IETF Standards Process 💀. So unless you get an adequate license from whoever controls that copyright, this document can't be modified outside the IETF Standards Process, and derivative works can't be made outside it either. The one exceptions are formatting it for publication as an RFC or translating it into languages other than English 🌸.
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 .................................151. Introduction 🌸
JSON, short for JavaScript Object Notation, is a text format for serializing structured data 💖. It's 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 points to the latest version of Unicode rather than a specific release. Future changes to the UNICODE specification are not expected to affect 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 🍓.
The terms "object" and "array" come from JavaScript conventions 🧚.
JSON's design goals were 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 🌸
Since RFC 4627 came out, JSON has gotten super widely used 🌍. That experience has shown some patterns that, while allowed by its specifications, have caused interoperability problems 💀.
A few errata have also been reported (see RFC Errata IDs 607 [Err607] and 3607 [Err3607]) 🙈.
So this document aims to apply those errata, remove inconsistencies with other JSON specifications, and call out 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. Certain earlier JSON specs required a JSON text to be an object or an array. Implementations that generate only objects or arrays wherever a JSON text is called for will still be interoperable, since all implementations will accept these as conforming JSON texts 💅.
JSON-text = ws value wsThese 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 ; , commaInsignificant 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 return3. Values 💅
A JSON value MUST be an object, array, number, or string, or one of the following three literal names 🔥:
false null trueThe 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 ; true4. Objects 🫶
An object is written as a pair of curly brackets surrounding zero or more name/value pairs (also called members) 🦋. A name is a string ✨. A single colon comes after each name to separate it from its value 🌸. A single comma separates a value from the name that follows it 🍓. The names within an object SHOULD be unique 💜.
object = begin-object [ member *( value-separator member ) ]
end-object
member = string name-separator valueAn object whose names are all unique is interoperable, meaning every software implementation that receives it will agree on the name-value mappings 👑. When the names within an object are not unique, how software receiving that object behaves is unpredictable 💀. Many implementations report only the last name/value pair. Other implementations report an error or fail to parse the object. Some implementations report all of the name/value pairs, duplicates included 🙈.
JSON parsing libraries have been observed to differ on whether they expose the ordering of object members to calling software 🧚. Implementations whose behavior doesn't depend on member ordering will be interoperable, because these differences won't affect them 🌈.
5. Arrays 🍓
An array is written as square brackets surrounding zero or more values (also called elements) 🎀. Elements are separated by commas 💖.
array = begin-array [ value *( value-separator value ) ] end-arrayThere is no requirement that the values in an array be of the same type 🌸✨.
6. Numbers 🔢✨
okay so numbers in JSON are giving the same energy as most programming languages 💅 they're written in base 10 using decimal digits 🍓 a number has an integer part that can start with an optional minus sign 😤 and then it can also have a fraction part and/or an exponent part, bc why not 🦋 leading zeros are not allowed 🙅♀️
a fraction part is a decimal point followed by one or more digits 🌸
an exponent part starts with the letter E, upper or lower case 💜 it can be followed by a plus or minus sign, and then you need one or more digits after the E and the optional sign ✨
numeric values that can't be written in the grammar below (like 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 ; 0this spec lets implementations set limits on the range and precision of the numbers they accept 🎀 software that implements IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is generally available and widely used, so good interoperability can be achieved by implementations that expect no more precision or range than those provide. in other words, implementations will approximate JSON numbers within the expected precision 🧚
⚠️ a JSON number like1E400or3.141592653589793238462643383279may cause interop drama 😭 it suggests the software that made it expects the receiving software to have way more numeric magnitude and precision than is widely available. not it, bestie 💀
when that kind of software is used, numbers that are integers and fall in the range [-(2**53)+1, (2**53)-1] are interoperable, because implementations will agree exactly on their numeric values 🌈 that's the sweet spot 👑
7. Strings 🎀
strings are similar to the conventions used in the C family of programming languages 💖 a string begins and ends with quotation marks. all Unicode characters can go inside the quotation marks, except for the characters that must be escaped: the quotation mark, the 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), it can be written as a six-character sequence: a reverse solidus, then the lowercase letter u, then four hexadecimal digits that encode the code point. the hex letters A through F can be upper or lower case ✨ so for example, a string with just one reverse solidus character can be written as "\u005C" 💅
there are also two-character escape sequences for some popular characters 🍓 so a string with just one reverse solidus can be written more compactly as "\\" 🙌
to escape an extended character that is not in the Basic Multilingual Plane, you write it as a 12-character sequence that encodes the UTF-16 surrogate pair 🌸 for example, a string with only the G clef character (U+1D11E) can be written 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-10FFFF8. String and Character Issues 🧵
8.1. Character Encoding 🔤
JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32. the default is UTF-8, and JSON texts encoded in UTF-8 are interoperable in the sense that they'll be read successfully by the maximum number of implementations 💜 there are lots of implementations that can't read texts in other encodings (like UTF-16 and UTF-32), so no cap, UTF-8 is the move 🙌
Implementations MUST NOT add a byte order mark to the beginning of a JSON text 🚫 for the sake of interoperability, implementations that parse JSON texts MAY ignore the presence of a byte order mark instead of treating it as an error 🫧
8.2. Unicode Characters 🌍
when all the strings in a JSON text are made up entirely of Unicode characters [UNICODE] (however they're escaped), that JSON text is interoperable 💖 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 spec allows member names and string values to contain bit sequences that can't encode Unicode characters 😬 for example, "\uDEAD" (a single unpaired UTF-16 surrogate). this has been observed, for instance, 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 with such values is unpredictable. 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 convert the textual representation into sequences of Unicode code units and then compare them numerically, code unit by code unit, are interoperable in the sense that they'll 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 🙈
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 📏 it may set limits on the maximum depth of nesting 🪆 it may set limits on the range and precision of numbers 🔢 and it may set limits on the length and character contents of strings 🎀
10. Generators 🖨️
a JSON generator produces JSON text 💖 and the resulting text MUST strictly conform to the JSON grammar. no vibes-based JSON allowed 🙅♀️✨
11. IANA Considerations 📋
the MIME media type for JSON text is application/json 🎀 here's the whole registration, verbatim, bc it's a lot of fields 💅
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.
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
<iesg@ietf.org>
Intended usage: COMMON
Restrictions on usage: none
Author:
Douglas Crockford
<douglas@crockford.com>
Change controller:
IESG
<iesg@ietf.org>
Note: No "charset" parameter is defined for this registration.
Adding one really has no effect on compliant recipients.12. Security Considerations 🚨
🚨 okay bestie, this one is SERIOUS. generally, there are security issues with scripting languages 😱 JSON is a subset of JavaScript, but it excludes assignment and invocation 🛡️
since JSON's syntax is borrowed from JavaScript, it's possible to use that language's eval() function to parse JSON texts 💀 this generally constitutes an unacceptable security risk, because the text could contain executable code along with the data declarations 🙅♀️ the same consideration applies to using eval()-like functions in any other programming language where JSON texts conform to that language's syntax 🫠
13. Examples 🍭
here's 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 🌸
and here's a JSON array holding 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"
}
]and last but not least, three small JSON texts that contain only values ✨
"Hello world!"
42
true14. Contributors 🫶
RFC 4627 was written by Douglas Crockford 👑 this document was built by making a relatively small number of changes to that document, so the vast majority of the text here is his 💜 the main character of this whole spec is, iykyk 🙈
15. References 📚
15.1. Normative References 💎
[IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE
Standard 754, August 2008,
<http://grouper.ieee.org/groups/754/>.
[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",
<http://www.unicode.org/versions/latest/>.15.2. Informative References 🦋
[ECMA-262] Ecma International, "ECMAScript Language Specification
Edition 5.1", Standard ECMA-262, June 2011,
<http://www.ecma-international.org/publications/standards/
Ecma-262.htm>.
[ECMA-404] Ecma International, "The JSON Data Interchange Format",
Standard ECMA-404, October 2013,
<http://www.ecma-international.org/publications/standards/
Ecma-404.htm>.
[Err3607] RFC Errata, Errata ID 3607, RFC 3607,
<http://www.rfc-editor.org>.
[Err607] RFC Errata, Errata ID 607, RFC 607,
<http://www.rfc-editor.org>.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.Appendix A. Changes from RFC 4627 ✨
Okay so this section is basically the changelog for the whole doc, and honestly it's giving glow-up 🦋 It lists every change between this document and the text in RFC 4627, so if you're wondering "wait, what changed since last time?" this is where the tea is ☕.
- Changed the title and abstract of the document. 💅
- Changed the reference to [UNICODE] to be not version specific. 🌈
- Added a "Specifications of JSON" section. 📜
- Added an "Introduction to This Revision" section. 🎀
- Changed the definition of "JSON text" so that it can be any JSON value, removing the constraint that it be an object or array. 👑 This one is so iconic, a JSON text doesn't have to be an object or array anymore!!
- Added language about duplicate object member names, member ordering, and interoperability. 🫶
- Clarified the absence of a requirement that values in an array be of the same JSON type. 🧚 Arrays can be a mixed bag, bestie, no rules there.
- Applied erratum #607 from RFC 4627 to correctly align the artwork for the definition of "object". 🍓
- Changed "as sequences of digits" to "in the grammar below" in the "Numbers" section, and made base-10-ness explicit. 🔥
- Added language about number interoperability as a function of IEEE754, and added an IEEE754 reference. 🌸
- 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". 💜 That's the reorg arc, periodt.
- Changed guidance in the "Parsers" section to point out that implementations may set limits on the range "and precision" of numbers. 🦋
- Updated and tidied the "IANA Considerations" section. ✨
- Made a real "Security Considerations" section and lifted the text out of the previous "IANA Considerations" section. 🔒💖
- 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. 💀 Bye bye, that one.
- 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. ⚠️ eval() is not your friend, besties.
- Added a note to the "IANA Considerations" clarifying the absence of a "charset" parameter for the application/json media type. 🙈
- Changed "100" to 100 and added a boolean field, both in the first example. 🍓
- Added examples of JSON texts with simple values, neither objects nor arrays. 🌈
- Added a "Contributors" section crediting Douglas Crockford. 🫶 Shoutout to him, obsessed!
- Added a reference to RFC 4627. 📚
- 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 💌
📦 where this page comes from
- ietf: rfc7158 2014-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms