One document matched: draft-ietf-json-rfc4627bis-10.xml

<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC0020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0020.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
<!ENTITY RFC4627 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4627.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc comments="no" ?>
<?rfc inline="no" ?>
<?rfc editing="no" ?>
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<rfc
category="std"
docName="draft-ietf-json-rfc4627bis-10"
ipr="pre5378Trust200902"
obsoletes="4627"
>

<front>
<title abbrev="JSON bis">The JSON Data Interchange Format</title>

<author fullname="Tim Bray" initials="T." surname="Bray" role="editor">
<organization>Google, Inc.</organization>
<address>
<email>tbray@textuality.com</email>
</address>
</author>

<date year="2013" month="December"/>

<area>Operations and Management</area>
<workgroup>JSON Working Group</workgroup>

<abstract>

<t>JavaScript Object Notation (JSON) is a lightweight, text-based,
language-independent data interchange format.  It was derived from
the ECMAScript Programming Language Standard.  JSON defines a small
set of formatting rules for the portable representation of structured
data.</t>
<t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t>

</abstract>

</front>

<middle>

<section title="Introduction">

<t>JavaScript Object Notation (JSON) is a text format for the
serialization of structured data.  It is derived from the object
literals of JavaScript, as defined in the ECMAScript Programming
Language Standard, Third Edition <xref target="ECMA-262"/>.</t>

<t>JSON can represent four primitive types (strings, numbers, booleans,
and null) and two structured types (objects and arrays).</t>

<t>A string is a sequence of zero or more Unicode characters <xref target="UNICODE"/>.</t>

<t>An object is an unordered collection of zero or more name/value
pairs, where a name is a string and a value is a string, number,
boolean, null, object, or array.</t>

<t>An array is an ordered sequence of zero or more values.</t>

<t>The terms "object" and "array" come from the conventions of
JavaScript.</t>

<t>JSON's design goals were for it to be minimal, portable, textual, and
a subset of JavaScript.</t>

<section title="Conventions Used in This Document">

<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119" />.</t>

<t>The grammatical rules in this document are to be interpreted as
described in <xref target="RFC5234" />.</t>

</section>

<section title="Specifications of JSON">
<t>This document is an update of <xref target="RFC4627" />, which described
JSON and registered the Media Type "application/json".</t>
<t>A description of JSON in ECMAScript terms appears in version 5.1 of
the ECMAScript specification <xref target="ECMA-262" />, section 15.12.
JSON is also described in <xref target="ECMA-404" />.
</t>

<t>All of the specifications of JSON syntax agree on the syntactic elements of
the language.</t>

</section>

<section title="Introduction to This Revision">
<t>In the years since the publication of RFC 4627, JSON has found very wide 
use. This experience has revealed certain patterns
which, while allowed by its specifications, have caused interoperability
problems.</t>
<t>Also, a small number of errata have been reported.</t>
<t>The revision's goal is to apply the errata, remove inconsistencies with
other specifications of JSON, and highlight practices which can lead to
interoperability problems.</t>
</section>

</section>

<section title="JSON Grammar">

<t>A JSON text is a sequence of tokens.  The set of tokens includes six
structural characters, strings, numbers, and three literal names.</t>

<t>A JSON text is a serialized value.  Note that certain previous
specifications of JSON constrained a JSON text to be an object or an array.
Implementations which generate only objects or arrays where a JSON text is
called for will be interoperable in the sense that all implementations will
accept these as conforming JSON texts.</t>

<figure><artwork>
   JSON-text = ws value ws
</artwork></figure>

<t>These are the six structural characters:</t>

<figure><artwork>
   begin-array     = ws %x5B ws  ; [ left square bracket

   begin-object    = ws %x7B ws  ; { left curly bracket

   end-array       = ws %x5D ws  ; ] right square bracket

   end-object      = ws %x7D ws  ; } right curly bracket

   name-separator  = ws %x3A ws  ; : colon

   value-separator = ws %x2C ws  ; , comma
</artwork></figure>

