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