Difference between revisions of "JSON Module"
Line 141: | Line 141: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>json:serialize</b>($input as node()) as xs:string()</code> | + | |<code><b>json:serialize-ml</b>($input as node()) as xs:string()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 154: | Line 154: | ||
|- | |- | ||
| valign='top' width='90' | '''Signatures''' | | valign='top' width='90' | '''Signatures''' | ||
− | |<code><b>json:parse</b>($input as xs:string()) as element()</code> | + | |<code><b>json:parse-ml</b>($input as xs:string()) as element()</code> |
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
Line 165: | Line 165: | ||
==Examples== | ==Examples== | ||
− | '''Example 1: | + | '''Example 1: Converts a simple XML fragment to the JsonML format''' |
'''Query:''' | '''Query:''' | ||
Line 177: | Line 177: | ||
</pre> | </pre> | ||
− | '''Example 2: | + | '''Example 2: Converts an XML document with elements and text''' |
'''Query:''' | '''Query:''' | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | json:serialize-ml(doc(' | + | json:serialize-ml(doc('flickr.xml')) |
</pre> | </pre> | ||
− | ''' | + | '''flickr.xml:''' |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
− | < | + | <flickr> |
− | < | + | <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> | |
− | + | </flickr> | |
− | |||
− | |||
− | </ | ||
− | </ | ||
'''Result:''' | '''Result:''' | ||
Line 213: | Line 209: | ||
</pre> | </pre> | ||
− | '''Example 3: | + | '''Example 3: Converts a document with nested elements and attributes''' |
'''Query:''' | '''Query:''' |
Revision as of 02:16, 15 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 officially supported with the upcoming Version 6.8 of BaseX.
As there are notable differences between JSON and XML, no mapping exists that guarantees a lossless, bidirectional conversion between JSON and XML. For this reason, we offer two sets of functions in this module:
Contents
JSON
json:parse and json:serialize facilitate a lossless conversion from JSON to XML and back. The transformation is based on the following rules:
- The resulting document has a
<json/>
root node. - Names (keys) of objects are represented as elements:
- Empty names are represented by a single underscore (
<_>...</_>
). - Underscore characters are rewritten to two underscores (
__
). - A character that cannot be represented as NCName character is rewritten to an underscore and its four-digit Unicode.
- Empty names are represented by a single underscore (
- As arrays have no names, {@code <value/>} is used as element name.
- JSON values are represented as text nodes.
- The types of values are represented in attributes:
- The value types number, boolean, null, object and array are represented by a
type
attribute. - The string type is omitted, as it is treated as default type.
- If a name has the same type throughout the document, the
type
attribute will be omitted. Instead, the name will be listed in additional, type-specific attributes in the root node. The attributes are named by their type in the plural (numbers, booleans, nulls, objects and arrays), and the attribute value contains all names with that type, separated by whitespaces.
- The value types number, boolean, null, object and array are represented by a
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.
|
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: Adds all JSON documents in a directory to a database
Query:
let $database := "database" for $name in file:list('.', false(), '*.json') let $file := file:read-text($name) let $json := json:parse($file) return db:add($database, document { $json }, $name)
Example 2: Converts a simple JSON string to XML
Query:
json:parse('{}')
Result:
<json objects="json"/>
Example 3: Converts a JSON string with 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 objects="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 4: Converts a JSON string with different data types
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 numbers="age code" arrays="phone" objects="json address value"> <last__name>John Smith</last__name> <age>25</age> <address> <street>21 2nd Street</street> <city>New York</city> <code>10021</code> </address> <phone> <value> <type>home</type> <number>212 555-1234</number> </value> </phone> </json>
JsonML
json:serialize-ml and json:parse-ml are used to transform XML to JSON and back, using the JsonML dialect. JsonML can be used to transform arbitrary XML documents, but namespaces, comments and processing instructions will be discarded in the transformation process. More details are found in the official JsonML documentation.
json:serialize-ml
Signatures | json:serialize-ml($input as node()) as xs:string()
|
Summary | Serializes the node specified by $input and returns the result as xs:string instance.
|
Errors | BASX0016 is raised if the specified node cannot be serialized as JSON document. |
json:parse-ml
Signatures | json:parse-ml($input as xs:string()) as element()
|
Summary | Converts the JsonML document specified by $input to XML, and returns the result as element() instance. The JSON input must conform to the JsonML specification to be successfully converted.
|
Errors | BASX0015 is raised if the specified input cannot be parsed as JsonML instance. |
Examples
Example 1: Converts a simple XML fragment to the JsonML format
Query:
json:serialize-ml(<xml/>)
Result:
["xml"]
Example 2: Converts an XML document with elements and text
Query:
json:serialize-ml(doc('flickr.xml'))
flickr.xml:
<flickr> <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> </flickr> '''Result:''' <pre> ["flickr", ["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\/"]]
Example 3: Converts a document with nested elements and attributes
Query:
json:serialize-ml(doc('input.xml'))
input.xml:
<address id='1'> <!-- comments will be discarded --> <last_name>Smith</last_name> <age>25</age> <address xmlns='will be dropped as well'> <street>21 2nd Street</street> <city>New York</city> <code>10021</code> </address> <phone type='home'>212 555-1234</phone> </address>
Result:
["address", {"id":"1"}, ["last_name", "Smith"], ["age", "25"], ["address", ["street", "21 2nd Street"], ["city", "New York"], ["code", "10021"]], ["phone", {"type":"home"}, "212 555-1234"]]