Dogcows Code - chaz/yoink/blob - src/Moof/yajl/rfc4627.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                       D. Crockford
   8 Request for Comments: 4627                                      JSON.org
   9 Category: Informational                                        July 2006
  10
  11
  12  The application/json Media Type for JavaScript Object Notation (JSON)
  13
  14 Status 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
  20 Copyright Notice
  21
  22    Copyright (C) The Internet Society (2006).
  23
  24 Abstract
  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
  32 1.  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
  58 Crockford                    Informational                      [Page 1]
  59 \f
  60 RFC 4627                          JSON                         July 2006
  61
  62
  63 1.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
  72 2.  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
 105 2.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
 114 Crockford                    Informational                      [Page 2]
 115 \f
 116 RFC 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
 130 2.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
 143 2.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
 150 2.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
 170 Crockford                    Informational                      [Page 3]
 171 \f
 172 RFC 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
 195 2.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
 226 Crockford                    Informational                      [Page 4]
 227 \f
 228 RFC 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
 251 3.  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
 267 4.  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
 282 Crockford                    Informational                      [Page 5]
 283 \f
 284 RFC 4627                          JSON                         July 2006
 285
 286
 287 5. Generators
 288
 289    A JSON generator produces JSON text.  The resulting text MUST
 290    strictly conform to the JSON grammar.
 291
 292 6. 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
 338 Crockford                    Informational                      [Page 6]
 339 \f
 340 RFC 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
 372 7. Security Considerations
 373
 374    See Security Considerations in Section 6.
 375
 376 8. 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
 394 Crockford                    Informational                      [Page 7]
 395 \f
 396 RFC 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
 430 9. References
 431
 432 9.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
 450 Crockford                    Informational                      [Page 8]
 451 \f
 452 RFC 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
 458 Author'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
 506 Crockford                    Informational                      [Page 9]
 507 \f
 508 RFC 4627                          JSON                         July 2006
 509
 510
 511 Full 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
 527 Intellectual 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
 551 Acknowledgement
 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
 562 Crockford                    Informational                     [Page 10]
 563 \f