<t>Insignificant whitespace is allowed before or after any of the six
structural characters.</t>

<figure><artwork>
   ws = *(
           %x20 /              ; Space
           %x09 /              ; Horizontal tab
           %x0A /              ; Line feed or New line
           %x0D )              ; Carriage return
</artwork></figure>
</section>

<section title="Values">

<t>A JSON value MUST be an object, array, number, or string, or one of
the following three literal names:</t>

<figure><artwork>
   false null true
</artwork></figure>

<t>The literal names MUST be lowercase.  No other literal names are
allowed.</t>

<figure><artwork>
   value = false / null / true / object / array / number / string

   false = %x66.61.6c.73.65   ; false

   null  = %x6e.75.6c.6c      ; null

   true  = %x74.72.75.65      ; true
</artwork></figure>

</section>

<section title="Objects">

<t>An object structure is represented as a pair of curly brackets
surrounding zero or more name/value pairs (or members).  A name is a
string.  A single colon comes after each name, separating the name
from the value.  A single comma separates a value from a following
name.  The names within an object SHOULD be unique.</t>

<figure><artwork>
   object = begin-object [ member *( value-separator member ) ]
            end-object

   member = string name-separator value
</artwork></figure>

<t>An object whose names are all unique is interoperable in the
sense that all software implementations which receive
that object will agree on the name-value mappings. 
When the names within an object are not unique, the behavior of
software that receives such an object is unpredictable. Many implementations
report the last name/value pair only; other implementations report an error or
fail to parse the object; other implementations report all of the name/value
pairs, including duplicates.</t> 

<t>JSON parsing libraries have been observed to differ as to whether or not
they make the ordering of object members visible to
calling software. Implementations whose behavior does not depend on member
ordering will be interoperable in the sense that they will not be affected by
these differences.</t> 

</section>

<section title="Arrays">

<t>An array structure is represented as square brackets surrounding zero
or more values (or elements).  Elements are separated by commas.</t>

<figure><artwork>
array = begin-array [ value *( value-separator value ) ] end-array
</artwork></figure>

<t>There is no requirement that the values in an array be of the same type.</t>

</section>

<section title="Numbers">

<t>The representation of numbers is similar to that used in most
programming languages.  A number is represented in base 10 using decimal
digits. It contains an integer component that
may be prefixed with an optional minus sign, which may be followed by
a fraction part and/or an exponent part. Leading zeros are not allowed.</t>

<t>A fraction part is a decimal point followed by one or more digits.</t>

<t>An exponent part begins with the letter E in upper or lowercase,
which may be followed by a plus or minus sign.  The E and optional
sign are followed by one or more digits.</t>

<t>Numeric values that cannot be represented in the grammar below
(such as Infinity and NaN) are not permitted.</t>

<figure><artwork>
   number = [ minus ] int [ frac ] [ exp ]

   decimal-point = %x2E       ; .

   digit1-9 = %x31-39         ; 1-9

   e = %x65 / %x45            ; e E

   exp = e [ minus / plus ] 1*DIGIT

   frac = decimal-point 1*DIGIT

   int = zero / ( digit1-9 *DIGIT )

   minus = %x2D               ; -

   plus = %x2B                ; +

   zero = %x30                ; 0
</artwork></figure>

<t>This specification allows implementations to set
limits on the range and precision of numbers accepted. Since software which 
implements IEEE 754-2008 binary64 (double precision) numbers <xref
target="IEEE754"/> is generally available and widely used, good
interoperability can be achieved by implementations which expect no more
precision or range than these provide, in the sense that implementations will
approximate JSON numbers within the expected precision.  A JSON number 
such as 1E400 or 3.141592653589793238462643383279
may indicate potential interoperability problems since it suggests that the
software which created it it expected greater magnitude or precision than is
widely available.</t>

<t>Note that when such software 
is used, numbers which are integers and are in the range 
[-(2**53)+1, (2**53)-1]
are interoperable in the sense that implementations will agree exactly on
their numeric values.</t>

</section>

<section title="Strings">

