idnits 2.17.1 draft-ietf-json-rfc4627bis-03.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 18, 2013) is 3866 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 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMA' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE754' ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 8 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 Intended status: Standards Track September 18, 2013 5 Expires: March 22, 2014 7 The JSON Data Interchange Format 8 draft-ietf-json-rfc4627bis-03 10 Abstract 12 JavaScript Object Notation (JSON) is a lightweight, text-based, 13 language-independent data interchange format. It was derived from 14 the ECMAScript Programming Language Standard. JSON defines a small 15 set of formatting rules for the portable representation of structured 16 data. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on March 22, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 54 1.2. Introduction to This Revision . . . . . . . . . . . . . . 3 55 1.3. Changes from RFC 4627 . . . . . . . . . . . . . . . . . . 3 56 2. JSON Grammar . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3. Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 4. Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 8. Character Model . . . . . . . . . . . . . . . . . . . . . . . 8 63 8.1. Encoding and Detection . . . . . . . . . . . . . . . . . 8 64 8.2. Unicode Characters . . . . . . . . . . . . . . . . . . . 8 65 8.3. String Comparison . . . . . . . . . . . . . . . . . . . . 9 66 9. Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 10. Generators . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 12. Security Considerations . . . . . . . . . . . . . . . . . . . 11 70 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 12 72 15. Normative References . . . . . . . . . . . . . . . . . . . . 12 73 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 75 1. Introduction 77 JavaScript Object Notation (JSON) is a text format for the 78 serialization of structured data. It is derived from the object 79 literals of JavaScript, as defined in the ECMAScript Programming 80 Language Standard, Third Edition [ECMA]. 82 JSON can represent four primitive types (strings, numbers, booleans, 83 and null) and two structured types (objects and arrays). 85 A string is a sequence of zero or more Unicode characters [UNICODE]. 87 An object is an unordered collection of zero or more name/value 88 pairs, where a name is a string and a value is a string, number, 89 boolean, null, object, or array. 91 An array is an ordered sequence of zero or more values. 93 The terms "object" and "array" come from the conventions of 94 JavaScript. 96 JSON's design goals were for it to be minimal, portable, textual, and 97 a subset of JavaScript. 99 1.1. Conventions Used in This Document 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC2119]. 105 The grammatical rules in this document are to be interpreted as 106 described in [RFC4234]. 108 1.2. Introduction to This Revision 110 In the years since the publication of RFC 4627, JSON has found very 111 wide use. This experience has revealed certain patterns which, while 112 allowed by the RFC, have caused interoperability problems. 114 Also, a small number of errata have been reported. 116 This revision does not change any of the rules of the specification; 117 all texts which were legal JSON remain so, and none which were not 118 JSON become JSON. The revision's goal is to fix the errata and 119 highlight practices which can lead to interoperability problems. 121 1.3. Changes from RFC 4627 123 This section lists all changes between this document and the text in 124 RFC 4627. 126 o Changed Working Group attribution to JSON Working Group. 128 o Changed title of doc per consensus call at http://www.ietf.org/ 129 mail-archive/web/json/current/msg00736.html 131 o Applied erratum #607 from RFC 4627 to correctly align the artwork 132 for the definition of "object". 134 o Change the reference to [UNICODE] to be be non-version-specific. 136 o Applied erratum #3607 from RFC 4627 by removing the security 137 consideration that begins "A JSON text can be safely passed" and 138 the JavaScript code that went with that consideration. 140 o Added Tim Bray as editor. 142 o Added an "Introduction to this Revision" section. 144 o Added language about duplicate object member names and 145 interoperability. 147 o Added language about intereoperability as a function of number 148 ranges and IEEE754. Also added IEEE754 reference. 150 o Added language about interoperability and Unicode characters, and 151 about string comparisons. To do this, turned the old "Encoding" 152 section into a "Character Model" section, with three subsections: 153 The old "Encoding" material, and two new sections for "Unicode 154 Characters" and "String Comparison". 156 o Made a real XML-level "Security Considerations" section, and 157 lifted the text out of the existing "IANA Considerations" section. 159 o Removed the language "Interoperability considerations: n/a" from 160 the "IANA Considerations section. 162 o Added "Contributors" section crediting Douglas Crockford. 164 2. JSON Grammar 166 A JSON text is a sequence of tokens. The set of tokens includes six 167 structural characters, strings, numbers, and three literal names. 169 A JSON text is a serialized object or array. 171 JSON-text = object / array 173 These are the six structural characters: 175 begin-array = ws %x5B ws ; [ left square bracket 177 begin-object = ws %x7B ws ; { left curly bracket 179 end-array = ws %x5D ws ; ] right square bracket 181 end-object = ws %x7D ws ; } right curly bracket 183 name-separator = ws %x3A ws ; : colon 185 value-separator = ws %x2C ws ; , comma 187 Insignificant whitespace is allowed before or after any of the six 188 structural characters. 190 ws = *( 191 %x20 / ; Space 192 %x09 / ; Horizontal tab 193 %x0A / ; Line feed or New line 194 %x0D ; Carriage return 195 ) 197 3. Values 199 A JSON value MUST be an object, array, number, or string, or one of 200 the following three literal names: 202 false null true 204 The literal names MUST be lowercase. No other literal names are 205 allowed. 207 value = false / null / true / object / array / number / string 209 false = %x66.61.6c.73.65 ; false 211 null = %x6e.75.6c.6c ; null 213 true = %x74.72.75.65 ; true 215 4. Objects 217 An object structure is represented as a pair of curly brackets 218 surrounding zero or more name/value pairs (or members). A name is a 219 string. A single colon comes after each name, separating the name 220 from the value. A single comma separates a value from a following 221 name. The names within an object SHOULD be unique. 223 object = begin-object [ member *( value-separator member ) ] 224 end-object 226 member = string name-separator value 228 An object whose names are all unique is interoperable in the sense 229 that all software implementations which receive that object will 230 agree on the name-value mappings. When the names within an object 231 are not unique, the behavior of software that receives such an object 232 is unpredictable. Many implementations report the last name/value 233 pair only; other implementations report an error or fail to parse the 234 object; other implementations report all of the name/value pairs, 235 including duplicates. 237 5. Arrays 239 An array structure is represented as square brackets surrounding zero 240 or more values (or elements). Elements are separated by commas. 242 array = begin-array [ value *( value-separator value ) ] end-array 244 6. Numbers 246 The representation of numbers is similar to that used in most 247 programming languages. A number contains an integer component that 248 may be prefixed with an optional minus sign, which may be followed by 249 a fraction part and/or an exponent part. 251 Octal and hex forms are not allowed. Leading zeros are not allowed. 253 A fraction part is a decimal point followed by one or more digits. 255 An exponent part begins with the letter E in upper or lowercase, 256 which may be followed by a plus or minus sign. The E and optional 257 sign are followed by one or more digits. 259 Numeric values that cannot be represented as sequences of digits 260 (such as Infinity and NaN) are not permitted. 262 number = [ minus ] int [ frac ] [ exp ] 264 decimal-point = %x2E ; . 266 digit1-9 = %x31-39 ; 1-9 268 e = %x65 / %x45 ; e E 270 exp = e [ minus / plus ] 1*DIGIT 272 frac = decimal-point 1*DIGIT 274 int = zero / ( digit1-9 *DIGIT ) 276 minus = %x2D ; - 278 plus = %x2B ; + 280 zero = %x30 ; 0 282 This specification allows implementations to set limits on the range 283 of numbers accepted. While absolute interoperability cannot be 284 guaranteed, wide interoperability can be achieved by limiting numbers 285 in JSON texts to those within the precision and magnitude expressible 286 in an IEEE 754:20008 binary64 (double precision) number [IEEE754]. 287 Numeric values that cannot be represented in the grammar above (such 288 as Infinity and NaN) are not permitted. Attempting to represent 289 numbers that cannot be exactly encoded as an IEEE 754:2008 binary64 290 number, such as 1E400, 9007199254740993, or 291 3.141592653589793238462643383279, may cause interoperability 292 problems. 294 7. Strings 296 The representation of strings is similar to conventions used in the C 297 family of programming languages. A string begins and ends with 298 quotation marks. All Unicode characters may be placed within the 299 quotation marks except for the characters that must be escaped: 300 quotation mark, reverse solidus, and the control characters (U+0000 301 through U+001F). 303 Any character may be escaped. If the character is in the Basic 304 Multilingual Plane (U+0000 through U+FFFF), then it may be 305 represented as a six-character sequence: a reverse solidus, followed 306 by the lowercase letter u, followed by four hexadecimal digits that 307 encode the character's code point. The hexadecimal letters A though 308 F can be upper or lowercase. So, for example, a string containing 309 only a single reverse solidus character may be represented as 310 "\u005C". 312 Alternatively, there are two-character sequence escape 313 representations of some popular characters. So, for example, a 314 string containing only a single reverse solidus character may be 315 represented more compactly as "\\". 317 To escape an extended character that is not in the Basic Multilingual 318 Plane, the character is represented as a twelve-character sequence, 319 encoding the UTF-16 surrogate pair. So, for example, a string 320 containing only the G clef character (U+1D11E) may be represented as 321 "\uD834\uDD1E". 323 string = quotation-mark *char quotation-mark 325 char = unescaped / 326 escape ( 327 %x22 / ; " quotation mark U+0022 328 %x5C / ; \ reverse solidus U+005C 329 %x2F / ; / solidus U+002F 330 %x62 / ; b backspace U+0008 331 %x66 / ; f form feed U+000C 332 %x6E / ; n line feed U+000A 333 %x72 / ; r carriage return U+000D 334 %x74 / ; t tab U+0009 335 %x75 4HEXDIG ) ; uXXXX U+XXXX 337 escape = %x5C ; \ 339 quotation-mark = %x22 ; " 341 unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 343 8. Character Model 345 8.1. Encoding and Detection 347 JSON text SHALL be encoded in Unicode. The default encoding is 348 UTF-8. 350 Since the first two characters of a JSON text will always be ASCII 351 characters [RFC0020], it is possible to determine whether an octet 352 stream is UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE) by looking 353 at the pattern of nulls in the first four octets. 355 00 00 00 xx UTF-32BE 356 00 xx 00 xx UTF-16BE 357 xx 00 00 00 UTF-32LE 358 xx 00 xx 00 UTF-16LE 359 xx xx xx xx UTF-8 361 8.2. Unicode Characters 363 A JSON text which is composed entirely of Unicode characters 364 [UNICODE] (however encoded) is interoperable in the sense that all 365 software implementations which parse it will agree on the contents of 366 names and values of object members. However, the ABNF in this 367 specification allows member names and string values to contain bit 368 sequences which cannot encode Unicode characters, for example 369 "\uDEAD" (a single unpaired UTF-16 surrogate). Instances of this 370 have been observed, for example when a library truncates a UTF-16 371 string without checking whether the truncation split a surrogate 372 pair. The behavior of software which receives JSON texts containing 373 such values is unpredictable; for example, implementations might 374 return different values for the length of a string value, or even 375 suffer a fatal runtime exception. 377 8.3. String Comparison 379 Software implementations are typically required to test names of 380 object members for equality. Implementations which transform the 381 textual representation into sequences of Unicode code units, and then 382 perform the comparison numerically, code unit by code unit, are 383 interoperable in the sense that implementations will agree in all 384 cases on equality or inequality of two strings. For example, 385 implementations which compare strings with escaped characters 386 unconverted may incorrectly find that "a\b" and "a\u005Cb" are not 387 equal. 389 9. Parsers 391 A JSON parser transforms a JSON text into another representation. A 392 JSON parser MUST accept all texts that conform to the JSON grammar. 393 A JSON parser MAY accept non-JSON forms or extensions. 395 An implementation may set limits on the size of texts that it 396 accepts. An implementation may set limits on the maximum depth of 397 nesting. An implementation may set limits on the range of numbers. 398 An implementation may set limits on the length and character contents 399 of strings. 401 10. Generators 403 A JSON generator produces JSON text. The resulting text MUST 404 strictly conform to the JSON grammar. 406 11. IANA Considerations 407 The MIME media type for JSON text is application/json. 409 Type name: application 411 Subtype name: json 413 Required parameters: n/a 415 Optional parameters: n/a 417 Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32 419 JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON 420 is written in UTF-8, JSON is 8bit compatible. When JSON is 421 written in UTF-16 or UTF-32, the binary content-transfer-encoding 422 must be used. 424 Published specification: RFC 4627 426 Applications that use this media type: 428 JSON has been used to exchange data between applications written 429 in all of these programming languages: ActionScript, C, C#, 430 ColdFusion, Common Lisp, E, Erlang, Java, JavaScript, Lua, 431 Objective CAML, Perl, PHP, Python, Rebol, Ruby, and Scheme. 433 Additional information: 435 Magic number(s): n/a 436 File extension(s): .json 437 Macintosh file type code(s): TEXT 439 Person & email address to contact for further information: 440 Douglas Crockford 441 douglas@crockford.com 443 Intended usage: COMMON 445 Restrictions on usage: none 447 Author: 448 Douglas Crockford 449 douglas@crockford.com 451 Change controller: 452 Douglas Crockford 453 douglas@crockford.com 455 12. Security Considerations 457 Generally there are security issues with scripting languages. JSON 458 is a subset of JavaScript, but excludes assignment and invocation. 460 13. Examples 462 This is a JSON object: 464 { 465 "Image": { 466 "Width": 800, 467 "Height": 600, 468 "Title": "View from 15th Floor", 469 "Thumbnail": { 470 "Url": "http://www.example.com/image/481989943", 471 "Height": 125, 472 "Width": "100" 473 }, 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 14. Contributors 508 RFC 4627 was written by Douglas Crockford. This document was 509 constructed by making a relatively small number of additions to and 510 subtractions from that document; thus the vast majority of the text 511 here is his. 513 15. Normative References 515 [ECMA] European Computer Manufacturers Association, "ECMAScript 516 Language Specification 3rd Edition ", December 1999, 517 . 520 [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", 2008, 521 . 523 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 524 October 1969. 526 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 527 Requirement Levels", BCP 14, RFC 2119, March 1997. 529 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for 530 Syntax Specifications: ABNF", RFC 4234, October 2005. 532 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 4.0 533 ", 2003, . 535 Author's Address 537 Tim Bray (editor) 538 Google, Inc. 540 Email: tbray@textuality.com