JSON Module

From BaseX Documentation

Jump to: navigation, search

This XQuery Module contains functions to parse and serialize JSON documents. JSON (JavaScript Object Notation) is a popular data exchange format for applications written in JavaScript. 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 various mappings, all of which are suited to different use cases.

Contents

[edit] Conventions

All functions in this module are assigned to the http://basex.org/modules/json namespace, which is statically bound to the json prefix.
All errors are assigned to the http://basex.org/errors namespace, which is statically bound to the bxerr prefix.

[edit] Conversion Formats

[edit] Direct

The direct conversion format allows a lossless conversion from JSON to XML and back. The transformation is based on the following rules:

[edit] Attributes

The attributes format is lossless, too. The transformation based on the following rules:

[edit] Map

The map format is lossless, too. It converts a JSON document to an XQuery map and vice versa. The conversion rules are the same as for fn:parse-json.

[edit] Basic

The basic format is another lossless format. It converts a JSON document to an XML node and vice versa. The conversion rules are the same as for fn:json-to-xml.

[edit] JsonML

The jsonml format is designed to convert XML to JSON and back, using the JsonML dialect. JsonML allows the transformation of 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.

A little advice: in the Database Creation dialog of the GUI, if you select JSON Parsing and switch to the Parsing tab, you can see the effects of some of the conversion options.

[edit] Options

The following options are available (the Direction column indicates if an option applies to parsing, serialization, or both operations):

Option Description Allowed Default Direction
format Specifies the format for converting JSON data. direct, attributes, jsonml, map direct parse, serialize
liberal Determines if minor deviations from RFC 7159 will be ignored. yes, no no parse
merge This option is considered when direct or attributes conversion is used:
  • 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 plural (numbers, booleans, nulls, objects and arrays), and the attribute value contains all names with that type, separated by whitespaces.
yes, no no parse, serialize
strings Indicates if type attributes will be added for strings. yes, no yes parse, serialize
lax Specifies if a lax approach is used to convert QNames to JSON names. yes, no no parse, serialize
escape Indicates if escaped characters are expanded (for example, \n becomes a single x0A character, while \u20AC becomes the character ). yes, no yes parse
escape Indicates if characters are escaped whenever the JSON syntax requires it. This option can be set to no if strings are already in escaped form and no further escaping is permitted. yes, no yes serialize
indent Indicates if whitespace should be added to the output with the aim of improving human legibility. If the parameter is set as in the query prolog, it overrides the indent serialization parameter. yes, no yes serialize

[edit] Functions

[edit] json:parse

Signatures json:parse($input as xs:string) as element(json)
json:parse($input as xs:string, $options as map(xs:string, xs:string)) as item()
Summary Converts the JSON document specified by $input to an XML document or a map. If the input can be successfully parsed, it can be serialized back to the original JSON representation. The $options argument can be used to control the way the input is converted.
Errors BXJS0001: the specified input cannot be parsed as JSON document.

[edit] json:serialize

Signatures json:serialize($input as item()?) as xs:string
json:serialize($input as item()?, $options as map(xs:string, xs:string)) as xs:string
Summary Serializes the node specified by $input as JSON, and returns the result as xs:string instance. The node is expected to conform to the output created by the json:parse() function. All other items will be serialized as specified for the json output method of the official specification.
Items can also be serialized as JSON if the Serialization Parameter method is set to json.
The $options argument can be used to control the way the input is serialized.
Errors BXJS0002: the specified node cannot be serialized as JSON document.

[edit] Examples

[edit] BaseX Format

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, $json, $name) 

Example 2: Converts a simple JSON string to XML and back

Query:

json:parse('{}')

Result:

<json type="object"/>

Query:

(: serialize result as plain text :)
declare option output:method 'text';
json:serialize(<json type="object"/>)

Result:

{ }

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": "2014-02-02T11:10:27Z",
  "generator": "http://www.flickr.com/"
}')

Result:

<json type="object">
  <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>2014-02-02T11:10:27Z</modified>
  <generator>http://www.flickr.com/</generator>
</json>

Example 4: Converts a JSON string with different data types

Query:

let $options := map { 'merge': true() }
return json:parse('{
  "first_name": "John",
  "last_name": "Smith",
  "age": 25,
  "address": {
    "street": "21 2nd Street",
    "city": "New York",
    "code": 10021
  },
  "phone": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "mobile",
      "number": 1327724623
    }
  ]
}', $options)

Result:

<json numbers="age code" arrays="phone" objects="json address value">
  <first__name>John</first__name>
  <last__name>Smith</last__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>
    </_>
    <_>
      <type>mobile</type>
      <number type="number">1327724623</number>
    </_>
  </phone>
</json>

[edit] JsonML Format

Example 1: Converts all XML documents in a database to JsonML and writes them to disk

Query:

for $doc in collection('json')
let $name := document-uri($doc)
let $json := json:serialize($doc)
return file:write($name, $json)

Example 2: Converts a simple XML fragment to the JsonML format

Query:

json:serialize(<xml/>, map { 'format': 'jsonml' })

Result:

["xml"]

Example 3: Converts an XML document with elements and text

Query:

json:serialize(doc('flickr.xml'), map { 'format': 'jsonml' })

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>2014-02-02T11:10:27Z</modified>
  <generator>http://www.flickr.com/</generator>
</flickr>

Result:

["flickr",
  ["title",
    "Talk On Travel Pool"],
  ["link",
    "http://www.flickr.com/groups/talkontravel/pool/"],
  ["description",
    "Travel and vacation photos from around the world."],
  ["modified",
    "2014-02-02T11:10:27Z"],
  ["generator",
    "http://www.flickr.com/"]]

Example 4: Converts a document with nested elements and attributes

Query:

json:serialize(doc('input.xml'), map { 'format': 'jsonml' })

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"]]

[edit] Errors

Code Description
BXJS0001 The specified input cannot be parsed as JSON document.
BXJS0002 The specified node cannot be serialized as JSON document.

[edit] Changelog

Version 8.4
Version 8.2
Version 8.0
Version 7.8
Version 7.7.2

The module was introduced with Version 7.0.

Personal tools
Namespaces
Variants
Actions
Navigation
Print/export