RFC 7159
The JavaScript Object Notation (JSON) Data Interchange Format
RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format 💖
okay bestie, let's talk about JSON 🎀 This one is RFC 7159, written by T. Bray (Ed.) at Google, Inc. and published in March 2014 🌸. It's a Standards Track document, so it's an official Internet standard, not just a suggestion lol 💅. It obsoletes RFC 4627 and RFC 7158, which means those older versions are replaced by this one 👑. It also updates RFC 4627, meaning it adds to and fixes that earlier spec 🔥. The ISSN is 2070-1721 ✨.
Internet Engineering Task Force (IETF) T. Bray, Ed.
Request for Comments: 7159 Google, Inc.
Obsoletes: 4627, 7158 March 2014
Category: Standards Track
ISSN: 2070-1721Abstract ✨
JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format 🦋 It came from the ECMAScript Programming Language Standard, and it has a small set of formatting rules for sending structured data around in a portable way 💜
This document cleans up inconsistencies with other JSON specifications, fixes errors in the spec, and gives interoperability advice based on real-world experience 🫶
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, received public review, and was approved for publication by the Internet Engineering Steering Group (IESG). More info on Internet Standards is in Section 2 of RFC 5741 ✨
For the current status of this document, any errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc7159 🧚
Copyright Notice 🔥
Copyright (c) 2014 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 were on the date this document was published. Please read these carefully, because they spell out your rights and restrictions. Code Components taken from this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come with no 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 people who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. So, unless you get a proper license from those copyright holders, 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. The 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 🦋
JavaScript Object Notation (JSON) 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]. The citation points to the latest version of Unicode rather than one specific release. Future changes to Unicode aren't expected to affect JSON's syntax 💅
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 words "object" and "array" come from JavaScript conventions 🔥
JSON was designed to be minimal, portable, textual, and a subset of JavaScript. Main character energy 👑
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 grammar 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 is in Version 5.1 of the ECMAScript specification [ECMA-262], Section 15.12. JSON is also described in [ECMA-404] ✨
All of the JSON syntax specifications agree on the syntactic elements of the language 🌈
1.3. Introduction to This Revision 🔥
Since RFC 4627 came out, JSON has gotten SO widely used 😭 That experience showed some patterns that are allowed by the specs but still cause interoperability problems 💀
A small number of errata have also been reported (see RFC Errata IDs 607 [Err607] and 3607 [Err3607]) 🙈
The goal of this document is 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 token set includes six structural characters, strings, numbers, and three literal names 💅
A JSON text is a serialized value. Some earlier JSON specs required a JSON text to be an object or an array. Implementations that only generate objects or arrays where a JSON text is called for will still be interoperable, because every implementation will accept those 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. Not me being picky, just being precise 💅
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 (called members). A name is a string 🧚 A single colon comes after each name to separate it from its value, and 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, in the sense that every software implementation receiving that object will agree on the name-value mappings ✨ When the names inside an object aren't unique, the behavior of software that receives it is unpredictable 💀 Lots of implementations only report the last name/value pair. Others report an error or fail to parse the object, and some report every name/value pair, duplicates included 😭
JSON parsing libraries have been seen 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 (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. Mixing types is totally fine 🔥
okay that's part one, bestie 🫶 more to come in the next part 💅✨
6. Numbers ✨
okay so numbers in JSON are giving "familiar from every other language" 💅 They're written in base 10 using decimal digits. A number can have an integer part, which can start with an optional minus sign 🫶 Then it can have a fraction part and/or an exponent part. Leading zeros are not allowed, so 007 is a no from me 🙅♀️
A fraction part is a decimal point followed by one or more digits 🦋
An exponent part starts with the letter E, in upper or lower case ✨ It can be followed by a plus or minus sign, and then one or more digits.
Numeric values that can't be represented in the grammar below, like Infinity and NaN, are not permitted 💀 no cap, those are not coming to the JSON party.
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 numbers they accept 💜 Since software that implements IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is everywhere, good interoperability is achievable if implementations don't expect more precision or range than those provide. Basically, they'll approximate JSON numbers within the expected precision 🌸 A JSON number like 1E400 or 3.141592653589793238462643383279 may signal interop problems, because it suggests the software that made it expects the receiver to handle more magnitude and precision than is widely available 😭
When that kind of software is used, integers in the range [-(253)+1, (253)-1] are interoperable, meaning implementations will agree exactly on their numeric values ✨ main character integers 👑
7. Strings 🎀
strings are giving C family vibes 💖 A string begins and ends with quotation marks. Basically all Unicode characters can go inside the quotes, except 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), you can write it as a six-character sequence: a reverse solidus, then the lowercase letter u, then four hexadecimal digits for the character's code point. The hex letters A through F can be upper or lower case. So a string with only one reverse solidus character can be written as "\u005C" 🫶
There are also two-character escape sequences for some popular characters, which is the compact option 🍓 So that same single reverse solidus string can be written more compactly as "\\" ✨
To escape an extended character that's not in the Basic Multilingual Plane, you write 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 the most interoperable, since they'll be read successfully by the most implementations 🫶 There are loads of implementations that can't read texts in other encodings, like UTF-16 and UTF-32, so be warned bestie 😭
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 entirely of Unicode characters [UNICODE] (however they're escaped), that JSON text is interoperable 💖 All the software that parses it will agree on the contents of names and of string values in objects and arrays. iconic 👑
BUT (and it's a big but 😤) the ABNF in this spec allows member names and string values to contain bit sequences that can't encode Unicode characters. For example, "\uDEAD" is a single unpaired UTF-16 surrogate 💀 This has actually 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 values like this is unpredictable. Implementations might return different lengths for the same string value, or even suffer fatal runtime exceptions 😭 not the vibe.
8.3. String Comparison 🔥
Software implementations are typically required to test names of object members for equality 🧚 Implementations that turn the text into sequences of Unicode code units and then compare them numerically, code unit by code unit, are interoperable. They'll agree in all cases on whether two strings are equal or not 💜 For example, implementations that compare strings with escaped characters left unconverted may incorrectly decide that "a\\b" and "a\u005Cb" are not equal 🙈 two strings, one vibe, but the computer says no.
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. It may also 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. no wiggle room, periodt ✨
11. IANA Considerations 🍓
The MIME media type for JSON text is application/json 💖 Here's the registration template, verbatim:
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 [RFC7159], Section 12.
Interoperability considerations: Described in [RFC7159]
Published specification: [RFC7159]
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 💀
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 🚨 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. please do not eval your JSON, bestie 😭🚨
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 💖
Here's 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"
}
]And here are three small JSON texts that contain only values 🦋
"Hello world!"
42
true14. Contributors 🫶
RFC 4627 was written by Douglas Crockford 👑 This document was made by changing a relatively small number of things in that document, so the vast majority of the text here is still his, 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 part is the changelog 📜✨ it spills every change between this doc and RFC 4627 (the old JSON spec), and bestie, there's a lot of tea ☕💅
- 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. 🧚 it's giving freedom!
- 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. 🍓 mixing types in arrays is fine, no cap.
- 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". 🔤💜 the glow-up is real
- 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. 🔐 main character energy for this one!
- 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. 🙈
- 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. > ⚠️ bestie,
eval()is a whole danger zone, so read this one twice 💀 - Added a note to the "IANA Considerations" clarifying the absence of a "charset" parameter for the
application/jsonmedia 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. 👑 iconic credit, obviously.
- 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. 🌙 periodt, that's the whole changelog!
Author's Address 💌
Tim Bray (editor)
Google, Inc.
EMail: tbray@textuality.com📦 where this page comes from
- ietf: rfc7159 2014-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms