idnits 2.17.00 (12 Aug 2021) /tmp/idnits56796/draft-ietf-json-rfc4627bis-09.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 seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 10, 2013) is 3083 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 474 -- Looks like a reference, but probably isn't: '943' on line 474 -- Looks like a reference, but probably isn't: '234' on line 474 -- Looks like a reference, but probably isn't: '38793' on line 474 == Unused Reference: 'RFC0020' is defined on line 527, but no explicit reference was found in the text -- 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 (~~), 3 warnings (==), 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) December 10, 2013 5 Intended status: Standards Track 6 Expires: June 13, 2014 8 The JSON Data Interchange Format 9 draft-ietf-json-rfc4627bis-09 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 removes inconsistencies with other specifications of 20 JSON, repairs specification errors, and offers experience-based 21 interoperability 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 June 13, 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 This document may contain material from IETF Documents or IETF 56 Contributions published or made publicly available before November 57 10, 2008. The person(s) controlling the copyright in some of this 58 material may not have granted the IETF Trust the right to allow 59 modifications of such material outside the IETF Standards Process. 60 Without obtaining an adequate license from the person(s) controlling 61 the copyright in such materials, this document may not be modified 62 outside the IETF Standards Process, and derivative works of it may 63 not be created outside the IETF Standards Process, except to format 64 it for publication as an RFC or to translate it into languages other 65 than English. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 70 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 71 1.2. Specifications of JSON . . . . . . . . . . . . . . . . . 3 72 1.3. Introduction to This Revision . . . . . . . . . . . . . . 4 73 2. JSON Grammar . . . . . . . . . . . . . . . . . . . . . . . . 4 74 3. Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 75 4. Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 6. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 78 7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 79 8. String and Character Issues . . . . . . . . . . . . . . . . . 8 80 8.1. Character Encoding . . . . . . . . . . . . . . . . . . . 9 81 8.2. Unicode Characters . . . . . . . . . . . . . . . . . . . 9 82 8.3. String Comparison . . . . . . . . . . . . . . . . . . . . 9 83 9. Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 84 10. Generators . . . . . . . . . . . . . . . . . . . . . . . . . 10 85 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 86 12. Security Considerations . . . . . . . . . . . . . . . . . . . 11 87 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 88 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 12 89 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 90 15.1. Normative References . . . . . . . . . . . . . . . . . . 12 91 15.2. Informative References . . . . . . . . . . . . . . . . . 13 92 Appendix A. Changes from RFC 4627 . . . . . . . . . . . . . . . 13 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 95 1. Introduction 96 JavaScript Object Notation (JSON) is a text format for the 97 serialization of structured data. It is derived from the object 98 literals of JavaScript, as defined in the ECMAScript Programming 99 Language Standard, Third Edition [ECMA-262]. 101 JSON can represent four primitive types (strings, numbers, booleans, 102 and null) and two structured types (objects and arrays). 104 A string is a sequence of zero or more Unicode characters [UNICODE]. 106 An object is an unordered collection of zero or more name/value 107 pairs, where a name is a string and a value is a string, number, 108 boolean, null, object, or array. 110 An array is an ordered sequence of zero or more values. 112 The terms "object" and "array" come from the conventions of 113 JavaScript. 115 JSON's design goals were for it to be minimal, portable, textual, and 116 a subset of JavaScript. 118 1.1. Conventions Used in This Document 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in [RFC2119]. 124 The grammatical rules in this document are to be interpreted as 125 described in [RFC5234]. 127 1.2. Specifications of JSON 129 This document is an update of [RFC4627], which described JSON and 130 registered the Media Type "application/json". 132 A description of JSON in ECMAScript terms appears in version 5.1 of 133 the ECMAScript specification [ECMA-262], section 15.12. JSON is also 134 described in [ECMA-404]. 136 All of the specifications of JSON syntax agree on the syntactic 137 elements of the language. 139 1.3. Introduction to This Revision 141 In the years since the publication of RFC 4627, JSON has found very 142 wide use. This experience has revealed certain patterns which, while 143 allowed by its specifications, have caused interoperability problems. 145 Also, a small number of errata have been reported. 147 This revision does not change any of the rules of the specification; 148 all texts which were legal JSON remain so, and none which were not 149 JSON become JSON. The revision's goal is to apply the errata and 150 highlight practices which can lead to interoperability problems. 152 2. JSON Grammar 154 A JSON text is a sequence of tokens. The set of tokens includes six 155 structural characters, strings, numbers, and three literal names. 157 A JSON text is a serialized value. Note that certain previous 158 specifications of JSON constrained a JSON text to be an object or an 159 array. Implementations which generate only objects or arrays where a 160 JSON text is called for will be interoperable in the sense that all 161 implementations will accept these as conforming JSON texts. 163 JSON-text = ws value ws 165 These are the six structural characters: 167 begin-array = ws %x5B ws ; [ left square bracket 169 begin-object = ws %x7B ws ; { left curly bracket 171 end-array = ws %x5D ws ; ] right square bracket 173 end-object = ws %x7D ws ; } right curly bracket 175 name-separator = ws %x3A ws ; : colon 177 value-separator = ws %x2C ws ; , comma 179 Insignificant whitespace is allowed before or after any of the six 180 structural characters. 182 ws = *( 183 %x20 / ; Space 184 %x09 / ; Horizontal tab 185 %x0A / ; Line feed or New line 186 %x0D ) ; Carriage return 188 3. Values 190 A JSON value MUST be an object, array, number, or string, or one of 191 the following three literal names: 193 false null true 195 The literal names MUST be lowercase. No other literal names are 196 allowed. 198 value = false / null / true / object / array / number / string 200 false = %x66.61.6c.73.65 ; false 202 null = %x6e.75.6c.6c ; null 204 true = %x74.72.75.65 ; true 206 4. Objects 208 An object structure is represented as a pair of curly brackets 209 surrounding zero or more name/value pairs (or members). A name is a 210 string. A single colon comes after each name, separating the name 211 from the value. A single comma separates a value from a following 212 name. The names within an object SHOULD be unique. 214 object = begin-object [ member *( value-separator member ) ] 215 end-object 217 member = string name-separator value 219 An object whose names are all unique is interoperable in the sense 220 that all software implementations which receive that object will 221 agree on the name-value mappings. When the names within an object 222 are not unique, the behavior of software that receives such an object 223 is unpredictable. Many implementations report the last name/value 224 pair only; other implementations report an error or fail to parse the 225 object; other implementations report all of the name/value pairs, 226 including duplicates. 228 5. Arrays 230 An array structure is represented as square brackets surrounding zero 231 or more values (or elements). Elements are separated by commas. 233 array = begin-array [ value *( value-separator value ) ] end-array 235 There is no requirement that the values in an array be of the same 236 type. 238 6. Numbers 240 The representation of numbers is similar to that used in most 241 programming languages. A number contains an integer component that 242 may be prefixed with an optional minus sign, which may be followed by 243 a fraction part and/or an exponent part. 245 Octal and hex forms are not allowed. Leading zeros are not allowed. 247 A fraction part is a decimal point followed by one or more digits. 249 An exponent part begins with the letter E in upper or lowercase, 250 which may be followed by a plus or minus sign. The E and optional 251 sign are followed by one or more digits. 253 Numeric values that cannot be represented in the grammar below (such 254 as Infinity and NaN) are not permitted. 256 number = [ minus ] int [ frac ] [ exp ] 258 decimal-point = %x2E ; . 260 digit1-9 = %x31-39 ; 1-9 262 e = %x65 / %x45 ; e E 264 exp = e [ minus / plus ] 1*DIGIT 266 frac = decimal-point 1*DIGIT 268 int = zero / ( digit1-9 *DIGIT ) 270 minus = %x2D ; - 272 plus = %x2B ; + 274 zero = %x30 ; 0 276 This specification allows implementations to set limits on the range 277 and precision of numbers accepted. Since software which implements 278 IEEE 754-2008 binary64 (double precision) numbers [IEEE754] is 279 generally available and widely used, good interoperability can be 280 achieved by implementations which expect no more precision or range 281 than these provide, in the sense that implementations will 282 approximate JSON numbers within the expected precision. A JSON 283 number such as 1E400 or 3.141592653589793238462643383279 may indicate 284 potential interoperability problems since it suggests that the 285 software which created it it expected greater magnitude or precision 286 than is widely available. 288 Note that when such software is used, numbers which are integers and 289 are in the range [-(2**53)+1, (2**53)-1] are interoperable in the 290 sense that implementations will agree exactly on their numeric 291 values. 293 7. Strings 295 The representation of strings is similar to conventions used in the C 296 family of programming languages. A string begins and ends with 297 quotation marks. All Unicode characters may be placed within the 298 quotation marks except for the characters that must be escaped: 299 quotation mark, reverse solidus, and the control characters (U+0000 300 through U+001F). 302 Any character may be escaped. If the character is in the Basic 303 Multilingual Plane (U+0000 through U+FFFF), then it may be 304 represented as a six-character sequence: a reverse solidus, followed 305 by the lowercase letter u, followed by four hexadecimal digits that 306 encode the character's code point. The hexadecimal letters A though 307 F can be upper or lowercase. So, for example, a string containing 308 only a single reverse solidus character may be represented as 309 "\u005C". 311 Alternatively, there are two-character sequence escape 312 representations of some popular characters. So, for example, a 313 string containing only a single reverse solidus character may be 314 represented more compactly as "\\". 316 To escape an extended character that is not in the Basic Multilingual 317 Plane, the character is represented as a twelve-character sequence, 318 encoding the UTF-16 surrogate pair. So, for example, a string 319 containing only the G clef character (U+1D11E) may be represented as 320 "\uD834\uDD1E". 322 string = quotation-mark *char quotation-mark 324 char = unescaped / 325 escape ( 326 %x22 / ; " quotation mark U+0022 327 %x5C / ; \ reverse solidus U+005C 328 %x2F / ; / solidus U+002F 329 %x62 / ; b backspace U+0008 330 %x66 / ; f form feed U+000C 331 %x6E / ; n line feed U+000A 332 %x72 / ; r carriage return U+000D 333 %x74 / ; t tab U+0009 334 %x75 4HEXDIG ) ; uXXXX U+XXXX 336 escape = %x5C ; \ 338 quotation-mark = %x22 ; " 340 unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 342 8. String and Character Issues 343 8.1. Character Encoding 345 JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32. The default 346 encoding is UTF-8, and JSON texts which are encoded in UTF-8 are 347 interoperable in the sense that they will be read successfully by the 348 maximum number of implementations; there are many implementations 349 which cannot successfully read texts in other encodings (such as 350 UTF-16 and UTF-32). 352 Implementations MUST NOT add a byte order mark to the beginning of a 353 JSON text. In the interests of interoperability, implementations 354 which parse JSON texts MAY ignore the presence of a byte order mark 355 rather than treating it as an error. 357 8.2. Unicode Characters 359 When all the strings represented in a JSON text are composed entirely 360 of Unicode characters [UNICODE] (however escaped), then that JSON 361 text is interoperable in the sense that all software implementations 362 which parse it will agree on the contents of names and of string 363 values in objects and arrays. 365 However, the ABNF in this specification allows member names and 366 string values to contain bit sequences which cannot encode Unicode 367 characters, for example "\uDEAD" (a single unpaired UTF-16 368 surrogate). Instances of this have been observed, for example when a 369 library truncates a UTF-16 string without checking whether the 370 truncation split a surrogate pair. The behavior of software which 371 receives JSON texts containing such values is unpredictable; for 372 example, implementations might return different values for the length 373 of a string value, or even suffer fatal runtime exceptions. 375 8.3. String Comparison 377 Software implementations are typically required to test names of 378 object members for equality. Implementations which transform the 379 textual representation into sequences of Unicode code units, and then 380 perform the comparison numerically, code unit by code unit, are 381 interoperable in the sense that implementations will agree in all 382 cases on equality or inequality of two strings. For example, 383 implementations which compare strings with escaped characters 384 unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not 385 equal. 387 9. Parsers 388 A JSON parser transforms a JSON text into another representation. A 389 JSON parser MUST accept all texts that conform to the JSON grammar. 390 A JSON parser MAY accept non-JSON forms or extensions. 392 An implementation may set limits on the size of texts that it 393 accepts. An implementation may set limits on the maximum depth of 394 nesting. An implementation may set limits on the range and precision 395 of numbers. An implementation may set limits on the length and 396 character contents of strings. 398 10. Generators 400 A JSON generator produces JSON text. The resulting text MUST 401 strictly conform to the JSON grammar. 403 11. IANA Considerations 405 The MIME media type for JSON text is application/json. 407 Type name: application 409 Subtype name: json 411 Required parameters: n/a 413 Optional parameters: n/a 415 Encoding considerations: binary 417 Interoperability considerations: Described in this document 419 Published specification: This document 421 Applications that use this media type: JSON has been used to 422 exchange data between applications written in all of these 423 programming languages: ActionScript, C, C#, Clojure, ColdFusion, 424 Common Lisp, E, Erlang, Go, Java, JavaScript, Lua, Objective CAML, 425 Perl, PHP, Python, Rebol, Ruby, Scala, and Scheme. 427 Additional information: Magic number(s): n/a 428 File extension(s): .json 429 Macintosh file type code(s): TEXT 431 Person & email address to contact for further information: IESG 432 434 Intended usage: COMMON 435 Restrictions on usage: none 437 Author: Douglas Crockford 438 440 Change controller: IESG 441 443 Note: No "charset" parameter is defined for this registration. 444 Adding one really has no effect on compliant recipients. 446 12. Security Considerations 448 Generally there are security issues with scripting languages. JSON 449 is a subset of JavaScript, but excludes assignment and invocation. 451 Since JSON's syntax is borrowed from JavaScript, it is possible to 452 use that language's "eval()" function to parse JSON texts. This 453 generally constitutes an unacceptable security risk, since the text 454 could contain executable code along with data declarations. The same 455 consideration applies to the use of eval()-like functions in any 456 other programming language in which JSON texts conform to that 457 language's syntax. 459 13. Examples 461 This is a JSON object: 463 { 464 "Image": { 465 "Width": 800, 466 "Height": 600, 467 "Title": "View from 15th Floor", 468 "Thumbnail": { 469 "Url": "http://www.example.com/image/481989943", 470 "Height": 125, 471 "Width": 100 472 }, 473 "Animated" : false, 474 "IDs": [116, 943, 234, 38793] 475 } 476 } 478 Its Image member is an object whose Thumbnail member is an object and 479 whose IDs member is an array of numbers. 481 This is a JSON array containing two objects: 483 [ 484 { 485 "precision": "zip", 486 "Latitude": 37.7668, 487 "Longitude": -122.3959, 488 "Address": "", 489 "City": "SAN FRANCISCO", 490 "State": "CA", 491 "Zip": "94107", 492 "Country": "US" 493 }, 494 { 495 "precision": "zip", 496 "Latitude": 37.371991, 497 "Longitude": -122.026020, 498 "Address": "", 499 "City": "SUNNYVALE", 500 "State": "CA", 501 "Zip": "94085", 502 "Country": "US" 503 } 504 ] 506 Here are three small JSON texts containing only values: 508 "Hello world!" 510 42 512 true 514 14. Contributors 516 RFC 4627 was written by Douglas Crockford. This document was 517 constructed by making a relatively small number of changes to that 518 document; thus the vast majority of the text here is his. 520 15. References 522 15.1. Normative References 524 [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", 2008, 525 . 527 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 528 October 1969. 530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 531 Requirement Levels", BCP 14, RFC 2119, March 1997. 533 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 534 Specifications: ABNF", STD 68, RFC 5234, January 2008. 536 [UNICODE] The Unicode Consortium, "The Unicode Standard", 2003-, 537 . 539 Note that this reference is to the latest version of 540 Unicode, rather than to a specific release. It is not 541 expected that future changes in the UNICODE specification 542 will impact the syntax of JSON. 544 15.2. Informative References 546 [ECMA-262] 547 European Computer Manufacturers Association, "ECMAScript 548 Language Specification 5.1 Edition ", June 2011, 549 . 551 [ECMA-404] 552 Ecma International, "The JSON Data Interchange Format ", 553 October 2013, . 556 [RFC4627] Crockford, D., "The application/json Media Type for 557 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 559 Appendix A. Changes from RFC 4627 561 This section lists changes between this document and the text in RFC 562 4627. 564 o Changed title and abstract of document. 566 o Change the reference to [UNICODE] to be be non-version-specific. 568 o Added a "Specifications of JSON" section. 570 o Added an "Introduction to this Revision" section. 572 o Changed the definition of "JSON text" so that it can be any JSON 573 value, removing the constraint that it be an object or array. 575 o Added language about duplicate object member names and 576 interoperability. 578 o Clarified the absence of a requirement that values in an array be 579 of the same JSON type. 581 o Applied erratum #607 from RFC 4627 to correctly align the artwork 582 for the definition of "object". 584 o Changed "as sequences of digits" to "in the grammar below" in 585 "Numbers" section. 587 o Added language about number interoperability as a function of 588 IEEE754, and an IEEE754 reference. 590 o Added language about interoperability and Unicode characters, and 591 about string comparisons. To do this, turned the old "Encoding" 592 section into a "String and Character Issues" section, with three 593 subsections: "Character Encoding", "Unicode Characters" and 594 "String Comparison". 596 o Changed guidance in "Parsers" section to point out that 597 implementations may set limits on the range "and precision" of 598 numbers. 600 o Updated and tidied the "IANA Considerations" section. 602 o Made a real "Security Considerations" section, and lifted the text 603 out of the existing "IANA Considerations" section. 605 o Applied erratum #3607 from RFC 4627 by removing the security 606 consideration that begins "A JSON text can be safely passed" and 607 the JavaScript code that went with that consideration. 609 o Added a note to the "Security Considerations" section pointing out 610 the risks of using the "eval()" function in JavaScript or any 611 other language in which JSON texts conform to that language's 612 syntax. 614 o Added a note to IANA considerations clarifying the absence of a 615 "charset" parameter for the application/json media type. 617 o Changed "100" to 100 and added a boolean field, both in the first 618 example. 620 o Added examples of JSON texts which simple values, neither objects 621 nor arrays. 623 o Added "Contributors" section crediting Douglas Crockford. 625 o Added a reference to RFC4627. 627 o Moved the ECMAScript reference from Normative to Informative, 628 updated it to reference ECMAScript 5.1, and added reference to 629 ECMA 404. 631 Author's Address 633 Tim Bray (editor) 634 Google, Inc. 636 Email: tbray@textuality.com