JSON

Standards

After RFC 4627 had been available as its "informational" specification since 2006, JSON was first standardized in 2013, as ECMA-404. RFC 8259, published in 2017, is the current version of the Internet Standard STD 90, and it remains consistent with ECMA-404. That same year, JSON was also standardized as ISO/IEC 21778:2017. The ECMA and ISO/IEC standards describe only the allowed syntax, whereas the RFC covers some security and interoperability considerations.

History

JSON grew out of a need for a real-time server-to-browser session communication protocol without using browser plugins such as Flash or Java applets, the dominant methods used in the early 2000s.

Crockford first specified and popularized the JSON format. The acronym originated at State Software, a company cofounded by Crockford and others in March 2001. The cofounders agreed to build a system that used standard browser capabilities and provided an abstraction layer for Web developers to create stateful Web applications that had a persistent duplex connection to a Web server by holding two Hypertext Transfer Protocol (HTTP) connections open and recycling them before standard browser time-outs if no further data were exchanged. The cofounders had a round-table discussion and voted on whether to call the data format JSML (JavaScript Markup Language) or JSON (JavaScript Object Notation), as well as under what license type to make it available. The JSON.org website was launched in 2001. In December 2005, Yahoo! began offering some of its Web services in JSON.

A precursor to the JSON libraries was used in a children's digital asset trading game project named Cartoon Orbit at Communities.com which used a browser side plug-in with a proprietary messaging format to manipulate DHTML elements. Upon discovery of early Ajax capabilities, digiGroups, Noosh, and others used frames to pass information into the user browsers' visual field without refreshing a Web application's visual context, realizing real-time rich Web applications using only the standard HTTP, HTML, and JavaScript capabilities of Netscape 4.0.5+ and Internet Explorer 5+. Crockford then found that JavaScript could be used as an object-based messaging format for such a system. The system was sold to Sun Microsystems, Amazon.com, and EDS.

JSON was based on a subset of the JavaScript scripting language (specifically, Standard ECMA-262 3rd Edition—December 1999) and is commonly used with JavaScript, but it is a language-independent data format. Code for parsing and generating JSON data is readily available in many programming languages. JSON's website lists JSON libraries by language.

In October 2013, Ecma International published the first edition of its JSON standard ECMA-404. That same year, RFC 7158 used ECMA-404 as a reference. In 2014, RFC 7159 became the main reference for JSON's Internet uses, superseding RFC 4627 and RFC 7158 (but preserving ECMA-262 and ECMA-404 as main references). In November 2017, ISO/IEC JTC 1/SC 22 published ISO/IEC 21778:2017 as an international standard. On December 13, 2017, the Internet Engineering Task Force obsoleted RFC 7159 when it published RFC 8259, which is the current version of the Internet Standard STD 90.

Crockford added a clause to the JSON license stating, "The Software shall be used for Good, not Evil", in order to open-source the JSON libraries while mocking corporate lawyers and those who are overly pedantic. On the other hand, this clause led to license compatibility problems of the JSON license with other open-source licenses since open-source software and free software usually imply no restrictions on the purpose of use.

Syntax

The following example shows a possible JSON representation describing a person.

