1 2 3 4 5 6 7Network Working Group D. Crockford 8Request for Comments: 4627 JSON.org 9Category: Informational July 2006 10 11 12 The application/json Media Type for JavaScript Object Notation (JSON) 13 14Status of This Memo 15 16 This memo provides information for the Internet community. It does 17 not specify an Internet standard of any kind. Distribution of this 18 memo is unlimited. 19 20Copyright Notice 21 22 Copyright (C) The Internet Society (2006). 23 24Abstract 25 26 JavaScript Object Notation (JSON) is a lightweight, text-based, 27 language-independent data interchange format. It was derived from 28 the ECMAScript Programming Language Standard. JSON defines a small 29 set of formatting rules for the portable representation of structured 30 data. 31 321. Introduction 33 34 JavaScript Object Notation (JSON) is a text format for the 35 serialization of structured data. It is derived from the object 36 literals of JavaScript, as defined in the ECMAScript Programming 37 Language Standard, Third Edition [ECMA]. 38 39 JSON can represent four primitive types (strings, numbers, booleans, 40 and null) and two structured types (objects and arrays). 41 42 A string is a sequence of zero or more Unicode characters [UNICODE]. 43 44 An object is an unordered collection of zero or more name/value 45 pairs, where a name is a string and a value is a string, number, 46 boolean, null, object, or array. 47 48 An array is an ordered sequence of zero or more values. 49 50 The terms "object" and "array" come from the conventions of 51 JavaScript. 52 53 JSON's design goals were for it to be minimal, portable, textual, and 54 a subset of JavaScript. 55 56 57 58Crockford Informational [Page 1] 59 60RFC 4627 JSON July 2006 61 62 631.1. Conventions Used in This Document 64 65 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 66 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 67 document are to be interpreted as described in [RFC2119]. 68 69 The grammatical rules in this document are to be interpreted as 70 described in [RFC4234]. 71 722. JSON Grammar 73 74 A JSON text is a sequence of tokens. The set of tokens includes six 75 structural characters, strings, numbers, and three literal names. 76 77 A JSON text is a serialized object or array. 78 79 JSON-text = object / array 80 81 These are the six structural characters: 82 83 begin-array = ws %x5B ws ; [ left square bracket 84 85 begin-object = ws %x7B ws ; { left curly bracket 86 87 end-array = ws %x5D ws ; ] right square bracket 88 89 end-object = ws %x7D ws ; } right curly bracket 90 91 name-separator = ws %x3A ws ; : colon 92 93 value-separator = ws %x2C ws ; , comma 94 95 Insignificant whitespace is allowed before or after any of the six 96 structural characters. 97 98 ws = *( 99 %x20 / ; Space 100 %x09 / ; Horizontal tab 101 %x0A / ; Line feed or New line 102 %x0D ; Carriage return 103 ) 104 1052.1. Values 106 107 A JSON value MUST be an object, array, number, or string, or one of 108 the following three literal names: 109 110 false null true 111 112 113 114Crockford Informational [Page 2] 115 116RFC 4627 JSON July 2006 117 118 119 The literal names MUST be lowercase. No other literal names are 120 allowed. 121 122 value = false / null / true / object / array / number / string 123 124 false = %x66.61.6c.73.65 ; false 125 126 null = %x6e.75.6c.6c ; null 127 128 true = %x74.72.75.65 ; true 129 1302.2. Objects 131 132 An object structure is represented as a pair of curly brackets 133 surrounding zero or more name/value pairs (or members). A name is a 134 string. A single colon comes after each name, separating the name 135 from the value. A single comma separates a value from a following 136 name. The names within an object SHOULD be unique. 137 138 object = begin-object [ member *( value-separator member ) ] 139 end-object 140 141 member = string name-separator value 142 1432.3. Arrays 144 145 An array structure is represented as square brackets surrounding zero 146 or more values (or elements). Elements are separated by commas. 147 148 array = begin-array [ value *( value-separator value ) ] end-array 149 1502.4. Numbers 151 152 The representation of numbers is similar to that used in most 153 programming languages. A number contains an integer component that 154 may be prefixed with an optional minus sign, which may be followed by 155 a fraction part and/or an exponent part. 156 157 Octal and hex forms are not allowed. Leading zeros are not allowed. 158 159 A fraction part is a decimal point followed by one or more digits. 160 161 An exponent part begins with the letter E in upper or lowercase, 162 which may be followed by a plus or minus sign. The E and optional 163 sign are followed by one or more digits. 164 165 Numeric values that cannot be represented as sequences of digits 166 (such as Infinity and NaN) are not permitted. 167 168 169 170Crockford Informational [Page 3] 171 172RFC 4627 JSON July 2006 173 174 175 number = [ minus ] int [ frac ] [ exp ] 176 177 decimal-point = %x2E ; . 178 179 digit1-9 = %x31-39 ; 1-9 180 181 e = %x65 / %x45 ; e E 182 183 exp = e [ minus / plus ] 1*DIGIT 184 185 frac = decimal-point 1*DIGIT 186 187 int = zero / ( digit1-9 *DIGIT ) 188 189 minus = %x2D ; - 190 191 plus = %x2B ; + 192 193 zero = %x30 ; 0 194 1952.5. Strings 196 197 The representation of strings is similar to conventions used in the C 198 family of programming languages. A string begins and ends with 199 quotation marks. All Unicode characters may be placed within the 200 quotation marks except for the characters that must be escaped: 201 quotation mark, reverse solidus, and the control characters (U+0000 202 through U+001F). 203 204 Any character may be escaped. If the character is in the Basic 205 Multilingual Plane (U+0000 through U+FFFF), then it may be 206 represented as a six-character sequence: a reverse solidus, followed 207 by the lowercase letter u, followed by four hexadecimal digits that 208 encode the character's code point. The hexadecimal letters A though 209 F can be upper or lowercase. So, for example, a string containing 210 only a single reverse solidus character may be represented as 211 "\u005C". 212 213 Alternatively, there are two-character sequence escape 214 representations of some popular characters. So, for example, a 215 string containing only a single reverse solidus character may be 216 represented more compactly as "\\". 217 218 To escape an extended character that is not in the Basic Multilingual 219 Plane, the character is represented as a twelve-character sequence, 220 encoding the UTF-16 surrogate pair. So, for example, a string 221 containing only the G clef character (U+1D11E) may be represented as 222 "\uD834\uDD1E". 223 224 225 226Crockford Informational [Page 4] 227 228RFC 4627 JSON July 2006 229 230 231 string = quotation-mark *char quotation-mark 232 233 char = unescaped / 234 escape ( 235 %x22 / ; " quotation mark U+0022 236 %x5C / ; \ reverse solidus U+005C 237 %x2F / ; / solidus U+002F 238 %x62 / ; b backspace U+0008 239 %x66 / ; f form feed U+000C 240 %x6E / ; n line feed U+000A 241 %x72 / ; r carriage return U+000D 242 %x74 / ; t tab U+0009 243 %x75 4HEXDIG ) ; uXXXX U+XXXX 244 245 escape = %x5C ; \ 246 247 quotation-mark = %x22 ; " 248 249 unescaped = %x20-21 / %x23-5B / %x5D-10FFFF 250 2513. Encoding 252 253 JSON text SHALL be encoded in Unicode. The default encoding is 254 UTF-8. 255 256 Since the first two characters of a JSON text will always be ASCII 257 characters [RFC0020], it is possible to determine whether an octet 258 stream is UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE) by looking 259 at the pattern of nulls in the first four octets. 260 261 00 00 00 xx UTF-32BE 262 00 xx 00 xx UTF-16BE 263 xx 00 00 00 UTF-32LE 264 xx 00 xx 00 UTF-16LE 265 xx xx xx xx UTF-8 266 2674. Parsers 268 269 A JSON parser transforms a JSON text into another representation. A 270 JSON parser MUST accept all texts that conform to the JSON grammar. 271 A JSON parser MAY accept non-JSON forms or extensions. 272 273 An implementation may set limits on the size of texts that it 274 accepts. An implementation may set limits on the maximum depth of 275 nesting. An implementation may set limits on the range of numbers. 276 An implementation may set limits on the length and character contents 277 of strings. 278 279 280 281 282Crockford Informational [Page 5] 283 284RFC 4627 JSON July 2006 285 286 2875. Generators 288 289 A JSON generator produces JSON text. The resulting text MUST 290 strictly conform to the JSON grammar. 291 2926. IANA Considerations 293 294 The MIME media type for JSON text is application/json. 295 296 Type name: application 297 298 Subtype name: json 299 300 Required parameters: n/a 301 302 Optional parameters: n/a 303 304 Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32 305 306 JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON 307 is written in UTF-8, JSON is 8bit compatible. When JSON is 308 written in UTF-16 or UTF-32, the binary content-transfer-encoding 309 must be used. 310 311 Security considerations: 312 313 Generally there are security issues with scripting languages. JSON 314 is a subset of JavaScript, but it is a safe subset that excludes 315 assignment and invocation. 316 317 A JSON text can be safely passed into JavaScript's eval() function 318 (which compiles and executes a string) if all the characters not 319 enclosed in strings are in the set of characters that form JSON 320 tokens. This can be quickly determined in JavaScript with two 321 regular expressions and calls to the test and replace methods. 322 323 var my_JSON_object = !(/[^,:{}\[\]0-9.\-+Eaeflnr-u \n\r\t]/.test( 324 text.replace(/"(\\.|[^"\\])*"/g, ''))) && 325 eval('(' + text + ')'); 326 327 Interoperability considerations: n/a 328 329 Published specification: RFC 4627 330 331 332 333 334 335 336 337 338Crockford Informational [Page 6] 339 340RFC 4627 JSON July 2006 341 342 343 Applications that use this media type: 344 345 JSON has been used to exchange data between applications written 346 in all of these programming languages: ActionScript, C, C#, 347 ColdFusion, Common Lisp, E, Erlang, Java, JavaScript, Lua, 348 Objective CAML, Perl, PHP, Python, Rebol, Ruby, and Scheme. 349 350 Additional information: 351 352 Magic number(s): n/a 353 File extension(s): .json 354 Macintosh file type code(s): TEXT 355 356 Person & email address to contact for further information: 357 Douglas Crockford 358 douglas@crockford.com 359 360 Intended usage: COMMON 361 362 Restrictions on usage: none 363 364 Author: 365 Douglas Crockford 366 douglas@crockford.com 367 368 Change controller: 369 Douglas Crockford 370 douglas@crockford.com 371 3727. Security Considerations 373 374 See Security Considerations in Section 6. 375 3768. Examples 377 378 This is a JSON object: 379 380 { 381 "Image": { 382 "Width": 800, 383 "Height": 600, 384 "Title": "View from 15th Floor", 385 "Thumbnail": { 386 "Url": "http://www.example.com/image/481989943", 387 "Height": 125, 388 "Width": "100" 389 }, 390 "IDs": [116, 943, 234, 38793] 391 392 393 394Crockford Informational [Page 7] 395 396RFC 4627 JSON July 2006 397 398 399 } 400 } 401 402 Its Image member is an object whose Thumbnail member is an object 403 and whose IDs member is an array of numbers. 404 405 This is a JSON array containing two objects: 406 407 [ 408 { 409 "precision": "zip", 410 "Latitude": 37.7668, 411 "Longitude": -122.3959, 412 "Address": "", 413 "City": "SAN FRANCISCO", 414 "State": "CA", 415 "Zip": "94107", 416 "Country": "US" 417 }, 418 { 419 "precision": "zip", 420 "Latitude": 37.371991, 421 "Longitude": -122.026020, 422 "Address": "", 423 "City": "SUNNYVALE", 424 "State": "CA", 425 "Zip": "94085", 426 "Country": "US" 427 } 428 ] 429 4309. References 431 4329.1. Normative References 433 434 [ECMA] European Computer Manufacturers Association, "ECMAScript 435 Language Specification 3rd Edition", December 1999, 436 <http://www.ecma-international.org/publications/files/ 437 ecma-st/ECMA-262.pdf>. 438 439 [RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20, 440 October 1969. 441 442 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 443 Requirement Levels", BCP 14, RFC 2119, March 1997. 444 445 [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 446 Specifications: ABNF", RFC 4234, October 2005. 447 448 449 450Crockford Informational [Page 8] 451 452RFC 4627 JSON July 2006 453 454 455 [UNICODE] The Unicode Consortium, "The Unicode Standard Version 4.0", 456 2003, <http://www.unicode.org/versions/Unicode4.1.0/>. 457 458Author's Address 459 460 Douglas Crockford 461 JSON.org 462 EMail: douglas@crockford.com 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506Crockford Informational [Page 9] 507 508RFC 4627 JSON July 2006 509 510 511Full Copyright Statement 512 513 Copyright (C) The Internet Society (2006). 514 515 This document is subject to the rights, licenses and restrictions 516 contained in BCP 78, and except as set forth therein, the authors 517 retain all their rights. 518 519 This document and the information contained herein are provided on an 520 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 521 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 522 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 523 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 524 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 525 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 526 527Intellectual Property 528 529 The IETF takes no position regarding the validity or scope of any 530 Intellectual Property Rights or other rights that might be claimed to 531 pertain to the implementation or use of the technology described in 532 this document or the extent to which any license under such rights 533 might or might not be available; nor does it represent that it has 534 made any independent effort to identify any such rights. Information 535 on the procedures with respect to rights in RFC documents can be 536 found in BCP 78 and BCP 79. 537 538 Copies of IPR disclosures made to the IETF Secretariat and any 539 assurances of licenses to be made available, or the result of an 540 attempt made to obtain a general license or permission for the use of 541 such proprietary rights by implementers or users of this 542 specification can be obtained from the IETF on-line IPR repository at 543 http://www.ietf.org/ipr. 544 545 The IETF invites any interested party to bring to its attention any 546 copyrights, patents or patent applications, or other proprietary 547 rights that may cover technology that may be required to implement 548 this standard. Please address the information to the IETF at 549 ietf-ipr@ietf.org. 550 551Acknowledgement 552 553 Funding for the RFC Editor function is provided by the IETF 554 Administrative Support Activity (IASA). 555 556 557 558 559 560 561 562Crockford Informational [Page 10] 563 564