Difference between revisions of "JSON Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 21: Line 21:
 
## String and object types are omitted as they are treated as default types for flat elements and and nested elements with/without names.  
 
## String and object types are omitted as they are treated as default types for flat elements and and nested elements with/without names.  
 
## 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.  
 
## 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.  
 +
|-
 +
| valign='top' | '''Errors'''
 +
|<b>[[XQuery Errors#JSON Errors (FOJS)|FOJS0001]]</b> is raised if the specified input cannot be parsed as JSON document.
 +
|}
 +
 +
==json:serialize==
 +
{|
 +
|-
 +
| valign='top' width='90' | '''Signatures'''
 +
|<code><b>json:serialize</b>($input as node()) as xs:string()</code>
 +
|-
 +
| valign='top' | '''Summary'''
 +
|Serializes the node specified by <code>$input</code> as JSON, and returns the result as <code>xs:string</code> instance. The serialized node must conform to the syntax specified by [[JSON Functions#json:parse]].
 +
|-
 +
| valign='top' | '''Errors'''
 +
|<b>[[XQuery Errors#JSON Errors (FOJS)|FOJS0002]]</b> is raised if the specified node cannot be serialized as JSON document.
 
|}
 
|}
  

Revision as of 14:45, 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.

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 FOJS0001 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 FOJS0002 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">
  <name>John Smith</name>
  <age>25</age>
  <address>
    <street>21 2nd Street</street>
    <city>New York</city>
    <code>10021</code>
  </address>
  <phone>
    <_>
      <type>home</type>
      <number>212 555-1234</number>
    </_>
  </phone>
</json>