http://www.zorba-xquery.com/modules/converters/json

Description

Before using any of the functions below please remember to import the module namespace:

import module namespace json = "http://www.zorba-xquery.com/modules/converters/json";
Using this module, you can parse JSON data into XML, manipulate it like any other XML data using XQuery, and serialize the result back as JSON. There are many ways to represent JSON data in XML, some loss-less ("round tripable") and some lossy ("one way"). Loss-less representations preserve the JSON data types boolean, number, and null; lossy representations convert all data to strings.

For a loss-less representation, Zorba implements that proposed by John Snelson. For example: 

   {
     "firstName" : "John",
     "lastName" : "Smith",
     "address" : {
       "streetAddress" : "21 2nd Street",
       "city" : "New York",
       "state" : "NY",
       "postalCode" : 10021
     },
     "phoneNumbers" : [ "212 732-1234", "646 123-4567" ]
   }
would be represented as: 
   <json type="object">
     <pair name="firstName" type="string">John</pair>
     <pair name="lastName" type="string">Smith</pair>
     <pair name="address" type="object">
       <pair name="streetAddress" type="string">21 2nd Street</pair>
       <pair name="city" type="string">New York</pair>
       <pair name="state" type="string">NY</pair>
       <pair name="postalCode" type="number">10021</pair>
     </pair>
     <pair name="phoneNumbers" type="array">
       <item type="string">212 732-1234</item>
       <item type="string">646 123-4567</item>
     </pair>
   </json>
For a lossy representation, Zorba implements JsonML (the array form). For example: 
   [ "person",
     { "created" : "2006-11-11T19:23",
       "modified" : "2006-12-31T23:59" },
     [ "firstName", "Robert" ],
     [ "lastName", "Smith" ],
     [ "address",
       { "type" : "home" },
       [ "street", "12345 Sixth Ave" ],
       [ "city", "Anytown" ],
       [ "state", "CA" ],
       [ "postalCode", "98765-4321" ]
     ]
   ]
would be represented as: 
   <person created="2006-11-11T19:23" modified="2006-12-31T23:59">
     <firstName>Robert</firstName>
     <lastName>Smith</lastName>
     <address type="home">
       <street>12345 Sixth Ave</street>
       <city>Anytown</city>
       <state>CA</state>
       <postalCode>98765-4321</postalCode>
     </address>
   </person>

Imported Schemas

Please note that the schemas are not automatically imported in the modules that import this module.

In order to import and use the schemas, please add:

import schema namespace json-options =  "http://www.zorba-xquery.com/modules/converters/json-options";

Author

Paul J. Lucas

XQuery version and encoding

xquery version "3.0" encoding "utf-8";

Namespaces

anhttp://www.zorba-xquery.com/annotations
errhttp://www.w3.org/2005/xqt-errors
jsonhttp://www.zorba-xquery.com/modules/converters/json
json-optionshttp://www.zorba-xquery.com/modules/converters/json-options
schemahttp://www.zorba-xquery.com/modules/schema
verhttp://www.zorba-xquery.com/options/versioning
zerrhttp://www.zorba-xquery.com/errors

Function Summary

parse($json as xs:string?) as element(*,xs:untyped)*

Parses JSON data from a string and returns an XDM instance using the Snelson representation described above.

parse($json as xs:string?, $options as element(json-options:options)) as element(*,xs:untyped)*

Parses JSON data from a string and returns an XDM instance using one of the representations described above.

serialize($xml as item()*) as xs:string

Serializes an XDM into JSON using one of the representations described above.

serialize($xml as item()*, $options as element(json-options:options)) as xs:string

Serializes an XDM into JSON using one of the representations described above.

Functions

parse#1

declare function json:parse(
    $json as xs:string?
) as element(*,xs:untyped)*

Parses JSON data from a string and returns an XDM instance using the Snelson representation described above.

Parameters

  • $json as xs:string
    The JSON data to parse.

Returns

  • element(*,xs:untyped)*

    said XDM instance.