<t>The representation of strings is similar to conventions used in the C
family of programming languages.  A string begins and ends with
quotation marks.  All Unicode characters may be placed within the
quotation marks except for the characters that must be escaped:
quotation mark, reverse solidus, and the control characters (U+0000
through U+001F).</t>

<t>Any character may be escaped.  If the character is in the Basic
Multilingual Plane (U+0000 through U+FFFF), then it may be
represented as a six-character sequence: a reverse solidus, followed
by the lowercase letter u, followed by four hexadecimal digits that
encode the character's code point.  The hexadecimal letters A though
F can be upper or lowercase.  So, for example, a string containing
only a single reverse solidus character may be represented as
"\u005C".</t>

<t>Alternatively, there are two-character sequence escape
representations of some popular characters.  So, for example, a
string containing only a single reverse solidus character may be
represented more compactly as "\\".</t>

<t>To escape an extended character that is not in the Basic Multilingual
Plane, the character is represented as a twelve-character sequence,
encoding the UTF-16 surrogate pair.  So, for example, a string
containing only the G clef character (U+1D11E) may be represented as
"\uD834\uDD1E".</t>

<figure><artwork>
   string = quotation-mark *char quotation-mark

   char = unescaped /
       escape (
           %x22 /          ; "    quotation mark  U+0022
           %x5C /          ; \    reverse solidus U+005C
           %x2F /          ; /    solidus         U+002F
           %x62 /          ; b    backspace       U+0008
           %x66 /          ; f    form feed       U+000C
           %x6E /          ; n    line feed       U+000A
           %x72 /          ; r    carriage return U+000D
           %x74 /          ; t    tab             U+0009
           %x75 4HEXDIG )  ; uXXXX                U+XXXX

   escape = %x5C              ; \

   quotation-mark = %x22      ; "

   unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
</artwork></figure>

</section>

<section title="String and Character Issues">

<section title="Character Encoding">
<t>JSON text SHALL be encoded in UTF-8, UTF-16, or UTF-32.  The default
encoding is UTF-8, and
JSON texts which are encoded in UTF-8 are interoperable in the sense that
they will be read successfully by the maximum number of implementations; there
are many implementations which cannot successfully read texts in other
encodings (such as UTF-16 and UTF-32).</t>
<t>Implementations MUST NOT add a byte order mark to the beginning of a JSON
text. In the interests of interoperability, implementations which parse JSON
texts MAY ignore the presence of a byte order mark rather than treating it as
an error.</t> 
</section>

<section anchor="unichars" title="Unicode Characters">

<t>When all the strings represented in a JSON text are composed
entirely of Unicode characters <xref target="UNICODE"/> (however escaped),
then that JSON text is interoperable in the sense that all
software implementations which parse it will agree on the contents
of names and of string values in objects and arrays.</t>
<t>However, the ABNF in this specification allows member names and
string values to contain bit sequences which cannot encode Unicode characters,
for example "\uDEAD" (a single unpaired UTF-16 surrogate).  Instances of this
have been observed, for example when a library truncates a UTF-16 string
without checking whether the truncation split a
surrogate pair.  The behavior of software which receives JSON texts containing
such values is unpredictable; for example, implementations might
return different values for the length of a string value, or even suffer 
fatal runtime exceptions.</t>
</section>

<section title="String Comparison">
<t>Software implementations are typically required to test names of object
members for equality.  Implementations which transform the textual
representation into sequences of Unicode code units, and then perform the
comparison numerically, code unit by code unit, are interoperable in the sense
that implementations will agree in all cases on equality or inequality of two
strings.  For example, implementations which compare strings with escaped 
characters unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not
equal.</t>
</section>

</section>

<section anchor="parsers" title="Parsers">

<t>A JSON parser transforms a JSON text into another representation.  A
JSON parser MUST accept all texts that conform to the JSON grammar.
A JSON parser MAY accept non-JSON forms or extensions.</t>

<t>An implementation may set limits on the size of texts that it
accepts.  An implementation may set limits on the maximum depth of
nesting.  An implementation may set limits on the range and precision of numbers.
An implementation may set limits on the length and character contents
of strings.</t>