<span id="mwtw"></span><span class="p" id="mwuA">{</span> <span class="w" id="mwuQ"> </span><span class="nt" id="mwug">"first_name"</span><span class="p" id="mwuw">:</span><span class="w" id="mwvA"> </span><span class="s2" id="mwvQ">"John"</span><span class="p" id="mwvg">,</span> <span class="w" id="mwvw"> </span><span class="nt" id="mwwA">"last_name"</span><span class="p" id="mwwQ">:</span><span class="w" id="mwwg"> </span><span class="s2" id="mwww">"Smith"</span><span class="p" id="mwxA">,</span> <span class="w" id="mwxQ"> </span><span class="nt" id="mwxg">"is_alive"</span><span class="p" id="mwxw">:</span><span class="w" id="mwyA"> </span><span class="kc" id="mwyQ">true</span><span class="p" id="mwyg">,</span> <span class="w" id="mwyw"> </span><span class="nt" id="mwzA">"age"</span><span class="p" id="mwzQ">:</span><span class="w" id="mwzg"> </span><span class="mi" id="mwzw">27</span><span class="p" id="mw0A">,</span> <span class="w" id="mw0Q"> </span><span class="nt" id="mw0g">"address"</span><span class="p" id="mw0w">:</span><span class="w" id="mw1A"> </span><span class="p" id="mw1Q">{</span> <span class="w" id="mw1g"> </span><span class="nt" id="mw1w">"street_address"</span><span class="p" id="mw2A">:</span><span class="w" id="mw2Q"> </span><span class="s2" id="mw2g">"21 2nd Street"</span><span class="p" id="mw2w">,</span> <span class="w" id="mw3A"> </span><span class="nt" id="mw3Q">"city"</span><span class="p" id="mw3g">:</span><span class="w" id="mw3w"> </span><span class="s2" id="mw4A">"New York"</span><span class="p" id="mw4Q">,</span> <span class="w" id="mw4g"> </span><span class="nt" id="mw4w">"state"</span><span class="p" id="mw5A">:</span><span class="w" id="mw5Q"> </span><span class="s2" id="mw5g">"NY"</span><span class="p" id="mw5w">,</span> <span class="w" id="mw6A"> </span><span class="nt" id="mw6Q">"postal_code"</span><span class="p" id="mw6g">:</span><span class="w" id="mw6w"> </span><span class="s2" id="mw7A">"10021-3100"</span> <span class="w" id="mw7Q"> </span><span class="p" id="mw7g">},</span> <span class="w" id="mw7w"> </span><span class="nt" id="mw8A">"phone_numbers"</span><span class="p" id="mw8Q">:</span><span class="w" id="mw8g"> </span><span class="p" id="mw8w">[</span> <span class="w" id="mw9A"> </span><span class="p" id="mw9Q">{</span> <span class="w" id="mw9g"> </span><span class="nt" id="mw9w">"type"</span><span class="p" id="mw-A">:</span><span class="w" id="mw-Q"> </span><span class="s2" id="mw-g">"home"</span><span class="p" id="mw-w">,</span> <span class="w" id="mw_A"> </span><span class="nt" id="mw_Q">"number"</span><span class="p" id="mw_g">:</span><span class="w" id="mw_w"> </span><span class="s2" id="mwAQA">"212 555-1234"</span> <span class="w" id="mwAQE"> </span><span class="p" id="mwAQI">},</span> <span class="w" id="mwAQM"> </span><span class="p" id="mwAQQ">{</span> <span class="w" id="mwAQU"> </span><span class="nt" id="mwAQY">"type"</span><span class="p" id="mwAQc">:</span><span class="w" id="mwAQg"> </span><span class="s2" id="mwAQk">"office"</span><span class="p" id="mwAQo">,</span> <span class="w" id="mwAQs"> </span><span class="nt" id="mwAQw">"number"</span><span class="p" id="mwAQ0">:</span><span class="w" id="mwAQ4"> </span><span class="s2" id="mwAQ8">"646 555-4567"</span> <span class="w" id="mwARA"> </span><span class="p" id="mwARE">}</span> <span class="w" id="mwARI"> </span><span class="p" id="mwARM">],</span> <span class="w" id="mwARQ"> </span><span class="nt" id="mwARU">"children"</span><span class="p" id="mwARY">:</span><span class="w" id="mwARc"> </span><span class="p" id="mwARg">[</span> <span class="w" id="mwARk"> </span><span class="s2" id="mwARo">"Catherine"</span><span class="p" id="mwARs">,</span> <span class="w" id="mwARw"> </span><span class="s2" id="mwAR0">"Thomas"</span><span class="p" id="mwAR4">,</span> <span class="w" id="mwAR8"> </span><span class="s2" id="mwASA">"Trevor"</span> <span class="w" id="mwASE"> </span><span class="p" id="mwASI">],</span> <span class="w" id="mwASM"> </span><span class="nt" id="mwASQ">"spouse"</span><span class="p" id="mwASU">:</span><span class="w" id="mwASY"> </span><span class="kc" id="mwASc">null</span> <span class="p" id="mwASg">}</span>

Character encoding

Although Crockford originally asserted that JSON is a strict subset of JavaScript and ECMAScript, their specification actually allows valid JSON documents that are not valid JavaScript; JSON allows the Unicode line terminators U+2028 LINE SEPARATOR and U+2029 PARAGRAPH SEPARATOR to appear unescaped in quoted strings, while ECMAScript 2018 and older do not. This is a consequence of JSON disallowing only "control characters". For maximum portability, these characters are backslash-escaped.

