JSON Module

From BaseX Documentation
Revision as of 14:51, 14 August 2011 by CG (talk | contribs)
Jump to navigation Jump to search

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.

The proposed JSON functions will be available with Version 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 transformatio 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 are represented with an underscore (_). Values of arrays (which have no keys) will also be enclosed by underscore tag names.
    2. Underscores are represented with two underscores (__).
    3. Spaces are represented with two underscores (___)
    4. Characters that cannot be represented as NCName character are represented with a leading and trailing underscore and a four-digit Unicode.
  3. The types of value are represented in attributes:
    1. The value types number, boolean, null and array are represented with a type attribute.
    2. String and object types are omitted as they are treated as default types for flat elements and and nested elements with/without names.
    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 or array) and will contain all relevant keys as value, separated by whitespaces.
Errors BASX0017 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 JSON Functions#json:parse.
Errors BASX0018 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

Query:

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

Result:

<json number="age code" array="phone" object="address">
  <name>John Smith</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>