</section>

<section title="Generators">

<t>A JSON generator produces JSON text.  The resulting text MUST
strictly conform to the JSON grammar.</t>

</section>

<section title="IANA Considerations" anchor="ianacons">
<t>The MIME media type for JSON text is application/json.

<list style='hanging' hangIndent='3'>
<t hangText='Type name:'>application</t>

<t hangText='Subtype name:'>json</t>

<t hangText='Required parameters:'>n/a</t>

<t hangText='Optional parameters:'>n/a</t>

<t hangText='Encoding considerations:'>binary</t>
<t hangText='Security considerations:'>See [this RFC], section 12.</t>
<t hangText='Interoperability considerations:'>Described in this document</t>
<t hangText='Published specification:'>This document</t>

<t hangText='Applications that use this media type:'>
JSON has been used to exchange data between applications written
in all of these programming languages: ActionScript, C, C#, Clojure,
ColdFusion, Common Lisp, E, Erlang, Go, Java, JavaScript, Lua,
Objective CAML, Perl, PHP, Python, Rebol, Ruby, Scala, and Scheme.</t>
<t hangText='Additional information:'>
Magic number(s): n/a<vspace/>
File extension(s): .json<vspace/>
Macintosh file type code(s): TEXT</t>
<t hangText='Person & email address to contact for further information:'>
IESG<vspace/>
<iesg@ietf.org></t>
<t hangText='Intended usage:'> COMMON</t>

<t hangText='Restrictions on usage:'>none</t>

<t hangText='Author:'>
Douglas Crockford<vspace/>
<douglas@crockford.com></t>
<t hangText='Change controller:'>
IESG<vspace/>
<iesg@ietf.org></t>

<t hangText='Note:'>
No "charset" parameter is defined for this registration.
Adding one really has no effect on compliant recipients.
</t>
</list>
</t>
</section>

<section title="Security Considerations">

<t>Generally there are security issues with scripting languages.  JSON
is a subset of JavaScript, but excludes
assignment and invocation.</t>

<t>Since JSON's syntax is borrowed from JavaScript, it is possible to use that
language's "eval()" function to parse JSON texts. This generally constitutes
an unacceptable security risk, since the text could contain executable code
along with data declarations.  
The same consideration applies to the use of eval()-like functions in any other
programming language in which JSON texts conform to that language's
syntax.</t>

</section>

<section anchor="examples" title="Examples">

<t>This is a JSON object:</t>

<figure><artwork>
   {
     "Image": {
         "Width":  800,
         "Height": 600,
         "Title":  "View from 15th Floor",
         "Thumbnail": {
             "Url":    "http://www.example.com/image/481989943",
             "Height": 125,
             "Width":  100
         },
         "Animated" : false,
         "IDs": [116, 943, 234, 38793]
       }
   }
</artwork></figure>

<t>Its Image member is an object whose Thumbnail member is an object
and whose IDs member is an array of numbers.</t>

<t>This is a JSON array containing two objects:</t>

<figure><artwork>
   [
     {
        "precision": "zip",
        "Latitude":  37.7668,
        "Longitude": -122.3959,
        "Address":   "",
        "City":      "SAN FRANCISCO",
        "State":     "CA",
        "Zip":       "94107",
        "Country":   "US"
     },
     {
        "precision": "zip",
        "Latitude":  37.371991,
        "Longitude": -122.026020,
        "Address":   "",
        "City":      "SUNNYVALE",
        "State":     "CA",
        "Zip":       "94085",
        "Country":   "US"
     }
   ]
</artwork></figure>

<t>Here are three small JSON texts containing only values:</t>
<figure><artwork>

"Hello world!"

42

true
</artwork></figure>

</section>
<section title="Contributors">
<t>RFC 4627 was written by Douglas Crockford. This document was constructed by
making a relatively small number of changes to that
document; thus the vast majority of the text here is his.</t>
</section>


</middle>

<back>

<references title="Normative References">