JSON exchange in an open ecosystem must be encoded in UTF-8. The encoding supports the full Unicode character set, including those characters outside the Basic Multilingual Plane (U+0000 to U+FFFF). However, if escaped, those characters must be written using UTF-16 surrogate pairs. For example, to include the Emoji character U+1F610 😐 NEUTRAL FACE in JSON:

<span id="mwAU4"></span><span class="p" id="mwAU8">{</span><span class="w" id="mwAVA"> </span><span class="nt" id="mwAVE">"face"</span><span class="p" id="mwAVI">:</span><span class="w" id="mwAVM"> </span><span class="s2" id="mwAVQ">"😐"</span><span class="w" id="mwAVU"> </span><span class="p" id="mwAVY">}</span>

Or:

<span id="mwAVo"></span><span class="p" id="mwAVs">{</span><span class="w" id="mwAVw"> </span><span class="nt" id="mwAV0">"face"</span><span class="p" id="mwAV4">:</span><span class="w" id="mwAV8"> </span><span class="s2" id="mwAWA">"\uD83D\uDE10"</span><span class="w" id="mwAWE"> </span><span class="p" id="mwAWI">}</span>

JSON became a strict subset of ECMAScript as of the language's 2019 revision.

Data types

JSON's basic data types are:

• Number: a signed decimal number that may contain a fractional part and may use exponential E notation but cannot include non-numbers such as NaN. The format makes no distinction between integer and floating-point. JavaScript uses IEEE-754 double-precision floating-point format for all its numeric values (later also supporting BigInt), but other languages implementing JSON may encode numbers differently.
• String: a sequence of zero or more Unicode characters. Strings are delimited with double quotation marks and support a backslash escaping syntax.
• Boolean: either of the values true or false
• Array: an ordered list of zero or more elements, each of which may be of any type. Arrays use square bracket notation with comma-separated elements.
• Object: a collection of name–value pairs where the names (also called keys) are strings. The current ECMA standard states, "The JSON syntax does not impose any restrictions on the strings used as names, does not require that name strings be unique, and does not assign any significance to the ordering of name/value pairs." Objects are delimited with curly brackets and use commas to separate each pair, while within each pair, the colon ":" character separates the key or name from its value.
• null: an empty value, using the word null

Whitespace is allowed and ignored around or between syntactic elements (values and punctuation, but not within a string value). Four specific characters are considered whitespace for this purpose: space, horizontal tab, line feed, and carriage return. In particular, the byte order mark must not be generated by a conforming implementation (though it may be accepted when parsing JSON).

Early versions of JSON (such as specified by RFC 4627) required that a valid JSON text must consist of only an object or an array type, which could contain other types within them. This restriction was dropped in RFC 7158, where a JSON text was redefined as any serialized value.

Numbers in JSON are agnostic with regard to their representation within programming languages. While this allows for numbers of arbitrary precision to be serialized, it may lead to portability issues. For example, since no differentiation is made between integer and floating-point values, some implementations may treat 42, 42.0, and 4.2E+1 as the same number, while others may not. The JSON standard makes no requirements regarding implementation details such as overflow, underflow, loss of precision, rounding, or signed zeros, but it does recommend expecting no more than IEEE 754 binary64 precision for "good interoperability". There is no inherent precision loss in serializing a machine-level binary representation of a floating-point number (like binary64) into a human-readable decimal representation (like numbers in JSON) and back; there exist published algorithms to do this conversion exactly and optimally.

Comments

JSON does not provide syntax for comments. Comments were intentionally excluded from JSON. In 2012, Douglas Crockford described their design decision thus: "I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability."

Lint

JSON disallows "trailing commas", a comma after the last value inside a data structure. Trailing commas are a common feature of JSON derivatives to improve ease of use.

Interoperability

RFC 8259 describes certain aspects of JSON syntax that, while legal per the specifications, can cause interoperability problems.

