564 lines
16 KiB
Plaintext
564 lines
16 KiB
Plaintext
|
||
|
||
|
||
|
||
|
||
|
||
Network Working Group D. Crockford
|
||
Request for Comments: 4627 JSON.org
|
||
Category: Informational July 2006
|
||
|
||
|
||
The application/json Media Type for JavaScript Object Notation (JSON)
|
||
|
||
Status of This Memo
|
||
|
||
This memo provides information for the Internet community. It does
|
||
not specify an Internet standard of any kind. Distribution of this
|
||
memo is unlimited.
|
||
|
||
Copyright Notice
|
||
|
||
Copyright (C) The Internet Society (2006).
|
||
|
||
Abstract
|
||
|
||
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.
|
||
|
||
1. Introduction
|
||
|
||
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 [ECMA].
|
||
|
||
JSON can represent four primitive types (strings, numbers, booleans,
|
||
and null) and two structured types (objects and arrays).
|
||
|
||
A string is a sequence of zero or more Unicode characters [UNICODE].
|
||
|
||
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.
|
||
|
||
An array is an ordered sequence of zero or more values.
|
||
|
||
The terms "object" and "array" come from the conventions of
|
||
JavaScript.
|
||
|
||
JSON's design goals were for it to be minimal, portable, textual, and
|
||
a subset of JavaScript.
|
||
|
||
|
||
|
||
Crockford Informational [Page 1]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
1.1. Conventions Used in This Document
|
||
|
||
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 [RFC2119].
|
||
|
||
The grammatical rules in this document are to be interpreted as
|
||
described in [RFC4234].
|
||
|
||
2. JSON Grammar
|
||
|
||
A JSON text is a sequence of tokens. The set of tokens includes six
|
||
structural characters, strings, numbers, and three literal names.
|
||
|
||
A JSON text is a serialized object or array.
|
||
|
||
JSON-text = object / array
|
||
|
||
These are the six structural characters:
|
||
|
||
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
|
||
|
||
Insignificant whitespace is allowed before or after any of the six
|
||
structural characters.
|
||
|
||
ws = *(
|
||
%x20 / ; Space
|
||
%x09 / ; Horizontal tab
|
||
%x0A / ; Line feed or New line
|
||
%x0D ; Carriage return
|
||
)
|
||
|
||
2.1. Values
|
||
|
||
A JSON value MUST be an object, array, number, or string, or one of
|
||
the following three literal names:
|
||
|
||
false null true
|
||
|
||
|
||
|
||
Crockford Informational [Page 2]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
The literal names MUST be lowercase. No other literal names are
|
||
allowed.
|
||
|
||
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
|
||
|
||
2.2. Objects
|
||
|
||
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.
|
||
|
||
object = begin-object [ member *( value-separator member ) ]
|
||
end-object
|
||
|
||
member = string name-separator value
|
||
|
||
2.3. Arrays
|
||
|
||
An array structure is represented as square brackets surrounding zero
|
||
or more values (or elements). Elements are separated by commas.
|
||
|
||
array = begin-array [ value *( value-separator value ) ] end-array
|
||
|
||
2.4. Numbers
|
||
|
||
The representation of numbers is similar to that used in most
|
||
programming languages. A number 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.
|
||
|
||
Octal and hex forms are not allowed. Leading zeros are not allowed.
|
||
|
||
A fraction part is a decimal point followed by one or more digits.
|
||
|
||
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.
|
||
|
||
Numeric values that cannot be represented as sequences of digits
|
||
(such as Infinity and NaN) are not permitted.
|
||
|
||
|
||
|
||
Crockford Informational [Page 3]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
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
|
||
|
||
2.5. Strings
|
||
|
||
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).
|
||
|
||
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".
|
||
|
||
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 "\\".
|
||
|
||
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".
|
||
|
||
|
||
|
||
Crockford Informational [Page 4]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
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
|
||
|
||
3. Encoding
|
||
|
||
JSON text SHALL be encoded in Unicode. The default encoding is
|
||
UTF-8.
|
||
|
||
Since the first two characters of a JSON text will always be ASCII
|
||
characters [RFC0020], it is possible to determine whether an octet
|
||
stream is UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE) by looking
|
||
at the pattern of nulls in the first four octets.
|
||
|
||
00 00 00 xx UTF-32BE
|
||
00 xx 00 xx UTF-16BE
|
||
xx 00 00 00 UTF-32LE
|
||
xx 00 xx 00 UTF-16LE
|
||
xx xx xx xx UTF-8
|
||
|
||
4. Parsers
|
||
|
||
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.
|
||
|
||
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 of numbers.
|
||
An implementation may set limits on the length and character contents
|
||
of strings.
|
||
|
||
|
||
|
||
|
||
Crockford Informational [Page 5]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
5. Generators
|
||
|
||
A JSON generator produces JSON text. The resulting text MUST
|
||
strictly conform to the JSON grammar.
|
||
|
||
6. IANA Considerations
|
||
|
||
The MIME media type for JSON text is application/json.
|
||
|
||
Type name: application
|
||
|
||
Subtype name: json
|
||
|
||
Required parameters: n/a
|
||
|
||
Optional parameters: n/a
|
||
|
||
Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32
|
||
|
||
JSON may be represented using UTF-8, UTF-16, or UTF-32. When JSON
|
||
is written in UTF-8, JSON is 8bit compatible. When JSON is
|
||
written in UTF-16 or UTF-32, the binary content-transfer-encoding
|
||
must be used.
|
||
|
||
Security considerations:
|
||
|
||
Generally there are security issues with scripting languages. JSON
|
||
is a subset of JavaScript, but it is a safe subset that excludes
|
||
assignment and invocation.
|
||
|
||
A JSON text can be safely passed into JavaScript's eval() function
|
||
(which compiles and executes a string) if all the characters not
|
||
enclosed in strings are in the set of characters that form JSON
|
||
tokens. This can be quickly determined in JavaScript with two
|
||
regular expressions and calls to the test and replace methods.
|
||
|
||
var my_JSON_object = !(/[^,:{}\[\]0-9.\-+Eaeflnr-u \n\r\t]/.test(
|
||
text.replace(/"(\\.|[^"\\])*"/g, ''))) &&
|
||
eval('(' + text + ')');
|
||
|
||
Interoperability considerations: n/a
|
||
|
||
Published specification: RFC 4627
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Crockford Informational [Page 6]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
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#,
|
||
ColdFusion, Common Lisp, E, Erlang, Java, JavaScript, Lua,
|
||
Objective CAML, Perl, PHP, Python, Rebol, Ruby, and Scheme.
|
||
|
||
Additional information:
|
||
|
||
Magic number(s): n/a
|
||
File extension(s): .json
|
||
Macintosh file type code(s): TEXT
|
||
|
||
Person & email address to contact for further information:
|
||
Douglas Crockford
|
||
douglas@crockford.com
|
||
|
||
Intended usage: COMMON
|
||
|
||
Restrictions on usage: none
|
||
|
||
Author:
|
||
Douglas Crockford
|
||
douglas@crockford.com
|
||
|
||
Change controller:
|
||
Douglas Crockford
|
||
douglas@crockford.com
|
||
|
||
7. Security Considerations
|
||
|
||
See Security Considerations in Section 6.
|
||
|
||
8. Examples
|
||
|
||
This is a JSON object:
|
||
|
||
{
|
||
"Image": {
|
||
"Width": 800,
|
||
"Height": 600,
|
||
"Title": "View from 15th Floor",
|
||
"Thumbnail": {
|
||
"Url": "http://www.example.com/image/481989943",
|
||
"Height": 125,
|
||
"Width": "100"
|
||
},
|
||
"IDs": [116, 943, 234, 38793]
|
||
|
||
|
||
|
||
Crockford Informational [Page 7]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
}
|
||
}
|
||
|
||
Its Image member is an object whose Thumbnail member is an object
|
||
and whose IDs member is an array of numbers.
|
||
|
||
This is a JSON array containing two objects:
|
||
|
||
[
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
|
||
9. References
|
||
|
||
9.1. Normative References
|
||
|
||
[ECMA] European Computer Manufacturers Association, "ECMAScript
|
||
Language Specification 3rd Edition", December 1999,
|
||
<http://www.ecma-international.org/publications/files/
|
||
ecma-st/ECMA-262.pdf>.
|
||
|
||
[RFC0020] Cerf, V., "ASCII format for network interchange", RFC 20,
|
||
October 1969.
|
||
|
||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
|
||
Requirement Levels", BCP 14, RFC 2119, March 1997.
|
||
|
||
[RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
|
||
Specifications: ABNF", RFC 4234, October 2005.
|
||
|
||
|
||
|
||
Crockford Informational [Page 8]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
[UNICODE] The Unicode Consortium, "The Unicode Standard Version 4.0",
|
||
2003, <http://www.unicode.org/versions/Unicode4.1.0/>.
|
||
|
||
Author's Address
|
||
|
||
Douglas Crockford
|
||
JSON.org
|
||
EMail: douglas@crockford.com
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Crockford Informational [Page 9]
|
||
|
||
RFC 4627 JSON July 2006
|
||
|
||
|
||
Full Copyright Statement
|
||
|
||
Copyright (C) The Internet Society (2006).
|
||
|
||
This document is subject to the rights, licenses and restrictions
|
||
contained in BCP 78, and except as set forth therein, the authors
|
||
retain all their rights.
|
||
|
||
This document and the information contained herein are provided on an
|
||
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
|
||
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
|
||
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
|
||
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
|
||
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
|
||
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
||
|
||
Intellectual Property
|
||
|
||
The IETF takes no position regarding the validity or scope of any
|
||
Intellectual Property Rights or other rights that might be claimed to
|
||
pertain to the implementation or use of the technology described in
|
||
this document or the extent to which any license under such rights
|
||
might or might not be available; nor does it represent that it has
|
||
made any independent effort to identify any such rights. Information
|
||
on the procedures with respect to rights in RFC documents can be
|
||
found in BCP 78 and BCP 79.
|
||
|
||
Copies of IPR disclosures made to the IETF Secretariat and any
|
||
assurances of licenses to be made available, or the result of an
|
||
attempt made to obtain a general license or permission for the use of
|
||
such proprietary rights by implementers or users of this
|
||
specification can be obtained from the IETF on-line IPR repository at
|
||
http://www.ietf.org/ipr.
|
||
|
||
The IETF invites any interested party to bring to its attention any
|
||
copyrights, patents or patent applications, or other proprietary
|
||
rights that may cover technology that may be required to implement
|
||
this standard. Please address the information to the IETF at
|
||
ietf-ipr@ietf.org.
|
||
|
||
Acknowledgement
|
||
|
||
Funding for the RFC Editor function is provided by the IETF
|
||
Administrative Support Activity (IASA).
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
Crockford Informational [Page 10]
|
||
|