Json
From Freebase
This article contains content originally taken from the MQL Manual, which is no longer maintained. It may need cleanup to make sense as a standalone document. Please go ahead and help us do this!
The Metaweb queries and responses we saw in <xref linkend="intro"/> contained a lot of punctuation: curly braces, quotation marks, colons, and commas. Before we study more queries, it is important to understand this punctuation. Metaweb queries and responses use a plain-text data interchange format known as JavaScript Object Notation or, more commonly, JSON. If you are a JavaScript programmer, then this format will be familiar to you since it is a subset of the JavaScript language. If you are not a JavaScript programmer, the format is easy-to-learn, and does not require the use of the JavaScript language.
Contents |
Intro to JSON
JSON is formally described in RFC 4627 (http://www.ietf.org/rfc/rfc4627.txt), and is also documented at http://json.org. The JSON website includes pointers to code, in a variety of programming languages, for serializing data structures into JSON format and for parsing JSON text into data structures. <footnote><para> The JSON syntax diagrams that appear below are also from the JSON website, where they have been placed in the public domain. </footnote>
A JSON-formatted string is a serialized form of an array or object. The array or object may contain numbers, strings, other arrays and objects, and the literal values null, true, and false. These JSON values are illustrated in <xref linkend="jsonvalues"/> and explained in the sub-sections that follow:
JSON Literals: null, true, false
JSON supports three literal values. null is a JSON value representing "no value". The literals true and false a represent the two possible Boolean values.
JSON Numbers
A JSON number consists of an optional minus sign followed by an integer part followed by an optional decimal point and fractional part followed by an optional exponent. This format is the same as the format described for /type/float in <xref linkend="objectmodel"/>. All numbers use decimal digits: octal and hexadecimal notation are not supported.
JSON Strings
A JSON string is much like a string in Java or JavaScript: zero or more Unicode characters <footnote> <para> JSON itself supports 32-bit, 16-bit and 8-bit encodings of Unicode text. Metaweb, however, requires the 8-bit UTF-8 encoding.
A backslash is special: it is an escape character and is interpreted along with the character or characters that follow:
| Escape | Character |
\" |
A quotation mark that does not terminate the string |
\\ |
A single backslash character that is not an escape |
\/ |
A forward slash character. Although it is legal to escape the forward slash character, it is never necessary to do so. |
\b |
The Backspace character |
\f |
The Formfeed character |
\n |
The Newline character |
\r |
The Carriage Return character |
\t |
The Tab character |
\uXXXX |
The Unicode character whose encoding is the four hexadecimal digits <replaceable>XXXX</replaceable>. To encode extended Unicode codepoints that do not fit in four hex digits, use two |
JSON Arrays
An array is a comma-separated list of JSON values enclosed in square brackets. See <xref linkend="jsonarray"/>
Arrays may contain any JSON values, including objects and other arrays. The elements of a JSON array need not have the same type (though in MQL they always do). The following JSON array might be returned in response to a MQL query:
["Outlandos d'Amour", "Reggatta de Blanc", "Zenyatta Mondatta"]
A JSON array with no elements consists of just the square brackets: []. Empty arrays often appear in MQL queries.
JSON Objects
A JSON object is named after the JavaScript object type, and is not very much like the objects of strongly-typed object-oriented programming languages. Instead, think of an object as:
- an associative array;
- a hashtable that maps strings to values;
- a dictionary; or
- an unordered set of named values.
JSON objects are written as a comma-separated list of name/value pairs, enclosed in curly braces. A name/value pair is a JSON string (the name) followed by a colon followed by any JSON value, which may include nested objects and arrays. See <xref linkend="jsonobject"/>
Here is an example JSON object (which also happens to be a Metaweb query):
{
"type" : "/music/artist",
"name" : "The Police",
"album" : []
}
JavaScript programmers should note that JSON requires property names to appear within double quotes, even though the JavaScript language does not. Arbitrary whitespace is allowed within JSON objects and arrays, but trailing commas (after the final array element or last name/value pair) are not. An empty JSON object, with no properties at all is simply a pair of curly braces: {}. As we'll see, empty objects are not uncommon in MQL queries.