Errors

  • zerr:ZJPE0001 if $json contains an illegal JSON character.
  • zerr:ZJPE0002 if $json contains an illegal Unicode code-point.
  • zerr:ZJPE0003 if $json contains an illegal JSON character escape.
  • zerr:ZJPE0004 if $json contains an illegal JSON literal.
  • zerr:ZJPE0005 if $json contains an illegal JSON number.
  • zerr:ZJPE0006 if $json is not a valid JSON string.
  • zerr:ZJPE0007 if $json contains an unterminated string.
  • zerr:ZJPE0008 if $json contains an illegal QName.

Examples

parse#2

declare function json:parse(
    $json as xs:string?,
    $options as element(json-options:options)
) as element(*,xs:untyped)*

Parses JSON data from a string and returns an XDM instance using one of the representations described above.

Parameters

  • $json as xs:string
    The JSON data to parse.
  • $options as element(json-options:options)
    The parsing options, for example: 
     <options xmlns="http://www.zorba-xquery.com/modules/converters/json-options"> <json-format value="JsonML-array"/> </options>

Returns

  • element(*,xs:untyped)*

    said XDM instance.

Errors

  • err:XQDY0027 if $options can not be validated against the json-options schema.
  • zerr:ZJPE0001 if $json contains an illegal JSON character.
  • zerr:ZJPE0002 if $json contains an illegal Unicode code-point.
  • zerr:ZJPE0003 if $json contains an illegal JSON character escape.
  • zerr:ZJPE0004 if $json contains an illegal JSON literal.
  • zerr:ZJPE0005 if $json contains an illegal JSON number.
  • zerr:ZJPE0006 if $json is not a valid JSON string.
  • zerr:ZJPE0007 if $json contains an unterminated string.
  • zerr:ZJPE0008 if $json contains an illegal QName.

Examples

serialize#1

declare function json:serialize(
    $xml as item()*
) as xs:string

Serializes an XDM into JSON using one of the representations described above.

Parameters

  • $xml as item()
    The XDM to serialize.

Returns

  • xs:string

    a JSON string.

Errors

  • zerr:ZJSE0001 if $xml is not a document or element node.
  • zerr:ZJSE0002 if $xml contains an element that is missing a required attribute.
  • zerr:ZJSE0003 if $xml contains an attribute having an illegal value.
  • zerr:ZJSE0004 if $xml contains an illegal element.
  • zerr:ZJSE0005 if $xml contains an illegal child element for a JSON type.
  • zerr:ZJSE0006 if $xml contains an illegal child element.
  • zerr:ZJSE0007 if $xml contains an illegal text node.
  • zerr:ZJSE0008 if $xml contains an illegal value for a JSON type.

Examples

serialize#2

declare function json:serialize(
    $xml as item()*,
    $options as element(json-options:options)
) as xs:string

Serializes an XDM into JSON using one of the representations described above.

Parameters

  • $xml as item()
    The XDM to serialize.
  • $options as element(json-options:options)
    The serializing options, for example: 
     <options xmlns="http://www.zorba-xquery.com/modules/converters/json-options"> <json-format value="JsonML-array"/> <whitespace value="indent"/> </options>

Returns

  • xs:string

    a JSON string.

Errors

  • err:XQDY0027 if $options can not be validated against the json-options schema.
  • zerr:ZJSE0001 if $xml is not a document or element node.
  • zerr:ZJSE0002 if $xml contains an element that is missing a required attribute.
  • zerr:ZJSE0003 if $xml contains an attribute having an illegal value.
  • zerr:ZJSE0004 if $xml contains an illegal element.
  • zerr:ZJSE0005 if $xml contains an illegal child element for a JSON type.
  • zerr:ZJSE0006 if $xml contains an illegal child element.
  • zerr:ZJSE0007 if $xml contains an illegal text node.
  • zerr:ZJSE0008 if $xml contains an illegal value for a JSON type.

Examples

blog comments powered by Disqus