JSON Data

JavaScript Object Notation (JSON) is a lightweight, text-based data-interchange format generally used for exchanging data between Web servers and applications, representing data in a structured way using name-value pairs, arrays, and objects.

Topics:

• About JSON

• JSON Syntax

About JSON

JSON is defined in standards ECMA-404 (JSON Data Interchange Format), IETF RFC 8259, and ECMA-262 (ECMAScript Language Specification, third edition and later). The JavaScript dialect of ECMAScript is a general programming language used widely in web browsers and web servers.

JSON is almost a subset of the object literal notation of JavaScript. Because it can be used to represent JavaScript object literals, JSON commonly serves as a data-interchange language. In this, it has much in common with XML. Because it is almost a subset of JavaScript notation, JSON can often be used in JavaScript programs without any need for parsing or serializing. It is a text-based way of representing JavaScript object literals, arrays, and scalar data.

Although it was defined in the context of JavaScript, JSON is in fact a language-independent data format. A variety of programming languages can parse and generate JSON data. JSON is relatively easy for humans to read and write, and easy for software to parse and generate. It is often used for serializing structured data and exchanging it over a network, typically between a server and web applications.

See also:

• ECMA 404 and IETF RFC 8259 for the definition of the JSON Data Interchange Format

• ECMA 262 and ECMA 262, 5.1 Edition for the ECMAScript Language Specifications (JavaScript)

• JSON.org and JSON5

JSON Syntax

JSON data is built on two structures:

• A collection of name-value pairs or object.

• An ordered list of values or array.

An object is an unordered set of zero or more pairs of property names and associated values. An object begins with a left curly brace ({) and ends with a right curly brace (}). Each property name consists of a string enclosed in double quotation marks (") and it is followed by a colon (:). Name-value pairs are separated by a comma (,). Property names must be unique within the object. Property names are typically called fields or keys. This documentation generally refers to property names as fields or name fields.

{
    "field1": value1,
    "field2": value2
}

Note:

Whitespace between tokens—as such as names, values, and punctuation marks—is ignored by JSON parsers, but can be used to make JSON data more readable and maintainable.

An array is an ordered set of values. An array begins with a left bracket ([) and ends with a right bracket (]). Values are separated by a comma (,). An array can be empty.

[ 
    value1, 
    value2 
]

A value can be a string enclosed in double quotation marks ("), a number, a Boolean, null, an object or an array.

Note:

The Boolean (true or false) and null values are case sensitive and should not be enclosed in double quotation marks.

Example 1-1 A JSON Object

This example shows a JSON object that represents a purchase order.

{
  "PONumber" : 1600,
  "Reference" : "ABULL-20140421",
  "Requestor" : "Alexis Bull",
  "User" : "ABULL",
  "CostCenter" : "A50",
  "ShippingInstructions" :
  {
    "name" : "Alexis Bull",
    "Address" :
    {
      "street" : "200 Sporting Green",
      "city" : "South San Francisco",
      "state" : "CA",
      "zipCode" : 99236,
      "country" : "United States of America"
    },
    "Phone" :
    [
      {
        "type" : "Office",
        "number" : "909-555-7307"
      },
      {
        "type" : "Mobile",
        "number" : "415-555-1234"
      }
    ]
  },
  "Special Instructions" : null,
  "AllowPartialShipment" : true,
  "LineItems" :
  [
    {
      "ItemNumber" : 1,
      "Part" :
      {
        "Description" : "One Magic Christmas",
        "UnitPrice" : 19.95,
        "UPCCode" : 13131092899
      },
      "Quantity" : 9
    },
    {
      "ItemNumber" : 2,
      "Part" :
      {
        "Description" : "Lethal Weapon",
        "UnitPrice" : 19.95,
        "UPCCode" : 85391628927
      },
      "Quantity" : 5
    }
  ]
}

The example includes all possible value types:

• String. For example, the Reference name field has the value ABULL-20140421.

• Number. For example, the PONumber name field has the value 1600.

• Boolean. For example, the AllowPartialShipment name field has the value true.

• Null. For example, the Special Instructions name field has the value null.

• Object. For example, the Shipping Instructions name field has an object value with Name, Address, and Phone as the top-level name fields.

• Array. For example the Phone name field has an array value of two object values.