&RFC0020;
&RFC2119;
&RFC5234;

<reference anchor="UNICODE" target="http://www.unicode.org/versions/latest/">
<front>
<title abbrev="Unicode">The Unicode Standard</title>
<author>
<organization>The Unicode Consortium</organization>
<address />
</author>
<date year="2003-"/>
</front>
<annotation>Note that this reference is to the latest version of Unicode,
rather than to a specific release. It is not expected that future changes in
the UNICODE specification will impact the syntax of JSON.
</annotation>
</reference>

<reference anchor="IEEE754" target="http://grouper.ieee.org/groups/754/">
<front>
<title abbrev="IEEE 754">IEEE Standard for Floating-Point Arithmetic</title>
<author>
<organization>IEEE</organization>
<address />
</author>
<date year="2008"/>
</front>
</reference>

</references>

<references title="Informative References">
&RFC4627;
<reference anchor="ECMA-262" target="http://www.ecma-international.org/ecma-262/5.1/">
<front>
<title abbrev="ECMAScript 5.1">
ECMAScript Language Specification 5.1 Edition
</title>
<author>
<organization>European Computer Manufacturers Association</organization>
<address />
</author>
<date month="June" year="2011"/>
</front>
</reference>

<reference anchor="ECMA-404" target="http://www.ecma-international.org/publications/standards/Ecma-404.htm">
<front>
<title abbrev="ECMA JSON">
The JSON Data Interchange Format
</title>
<author>
<organization>Ecma International</organization>
<address />
</author>
<date month="October" year="2013"/>
</front>
</reference>

</references>
<section title="Changes from RFC 4627">

<t>This section lists changes between this document
and the text in RFC 4627.</t>

<t><list style="symbols">

<t>Changed title and abstract of document.</t>

<t>Change the reference to [UNICODE] to be be non-version-specific.</t>

<t>Added a "Specifications of JSON" section.</t>

<t>Added an "Introduction to this Revision" section.</t>

<t>Changed the definition of "JSON text" so that it can be any JSON value,
removing the constraint that it be an object or array.</t>

<t>Added language about duplicate object member names, member ordering, and
interoperability.</t>

<t>Clarified the absence of a requirement that values in an array be of the
same JSON type.</t>

<t>Applied erratum #607 from RFC 4627 to correctly align the artwork for the
definition of "object".</t>

<t>Changed "as sequences of digits" to "in the grammar below" in "Numbers"
section, and made base-10-ness explicit.</t>

<t>Added language about number interoperability as a function of 
IEEE754, and an IEEE754 reference.</t>

<t>Added language about interoperability and Unicode characters, and about
string comparisons.  To do this, turned the old "Encoding" section into a
"String and Character Issues" section, with three subsections: "Character
Encoding", "Unicode Characters" and "String Comparison".</t> 

<t>Changed guidance in "Parsers" section to point out that implementations may
set limits on the range "and precision" of numbers.</t>

<t>Updated and tidied the "IANA Considerations" section.</t>

<t>Made a real "Security Considerations" section, and lifted the
text out of the existing "IANA Considerations" section.</t>

<t>Applied erratum #3607 from RFC 4627 by removing the security consideration
that begins "A JSON text can be safely passed" and the JavaScript code that
went with that consideration.</t>

<t>Added a note to the "Security Considerations" section pointing out the
risks of using the "eval()" function in JavaScript or any other language in
which JSON texts conform to that language's syntax.</t>

<t>Added a note to IANA considerations clarifying the absence of a "charset"
parameter for the application/json media type.</t>

<t>Changed "100" to 100 and added a boolean field, both in the first
example.</t>

<t>Added examples of JSON texts which simple values, neither objects nor
arrays.</t>

<t>Added "Contributors" section crediting Douglas Crockford.</t>

<t>Added a reference to RFC4627.</t>

<t>Moved the ECMAScript reference from Normative to Informative, updated
it to reference ECMAScript 5.1, and added reference to ECMA 404.</t>

</list></t>

</section>

</back>
</rfc>