The JSON format represents data as
JavaScript literals. The object literal produced by JSON can be
directly evaluated by a JSON parser (such as json_decode
in PHP or the json.org JSON
library).
The following rules define the mapping from entities to JSON primitives (arrays, objects and properties):
Underscores are used instead of dashes for name properties and for entity types.
Each entity is represented as an object.
The type of the entity is represented as the property "type".
Metadata is represented as object properties.
Unstructured data is represented as the property "data".
Structured data is represented using an object with each component represented as a property of that object.
Composition is represented as a property. There can be two kinds of composition relationships between parent and child entities:
Only a single child is permitted by the schema. In this case, the parent object will have a property referencing the child object directly
Zero, one, or multiple children are permitted by the schema. In this case the parent object will have a property referencing an array of child objects. This array can also be empty or contain a single element.
It can be known statically if a particular property needs to be accessed as an object, or as an array of objects, which removes type-checking complexity on the receiving side. Although most data is stored in single-element arrays, this representation suggests fields are potentially multi-value. The plurality of a property is the same as the name of the composition relationship between the two entities. If the schema allows multiple children, the name of the property is plural. If the schema allows a single child, the name is singular.
![[Note]](images/docbook/note.png) |
Note |
|---|---|
Although the examples throughout this specification show JSON structures indented for readability, the actual output from the Address Book JSON API is not indented. |
The search Response containing a single contact with name and phone fields (shown in the XML example above), looks like the following in JSON format:
{ "type": "search_response",
"contacts": [
{ "type": "contact",
"cid": 28,
"fields": [
{ "type": "name",
"fid": 30,
"first": "Mike",
"last": "Smith"
},
{ "type": "phone",
"fid": 33,
"data": "408-349-1111",
"work": true
}
]
}
]
}