• Certain JSON implementations only accept JSON texts representing an object or an array. For interoperability, applications interchanging JSON should transmit messages that are objects or arrays.
• The specifications allow JSON objects that contain multiple members with the same name. The behavior of implementations processing objects with duplicate names is unpredictable. For interoperability, applications should avoid duplicate names when transmitting JSON objects.
• The specifications specifically say that the order of members in JSON objects is not significant. For interoperability, applications should avoid assigning meaning to member ordering even if the parsing software makes that ordering visible.
• While the specifications place no limits on the magnitude or precision of JSON number literals, the widely used JavaScript implementation stores them as IEEE754 "binary64" quantities. For interoperability, applications should avoid transmitting numbers that cannot be represented in this way, for example, 1E400 or 3.141592653589793238462643383279.
• Earlier IETF specifications for JSON did not require UTF-8, but RFC 8259 requires JSON text exchanged between systems that are not part of a closed ecosystem to be encoded in UTF-8.
• The specifications do not forbid transmitting byte sequences that incorrectly represent Unicode characters. For interoperability, applications should transmit messages containing no such byte sequences.
• The specification does not constrain how applications go about comparing Unicode strings. For interoperability, applications should always perform such comparisons code unit by code unit.

In 2015, the IETF published RFC 7493, describing the "I-JSON Message Format", a restricted profile of JSON that constrains the syntax and processing of JSON to avoid, as much as possible, these interoperability issues.

Semantics

While JSON provides a syntactic framework for data interchange, unambiguous data interchange also requires agreement between producer and consumer on the semantics of specific use of the JSON syntax. One example of where such an agreement is necessary is the serialization of data types that are not part of the JSON standard, for example, dates and regular expressions.

Metadata and schema

The official MIME type for JSON text is application/json, and most modern implementations have adopted this. Legacy MIME types include text/json, text/x-json, and text/javascript. The standard filename extension is .json.

JSON Schema specifies a JSON-based format to define the structure of JSON data for validation, documentation, and interaction control. It provides a contract for the JSON data required by a given application and how that data can be modified. JSON Schema is based on the concepts from XML Schema (XSD) but is JSON-based. As in XSD, the same serialization/deserialization tools can be used both for the schema and data, and it is self-describing. It is specified in an Internet Draft at the IETF, with the latest version as of 2024 being "Draft 2020-12". There are several validators available for different programming languages, each with varying levels of conformance.

The JSON standard does not support object references, but an IETF draft standard for JSON-based object references exists.

Uses

JSON-RPC is a remote procedure call (RPC) protocol built on JSON, as a replacement for XML-RPC or SOAP. It is a simple protocol that defines only a handful of data types and commands. JSON-RPC lets a system send notifications (information to the server that does not require a response) and multiple calls to the server that can be answered out of order.

Asynchronous JavaScript and JSON (or AJAJ) refers to the same dynamic web page methodology as Ajax, but instead of XML, JSON is the data format. AJAJ is a web development technique that provides for the ability of a web page to request new data after it has loaded into the web browser. Typically, it renders new data from the server in response to user actions on that web page. For example, what the user types into a search box, client-side code then sends to the server, which immediately responds with a drop-down list of matching database items.

JSON has seen ad hoc usage as a configuration language, despite lacking native support for comments (see § Comments).

MongoDB uses JSON-like data for its document-oriented database.

Some relational databases have added support for native JSON data types, such as JSONB in PostgreSQL and JSON in MySQL. This allows developers to insert JSON data directly without having to convert it to another format.

Safety

JSON being a subset of JavaScript can lead to the misconception that it is safe to pass JSON texts to the JavaScript eval() function. This is not safe, due to certain valid JSON texts, specifically those containing U+2028 LINE SEPARATOR or U+2029 PARAGRAPH SEPARATOR, not being valid JavaScript code until JavaScript specifications were updated in 2019, and so older engines may not support it. To avoid the many pitfalls caused by executing arbitrary code from the Internet, a new function, JSON.parse(), was first added to the fifth edition of ECMAScript, which as of 2017 is supported by all major browsers. For non-supported browsers, an API-compatible JavaScript library is provided by Douglas Crockford. In addition, the TC39 proposal "Subsume JSON" made ECMAScript a strict JSON superset as of the language's 2019 revision. Various JSON parser implementations have suffered from denial-of-service attack and mass assignment vulnerability.

Alternatives

JSON is promoted as a low-overhead alternative to XML as both of these formats have widespread support for creation, reading, and decoding in the real-world situations where they are commonly used. Depending on the specific use-case, JSON alternatives include:

