idnits 2.17.1 draft-ietf-json-rfc4627bis-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC4627, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 06, 2013) is 3822 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '116' on line 469 -- Looks like a reference, but probably isn't: '943' on line 469 -- Looks like a reference, but probably isn't: '234' on line 469 -- Looks like a reference, but probably isn't: '38793' on line 469 -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE754' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JSON Working Group T. Bray, Ed. 3 Internet-Draft Google, Inc. 4 Obsoletes: 4627 (if approved) November 06, 2013 5 Intended status: Standards Track 6 Expires: May 10, 2014 8 The JSON Data Interchange Format 9 draft-ietf-json-rfc4627bis-07 11 Abstract 13 JavaScript Object Notation (JSON) is a lightweight, text-based, 14 language-independent data interchange format. It was derived from 15 the ECMAScript Programming Language Standard. JSON defines a small 16 set of formatting rules for the portable representation of structured 17 data. 19 This document makes no changes to the definition of JSON; it repairs 20 specification errors and offers experience-based interoperability 21 guidance. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on May 10, 2014. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 59 1.2. Specifications of JSON . . . . . . . . . . . . . . . . . 3 60 1.3. Introduction to This Revision . . . . . . . . . . . . . . 4 61 2. JSON Grammar . . . . . . . . . . . . . . . . . . . . . . . . 4 62 3. Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 4. Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 6. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 8. String and Character Issues . . . . . . . . . . . . . . . . . 8 68 8.1. Encoding and Detection . . . . . . . . . . . . . . . . . 8 69 8.2. Unicode Characters . . . . . . . . . . . . . . . . . . . 8 70 8.3. String Comparison . . . . . . . . . . . . . . . . . . . . 9 71 9. Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 10. Generators . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 74 12. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 11 77 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 78 15.1. Normative References . . . . . . . . . . . . . . . . . . 12 79 15.2. Informative References . . . . . . . . . . . . . . . . . 12 80 Appendix A. Changes from RFC 4627 . . . . . . . . . . . . . . . 13 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 83 1. Introduction 85 JavaScript Object Notation (JSON) is a text format for the 86 serialization of structured data. It is derived from the object 87 literals of JavaScript, as defined in the ECMAScript Programming 88 Language Standard, Third Edition [ECMA-262]. 90 JSON can represent four primitive types (strings, numbers, booleans, 91 and null) and two structured types (objects and arrays). 93 A string is a sequence of zero or more Unicode characters [UNICODE]. 95 An object is an unordered collection of zero or more name/value 96 pairs, where a name is a string and a value is a string, number, 97 boolean, null, object, or array. 99 An array is an ordered sequence of zero or more values. 101 The terms "object" and "array" come from the conventions of 102 JavaScript. 104 JSON's design goals were for it to be minimal, portable, textual, and 105 a subset of JavaScript. 107 1.1. Conventions Used in This Document 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 111 document are to be interpreted as described in [RFC2119]. 113 The grammatical rules in this document are to be interpreted as 114 described in [RFC5234]. 116 1.2. Specifications of JSON 118 This document is an update of [RFC4627], which described JSON and 119 registered the Media Type "application/json". 121 A description of JSON in ECMAScript terms appears in version 5.1 of 122 the ECMAScript specification [ECMA-262], section 15.12. JSON is also 123 described in [ECMA-404]. ECMAscript 5.1 enumerates the differences 124 between JSON as described in that specification and in RFC4627. The 125 most significant is that ECMAScript 5.1 does not require a JSON Text 126 to be an Array or an Object; thus, for example, the following would 127 all be valid JSON texts in the ECMAScript context: 129 o "Hello world!" 131 o 42 133 o true 135 All of the specifications of JSON syntax agree on the syntactic 136 elements of the language. 138 1.3. Introduction to This Revision 140 In the years since the publication of RFC 4627, JSON has found very 141 wide use. This experience has revealed certain patterns which, while 142 allowed by its specifications, have caused interoperability problems. 144 Also, a small number of errata have been reported. 146 This revision does not change any of the rules of the specification; 147 all texts which were legal JSON remain so, and none which were not 148 JSON become JSON. The revision's goal is to fix the errata and 149 highlight practices which can lead to interoperability problems. 151 2. JSON Grammar 153 A JSON text is a sequence of tokens. The set of tokens includes six 154 structural characters, strings, numbers, and three literal names. 156 A JSON text is a serialized object or array. 158 JSON-text = object / array 160 These are the six structural characters: 162 begin-array = ws %x5B ws ; [ left square bracket 164 begin-object = ws %x7B ws ; { left curly bracket 166 end-array = ws %x5D ws ; ] right square bracket 168 end-object = ws %x7D ws ; } right curly bracket 170 name-separator = ws %x3A ws ; : colon 172 value-separator = ws %x2C ws ; , comma 174 Insignificant whitespace is allowed before or after any of the six 175 structural characters. 177 ws = *( 178 %x20 / ; Space 179 %x09 / ; Horizontal tab 180 %x0A / ; Line feed or New line 181 %x0D ) ; Carriage return 183 3. Values 185 A JSON value MUST be an object, array, number, or string, or one of 186 the following three literal names: 188 false null true 190 The literal names MUST be lowercase. No other literal names are 191 allowed. 193 value = false / null / true / object / array / number / string 195 false = %x66.61.6c.73.65 ; false 197 null = %x6e.75.6c.6c ; null 199 true = %x74.72.75.65 ; true 201 4. Objects 203 An object structure is represented as a pair of curly brackets 204 surrounding zero or more name/value pairs (or members). A name is a 205 string. A single colon comes after each name, separating the name 206 from the value. A single comma separates a value from a following 207 name. The names within an object SHOULD be unique. 209 object = begin-object [ member *( value-separator member ) ] 210 end-object 212 member = string name-separator value 214 An object whose names are all unique is interoperable in the sense 215 that all software implementations which receive that object will 216 agree on the name-value mappings. When the names within an object 217 are not unique, the behavior of software that receives such an object 218 is unpredictable. Many implementations report the last name/value 219 pair only; other implementations report an error or fail to parse the 220 object; other implementations report all of the name/value pairs, 221 including duplicates. 223 5. Arrays 225 An array structure is represented as square brackets surrounding zero 226 or more values (or elements). Elements are separated by commas. 228 array = begin-array [ value *( value-separator value ) ] end-array 230 6. Numbers 232 The representation of numbers is similar to that used in most 233 programming languages. A number contains an integer component that 234 may be prefixed with an optional minus sign, which may be followed by 235 a fraction part and/or an exponent part. 237 Octal and hex forms are not allowed. Leading zeros are not allowed. 239 A fraction part is a decimal point followed by one or more digits. 241 An exponent part begins with the letter E in upper or lowercase, 242 which may be followed by a plus or minus sign. The E and optional 243 sign are followed by one or more digits. 245 Numeric values that cannot be represented in the grammar below (such 246 as Infinity and NaN) are not permitted. 248 number = [ minus ] int [ frac ] [ exp ] 250 decimal-point = %x2E ; . 252 digit1-9 = %x31-39 ; 1-9 254 e = %x65 / %x45 ; e E 256 exp = e [ minus / plus ] 1*DIGIT 258 frac = decimal-point 1*DIGIT 260 int = zero / ( digit1-9 *DIGIT ) 262 minus = %x2D ; - 264 plus = %x2B ; + 266 zero = %x30 ; 0 268 This specification allows implementations to set limits on the range 269 and precision of numbers accepted. Since software which implements 270 IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is 271 generally available and widely used, good interoperability can be 272 achieved by implementations which expect no more precision or range 273 than these provide, in the sense that implementations will 274 approximate JSON numbers within the expected precision. A JSON 275 number such as 1E400 or 3.141592653589793238462643383279 may indicate 276 potential interoperability problems since it suggests that the 277 software which created it it expected greater magnitude or precision 278 than is widely available. 280 Note that when such software is used, numbers which are integers and 281 are in the range [-(2**53)+1, (2**53)-1] are interoperable in the 282 sense that implementations will agree exactly on their numeric 283 values. 285 7. Strings 287 The representation of strings is similar to conventions used in the C 288 family of programming languages. A string begins and ends with 289 quotation marks. All Unicode characters may be placed within the 290 quotation marks except for the characters that must be escaped: 291 quotation mark, reverse solidus, and the control characters (U+0000 292 through U+001F). 294 Any character may be escaped. If the character is in the Basic 295 Multilingual Plane (U+0000 through U+FFFF), then it may be 296 represented as a six-character sequence: a reverse solidus, followed 297 by the lowercase letter u, followed by four hexadecimal digits that 298 encode the character's code point. The hexadecimal letters A though 299 F can be upper or lowercase. So, for example, a string containing 300 only a single reverse solidus character may be represented as 301 "\u005C". 303 Alternatively, there are two-character sequence escape 304 representations of some popular characters. So, for example, a 305 string containing only a single reverse solidus character may be 306 represented more compactly as "\\". 308 To escape an extended character that is not in the Basic Multilingual 309 Plane, the character is represented as a twelve-character sequence, 310 encoding the UTF-16 surrogate pair. So, for example, a string 311 containing only the G clef character (U+1D11E) may be represented as 312 "\uD834\uDD1E". 314 string = quotation-mark *char quotation-mark 315 char = unescaped / 316 escape ( 317 %x22 / ; " quotation mark U+0022 318 %x5C / ; \ reverse solidus U+005C 319 %x2F / ; / solidus U+002F 320 %x62 / ; b backspace U+0008 321 %x66 / ; f form feed U+000C 322 %x6E / ; n line feed U+000A 323 %x72 / ; r carriage return U+000D 324 %x74 / ; t tab U+0009 325 %x75 4HEXDIG ) ; uXXXX U+XXXX 327 escape = %x5C ; \ 329 quotation-mark = %x22 ; " 331 unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 333 8. String and Character Issues 335 8.1. Encoding and Detection 337 JSON text SHALL be encoded in Unicode. The default encoding is 338 UTF-8. 340 Since the first two characters of a JSON text will always be ASCII 341 characters [RFC0020], it is possible to determine whether an octet 342 stream is UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE) by looking 343 at the pattern of nulls in the first four octets. 345 00 00 00 xx UTF-32BE 346 00 xx 00 xx UTF-16BE 347 xx 00 00 00 UTF-32LE 348 xx 00 xx 00 UTF-16LE 349 xx xx xx xx UTF-8 351 8.2. Unicode Characters 353 When all the strings represented in a JSON text are composed entirely 354 of Unicode characters [UNICODE] (however escaped), then that JSON 355 text is interoperable in the sense that all software implementations 356 which parse it will agree on the contents of names and of string 357 values in objects and arrays. 359 However, the ABNF in this specification allows member names and 360 string values to contain bit sequences which cannot encode Unicode 361 characters, for example "\uDEAD" (a single unpaired UTF-16 362 surrogate). Instances of this have been observed, for example when a 363 library truncates a UTF-16 string without checking whether the 364 truncation split a surrogate pair. The behavior of software which 365 receives JSON texts containing such values is unpredictable; for 366 example, implementations might return different values for the length 367 of a string value, or even suffer fatal runtime exceptions. 369 8.3. String Comparison 371 Software implementations are typically required to test names of 372 object members for equality. Implementations which transform the 373 textual representation into sequences of Unicode code units, and then 374 perform the comparison numerically, code unit by code unit, are 375 interoperable in the sense that implementations will agree in all 376 cases on equality or inequality of two strings. For example, 377 implementations which compare strings with escaped characters 378 unconverted may incorrectly find that "a\b" and "a\u005Cb" are not 379 equal. 381 9. Parsers 383 A JSON parser transforms a JSON text into another representation. A 384 JSON parser MUST accept all texts that conform to the JSON grammar. 385 A JSON parser MAY accept non-JSON forms or extensions. 387 An implementation may set limits on the size of texts that it 388 accepts. An implementation may set limits on the maximum depth of 389 nesting. An implementation may set limits on the range and precision 390 of numbers. An implementation may set limits on the length and 391 character contents of strings. 393 10. Generators 395 A JSON generator produces JSON text. The resulting text MUST 396 strictly conform to the JSON grammar. 398 11. IANA Considerations 400 The MIME media type for JSON text is application/json. 402 Type name: application 404 Subtype name: json 406 Required parameters: n/a 408 Optional parameters: n/a 409 Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32. 410 JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON 411 is written in UTF-8, JSON is 8bit compatible. When JSON is 412 written in UTF-16 or UTF-32, the binary content-transfer-encoding 413 must be used. 415 Interoperability considerations: Described in this document 417 Published specification: This document 419 Applications that use this media type: JSON has been used to 420 exchange data between applications written in all of these 421 programming languages: ActionScript, C, C#, Clojure, ColdFusion, 422 Common Lisp, E, Erlang, Go, Java, JavaScript, Lua, Objective CAML, 423 Perl, PHP, Python, Rebol, Ruby, Scala, and Scheme. 425 Additional information: Magic number(s): n/a 426 File extension(s): .json 427 Macintosh file type code(s): TEXT 429 Person & email address to contact for further information: IESG 430 . 513 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 514 October 1969. 516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 517 Requirement Levels", BCP 14, RFC 2119, March 1997. 519 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 520 Specifications: ABNF", STD 68, RFC 5234, January 2008. 522 [UNICODE] The Unicode Consortium, "The Unicode Standard", 2003-, 523 . 525 Note that this reference is to the latest version of 526 Unicode, rather than to a specific release. It is not 527 expected that future changes in the UNICODE specification 528 will impact the syntax of JSON. 530 15.2. Informative References 532 [ECMA-262] 533 European Computer Manufacturers Association, "ECMAScript 534 Language Specification 5.1 Edition ", June 2011, 535 . 537 [ECMA-404] 538 Ecma International, "The JSON Data Interchange Format ", 539 October 2013, . 542 [RFC4627] Crockford, D., "The application/json Media Type for 543 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 545 Appendix A. Changes from RFC 4627 547 This section lists changes between this document and the text in RFC 548 4627. 550 o Changed Working Group attribution to JSON Working Group. 552 o Changed title and abstract of document. 554 o Change the reference to [UNICODE] to be be non-version-specific. 556 o Added a "Specifications of JSON" section. 558 o Added an "Introduction to this Revision" section. 560 o Added language about duplicate object member names and 561 interoperability. 563 o Applied erratum #607 from RFC 4627 to correctly align the artwork 564 for the definition of "object". 566 o Changed "as sequences of digits" to "in the grammar below" in 567 "Numbers" section. 569 o Added language about number interoperability as a function of 570 IEEE754, and an IEEE754 reference. 572 o Added language about interoperability and Unicode characters, and 573 about string comparisons. To do this, turned the old "Encoding" 574 section into a "String and Character Issues" section, with three 575 subsections: The old "Encoding" material, and two new sections for 576 "Unicode Characters" and "String Comparison". 578 o Changed guidance in "Parsers" section to point out that 579 implementations may set limits on the range "and precision" of 580 numbers. 582 o Updated and tidied the "IANA Considerations" section. 584 o Made a real "Security Considerations" section, and lifted the text 585 out of the existing "IANA Considerations" section. 587 o Applied erratum #3607 from RFC 4627 by removing the security 588 consideration that begins "A JSON text can be safely passed" and 589 the JavaScript code that went with that consideration. 591 o Added a note to the "Security Considerations" section pointing out 592 the risks of using the "eval()" function in JavaScript or any 593 other language in which JSON texts conform to that language's 594 syntax. 596 o Changed "100" to 100 and added a boolean field, both in the first 597 example. 599 o Added "Contributors" section crediting Douglas Crockford. 601 o Added a reference to RFC4627. 603 o Moved the ECMAScript reference from Normative to Informative, 604 updated it to reference ECMAScript 5.1, and added reference to 605 ECMA 404. 607 Author's Address 609 Tim Bray (editor) 610 Google, Inc. 612 Email: tbray@textuality.com