rfc4627.txt 16 KB

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