• For textual formats, CSV and supersets of JSON (see below). Ion also offers a textual format that's a JSON superset (wider range of primary types, annotations, comments, and allowing trailing commas).
• For faster processing at the cost of human-readability, data interchange formats that can express all JSON objects (i.e. that have a data model that is a superset of JSON's) include CBOR (an IETF RFC standard) and Ion binary. Google Protocol Buffers can also fill this niche due to the ability to be parsed without a schema, but it is not intended as an interchange language. In addition, databases such as SQLite and PostgreSQL have their own internal binary representations called "JSONB", not intended for outside use.

XML

XML has been used to describe structured data and to serialize objects. Various XML-based protocols exist to represent the same kind of data structures as JSON for the same kind of data interchange purposes. Data can be encoded in XML in several ways. The most expansive form using tag pairs results in a much larger (in character count) representation than JSON, but if data is stored in attributes and short tag form where the closing tag is replaced with />, the representation is often about the same size as JSON or just a little larger. However, an XML attribute can only have a single value and each attribute can appear at most once on each element.

XML separates data from metadata (via the use of elements and attributes), while JSON does not have such a concept.

Another key difference is the addressing of values. JSON has objects with a simple key-to-value mapping, whereas in XML addressing happens on nodes, each of which receives a unique ID via the XML processor. Additionally, the XML standard defines a common attribute xml:id, that can be used by the user, to set an ID explicitly.

XML tag names cannot contain any of the characters !"#$%&'()*+,/;<=>?@[\]^`{|}~, nor a space character, and cannot begin with -, ., or a numeric digit, whereas JSON keys can (even if quotation mark and backslash must be escaped).

XML values are strings of characters, with no built-in type safety. XML has the concept of schema, that permits strong typing, user-defined types, predefined tags, and formal structure, allowing for formal validation of an XML stream. JSON has several types built-in and has a similar schema concept in JSON Schema.

XML supports comments, while JSON does not.

Supersets

Support for comments and other features have been deemed useful, which has led to several nonstandard JSON supersets being created. Among them are HJSON, HOCON, and JSON5 (which despite its name, is not the fifth version of JSON).

YAML

YAML version 1.2 is a superset of JSON; prior versions were not strictly compatible. For example, escaping a slash / with a backslash \ is valid in JSON, but was not valid in YAML. YAML supports comments, while JSON does not.

CSON

CSON ("CoffeeScript Object Notation") uses significant indentation and unquoted keys, and assumes an outer object declaration. It was used for configuring GitHub's Atom text editor.

There is also an unrelated project called CSON ("Cursive Script Object Notation") that is more syntactically similar to JSON.

HOCON

HOCON ("Human-Optimized Config Object Notation") is a format for human-readable data, and a superset of JSON. The uses of HOCON are:

• It is used mostly along with the Play Framework, and is developed by Lightbend.
• It is also supported as a configuration format for .NET projects via Akka.NET and Puppet.
• TIBCO Streaming: HOCON is the primary configuration file format for the TIBCO Streaming family of products (StreamBase, LiveView, and Artifact Management Server) as of TIBCO Streaming Release 10.
• It is also the primary configuration file format for several subsystems of Exabeam Advanced Analytics.
• Jitsi uses it as the "new" config system and .properties-Files as fallback

JSON5

JSON5 ("JSON5 Data Interchange Format") is an extension of JSON syntax that, like JSON, is also valid JavaScript syntax. The specification was started in 2012 and finished in 2018 with version 1.0.0. The main differences to JSON syntax are:

• Optional trailing commas
• Unquoted object keys
• Single quoted and multiline strings
• Additional number formats
• Comments

JSON5 syntax is supported in some software as an extension of JSON syntax, for instance in SQLite.

JSONC

JSONC (JSON with Comments) is a subset of JSON5 used in Microsoft's Visual Studio Code:

• supports single-line comments (//) and block comments (/* */)
• accepts trailing commas, but they are discouraged and the editor will display a warning

Derivatives

Several serialization formats have been built on or from the JSON specification. Examples include

• GeoJSON, a format designed for representing simple geographical features
• JSON-LD, a method of encoding linked data using JSON
• JSON-RPC, a remote procedure call protocol encoded in JSON
• JsonML, a lightweight markup language used to map between XML and JSON
• Smile (data interchange format)
• UBJSON, a binary computer data interchange format imitating JSON, but requiring fewer bytes of data
• Jsonnet is a prototype-based domain-specific language that produces JSON files. All JSON documents are valid Jsonnet programs that will be emitted unchanged when run. Jsonnet extends JSON by supporting variables, imports, loops, comments, etc. Jsonnet is used as a configuration language for cloud infrastructure engineering.