JSON

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

{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 27,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}

Although Douglas Crockford originally asserted that JSON is a strict subset of JavaScript, his 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 does not.[24][25] This is a consequence of JSON disallowing only "control characters". For maximum portability, these characters should be backslash-escaped. This subtlety is important when generating JSONP.

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

{ "face": "😐" }
// or
{ "face": "\uD83D\uDE10" }

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 to expect 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, since there exist published algorithms to do this exactly and optimally.[26]

Comments were purposefully excluded from JSON. In 2012, Douglas Crockford described his 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." [23]

While JSON provides a syntactic framework for data interchange, unambiguous data interchange also requires agreement between producer and consumer on the semantics of a specific use of the JSON syntax.[27] One example of where such an agreement is necessary is the serialization of data types defined by the JavaScript syntax that are not part of the JSON standard, e.g. Date, Function, Regular Expression, and undefined.[note 2][28]

The official MIME type for JSON text is "application/json",[29] and most modern implementations have adopted this.

The unofficial MIME type "text/json" or the content-type "text/javascript" also get legacy support by many service providers, browsers, servers, web applications, libraries, frameworks, and APIs. Notable examples include the Google Search API,[30] Yahoo!,[30][31] Flickr,[30] Facebook API,[32] Lift framework,[33] Dojo Toolkit 0.4,[34] etc.

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.[35]

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 is self-describing. It is specified in an Internet Draft at the IETF, currently in 2019-09 draft, which was released on September 19, 2019.[36] There are several validators available for different programming languages,[37] each with varying levels of conformance.

There is no standard filename extension, but some have suggested .schema.json.[38]

Example JSON Schema (2019-09):

{
  "$schema": "http://json-schema.org/draft/2019-09/schema",
  "title": "Product",
  "type": "object",
  "required": ["id", "name", "price"],
  "properties": {
    "id": {
      "type": "number",
      "description": "Product identifier"
    },
    "name": {
      "type": "string",
      "description": "Name of the product"
    },
    "price": {
      "type": "number",
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "stock": {
      "type": "object",
      "properties": {
        "warehouse": {
          "type": "number"
        },
        "retail": {
          "type": "number"
        }
      }
    }
  }
}

The JSON Schema above can be used to test the validity of the JSON text below:

{
  "id": 1,
  "name": "Foo",
  "price": 123,
  "tags": [
    "Bar",
    "Eek"
  ],
  "stock": {
    "warehouse": 300,
    "retail": 20
  }
}

The JSON standard does not support object references, but an IETF draft standard for JSON-based object references exists.[39] The Dojo Toolkit supports object references using standard JSON; specifically, the dojox.json.ref module provides support for several forms of referencing including circular, multiple, inter-message, and lazy referencing. Internally both do so by assigning a "$ref" key for such references and resolving it at parse-time; the IETF draft only specifies the URL syntax, but Dojo allows more.[40][41][42]

Alternatively, non-standard solutions exist such as the use of Mozilla JavaScript Sharp Variables. However this functionality became obsolete with JavaScript 1.8.5 and was removed in Firefox version 12.[43]

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. Example of a JSON-RPC 2.0 request and response using positional parameters.

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

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 webpage 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 webpage. 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.

The following JavaScript code is an example of a client using XMLHttpRequest to request data in JSON format from a server. (The server-side programming is omitted; it must be set up to service requests to the url containing a JSON-formatted string.)

var my_JSON_object;
var http_request = new XMLHttpRequest();
http_request.open("GET", url, true);
http_request.responseType = "json";
http_request.onreadystatechange = function () {
  var done = 4, ok = 200;
  if (http_request.readyState === done && http_request.status === ok) {
    my_JSON_object = http_request.response;
  }
};
http_request.send(null);

While JSON is a data serialization format, it has seen ad hoc usage as a configuration language. In this use case, support for comments and other features have been deemed useful, which has led to several nonstandard JSON supersets being created. Among them are HJSON,[44] HOCON, and JSON5 (which despite its name, isn't the fifth version of JSON).[45][46] The primary objective of version 1.2 of YAML was to make the nonstandard format a strict JSON superset.[47]

In 2012, Douglas Crockford had this to say about comments in JSON when used as a configuration language: "I know that the lack of comments makes some people sad, but it shouldn't. Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser."[23]

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.[47] Such escaping is common practice when injecting JSON into HTML to protect against cross-site scripting attacks.

YAML supports comments, while JSON does not.[47][45][23]

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 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" → "value" mapping, whereas in XML addressing happens on "nodes", which all receive 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 reverse solidus must be escaped).[54]

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 strong typing built-in, and has a similar schema concept in JSON Schema.

XML supports comments, while JSON does not.[55][23]

{
  "first name": "John",
  "last name": "Smith",
  "age": 25,
  "address": {
    "street address": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postal code": "10021"
  },
  "phone numbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "fax",
      "number": "646 555-4567"
    }
  ],
  "sex": {
    "type": "male"
  }
}

Both of the following examples carry the same kind of information as the JSON example above in different ways, except that XML doesn't carry the data type.

The JSON text above is also entirely valid YAML. YAML also offers an alternative syntax intended to be more human-accessible by replacing nested delimiters like {}, [], and " marks with indentation.[47]

first name: John
last name: Smith
age: 25
address: 
  street address: 21 2nd Street
  city: New York
  state: NY
  postal code: '10021'
phone numbers: 
  - type: home
    number: 212 555-1234
  - type: fax
    number: 646 555-4567
sex: 
  type: male

Note that the XML examples below don't encode the data type (e.g. that age is a number), and would need something like a schema to encode the same information as the JSON example above does as is. Note that since XML tag names cannot contain spaces (in contrast to JSON and YAML keys), another naming convention has to be used to represent the JSON keys (in this example the tags are in camelCase).[54]

<person>
  <firstName>John</firstName>
  <lastName>Smith</lastName>
  <age>25</age>
  <address>
    <streetAddress>21 2nd Street</streetAddress>
    <city>New York</city>
    <state>NY</state>
    <postalCode>10021</postalCode>
  </address>
  <phoneNumbers>
    <phoneNumber>
      <type>home</type>
      <number>212 555-1234</number>
    </phoneNumber>
    <phoneNumber>
      <type>fax</type>
      <number>646 555-4567</number>
    </phoneNumber>
  </phoneNumbers>
  <sex>
    <type>male</type>
  </sex>
</person>

The properties can also be serialized using attributes instead of tags:

<person firstName="John" lastName="Smith" age="25">
  <address streetAddress="21 2nd Street" city="New York" state="NY" postalCode="10021" />
  <phoneNumbers>
    <phoneNumber type="home" number="212 555-1234"/>
    <phoneNumber type="fax" number="646 555-4567"/>
  </phoneNumbers>
  <sex type="male"/>
</person>