Difference between revisions of "JSON Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 1: Line 1:
[http://www.json.org/ JSON (JavaScript Object Notation)] is a popular data exchange format for applications written in JavaScript. This module contains [[Querying#Functions|XQuery functions]] to parse and serialize JSON documents. All functions are preceded by the <code>json:</code> prefix, which is linked to the <code><nowiki>http://www.basex.org/json</nowiki></code> namespace:
+
[http://www.json.org/ JSON (JavaScript Object Notation)] is a popular data exchange format for applications written in JavaScript. This module contains [[Querying#Functions|XQuery functions]] to parse and serialize JSON documents. All functions are preceded by the <code>json:</code> prefix, which is linked to the <code><nowiki>http://www.basex.org/json</nowiki></code> namespace. [[JSON Functions#json:parse|json:parse()]] and [[JSON Functions#json:serialize|json:serialize()]] are used to transform JSON to XML and back, while [[JSON Functions#json:parse-ml|json:parse-ml()]] and [[JSON Functions#json:serialize-ml|json:serialize-ml()]]) are applied to transform XML to JSON and back.
 
 
* the first two functions ([[JSON Functions#json:parse|json:parse()]] and [[JSON Functions#json:serialize|json:serialize()]]) can be used to transform JSON to XML and back.
 
* the second two functions ([[JSON Functions#json:parse-ml|json:parse-ml()]] and [[JSON Functions#json:serialize-ml|json:serialize-ml()]]) can be used to transform XML to JSON and back.
 
  
 
The proposed JSON functions will be available with <font color="red">Version 6.7.2</font> or <font color="red">6.8</font> of BaseX.
 
The proposed JSON functions will be available with <font color="red">Version 6.7.2</font> or <font color="red">6.8</font> of BaseX.

Revision as of 21:01, 14 August 2011

JSON (JavaScript Object Notation) is a popular data exchange format for applications written in JavaScript. This module contains XQuery functions to parse and serialize JSON documents. All functions are preceded by the json: prefix, which is linked to the http://www.basex.org/json namespace. json:parse() and json:serialize() are used to transform JSON to XML and back, while json:parse-ml() and json:serialize-ml()) are applied to transform XML to JSON and back.

The proposed JSON functions will be available with Version 6.7.2 or 6.8 of BaseX.

json:parse

Signatures json:parse($input as xs:string()) as element(json)
Summary Converts the JSON document specified by $input to XML, and returns the result as element(json) instance. The converted XML document is both well readable and lossless, i.e., the converted document can be serialized back to the original JSON representation. The transformation is based on the following rules:
  1. The resulting document has a <json/> root node.
  2. JSON keys are represented as elements:
    1. Empty keys and values of arrays (which have no keys) are represented by a single underscore <_>...</_>).
    2. Underscores in the key are rewritten to two underscores (__).
    3. A character that cannot be represented as NCName character is rewritten to an underscore and its four-digit Unicode.
  3. JSON values are represented as text nodes.
  4. The types of values are represented in attributes:
    1. The value types number, boolean, null, object and array are represented by a type attribute.
    2. The string type is omitted, as it is treated as default type.
    3. If a key has the same type throughout the whole document, the type attribute will be omitted. Instead, the key will be listed in additional, type-specific attributes in the root node. The attributes are named by their type (number, boolean, null, object or array) and will contain all relevant keys as value, separated by whitespaces.
Errors BASX0015 is raised if the specified input cannot be parsed as JSON document.

json:serialize

Signatures json:serialize($input as node()) as xs:string()
Summary Serializes the node specified by $input as JSON, and returns the result as xs:string instance. The serialized node must conform to the syntax specified by the json:parse() function.
XML documents in the JSON format can also be serialized if the Serialization Option "method" is set to "json".
Errors BASX0016 is raised if the specified node cannot be serialized as JSON document.

Examples

Example 1: A basic example to convert an empty JSON document

Query:

json:parse('{}')

Result:

<json/>

Example 2: Conversion of some simple objects and arrays

Query:

json:parse('{
  "title": "Talk On Travel Pool",
  "link": "http://www.flickr.com/groups/talkontravel/pool/",
  "description": "Travel and vacation photos from around the world.",
  "modified": "2009-02-02T11:10:27Z",
  "generator": "http://www.flickr.com/"
}')

Result:

<json>
  <title>Talk On Travel Pool</title>
  <link>http://www.flickr.com/groups/talkontravel/pool/</link>
  <description>Travel and vacation photos from around the world.</description>
  <modified>2009-02-02T11:10:27Z</modified>
  <generator>http://www.flickr.com/</generator>
</json>

Example 3: Globally defined data types, key rewritings

Query:

json:parse('{
  "last_name": "John Smith",
  "age": 25,
  "address": {
    "street": "21 2nd Street",
    "city": "New York",
    "code": 10021
  },
  "phone": [
    {
      "type": "home",
      "number": "212 555-1234"
    }
  ]
}')

Result:

<json type="object" number="age code" array="phone" object="address">
  <last__name>John Smith</last__name>
  <age>25</age>
  <address>
    <street>21 2nd Street</street>
    <city>New York</city>
    <code>10021</code>
  </address>
  <phone>
    <_ type="object">
      <type>home</type>
      <number>212 555-1234</number>
    </_>
  </phone>
</json>