https://github.com/joewiz/xqjson
An XQuery module with functions for parsing and serializing JSON
https://github.com/joewiz/xqjson
Last synced: 5 months ago
JSON representation
An XQuery module with functions for parsing and serializing JSON
- Host: GitHub
- URL: https://github.com/joewiz/xqjson
- Owner: joewiz
- License: other
- Created: 2012-12-28T05:43:14.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2018-09-20T13:33:41.000Z (about 7 years ago)
- Last Synced: 2024-04-14T22:55:44.298Z (over 1 year ago)
- Language: XQuery
- Size: 51.8 KB
- Stars: 20
- Watchers: 7
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
> With [XQuery 3.1's support of JSON parsing and serialization](https://www.w3.org/TR/xpath-functions-31/#json), this package is no longer being maintained. You are strongly encouraged to migrate your code to XQuery 3.1. (For eXist users, an implementation of the `fn:json-to-xml` and `fn:xml-to-json` functions, see https://gist.github.com/joewiz/d986da715facaad633db.)
# Parsing JSON into XQuery
An XQuery module for parsing and serializing JSON, originally
written by John Snelson, with minor bug fixes applied, and packaged in the
[EXPath Package format](http://www.expath.org/spec/pkg) for convenient installation in any XQuery implementation that
supports it.
## Documentation
Snelson's [original article](http://john.snelson.org.uk/post/48547628468/parsing-json-into-xquery) is the official documentation. The information below focuses on how to install this module and get up and running. A table from Snelson's article about how each aspect of JSON is captured as XML is reproduced [below](#json-xml-mapping).
## Requirements and Compatibility
The [original module](http://xqilla.hg.sourceforge.net/hgweb/xqilla/xqilla/file/6458513c94c0/src/functions/XQillaModule.xq)
was designed for use with [XQilla](http://xqilla.sourceforge.net/HomePage), but since it is written in pure XQuery 3.0,
it is compatible with other XQuery 3.0 processors. It has been tested with eXist 2.0+.
You can download the core module from the `src/content/` directory and import it in your own XQuery.
For many systems, it is more convenient to install the module as an [EXPath Package](http://expath.org/modules/pkg/) (.xar file).
A pre-built package is available on the [Releases](https://github.com/joewiz/xqjson/releases) page.
To build the source into a package, you will need [Apache Ant](http://ant.apache.org/).
To install the package, you need an implementation of XQuery that [supports](http://expath.org/modules/pkg/implems) the EXPath Package system.
## Installation for eXist-db
To install in eXist-db, clone this repository and run ant, which will construct an EXPath Archive (.xar) file in the
project's build folder. Then install the package via the eXist-db Package Manager, or place it in eXist-db's 'autodeploy' folder.
## Usage
### Import the module
import module namespace xqjson="http://xqilla.sourceforge.net/lib/xqjson";
Note that the original module used "xqilla" as the module's namespace prefix, but this module uses "xqjson" instead,
and the original module used "http://xqilla.sourceforge.net/Functions" as the module's namespace, but this module has
adopted the more specific "http://xqilla.sourceforge.net/lib/xqjson".
### xqjson:parse-json($json as xs:string?) as element()?
This function translates a valid JSON string into an XML representation.
**Note:** This function assumes that the JSON string supplied is valid JSON. If you encounter an error with this function, please check to make sure your JSON is valid using a free, online validator like [jsonlint.com](http://jsonlint.com/).
### xqjson:serialize-json($json-xml as element()?) as xs:string?
This function reverses the above process.
**Note**: The resulting JSON is not pretty-printed, and no effort is made to preserve whitespace when roundtripping from JSON to parsed XML back to serialized JSON.
## Examples
This example shows how the `parse-json()` function translates and captures JSON objects, arrays, strings, numbers, booleans, and nulls. (The JSON string was taken from [wikipedia](http://en.wikipedia.org/wiki/JSON#Data_types.2C_syntax_and_example).)
```xquery
let $json :=
'{
"firstName": "John",
"lastName": "Smith",
"isAlive": true,
"age": 25,
"height_cm": 167.6,
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": "10021-3100"
},
"phoneNumbers": [
{
"type": "home",
"number": "212 555-1234"
},
{
"type": "office",
"number": "646 555-4567"
}
],
"children": [],
"spouse": null
}')
return
xqjson:parse-json($json)
```
This will return the following result:
```xml
John
Smith
true
25
167.6
21 2nd Street
New York
NY
10021-3100
home
212 555-1234
office
646 555-4567
```
Using xqjson:serialize-json() on this `` element will return the original JSON, sans pretty printing:
```json
{"firstName":"John","lastName":"Smith","isAlive":true,"age":25,"height_cm":167.6,"address":{"streetAddress":"21 2nd Street","city":"New York","state":"NY","postalCode":"10021-3100"},"phoneNumbers":[{"type":"home","number":"212 555-1234"},{"type":"office","number":"646 555-4567"}],"children":[],"spouse":null}
```
### JSON object with a single pair, illustrating string type
```json
{
"firstName": "John"
}
```
```xml
John
```
### JSON object with multiple pairs, illustrating string, number, and boolean types
```json
{
"firstName": "John",
"lastName": "Smith",
"age": 25,
"isAlive": true
}
```
```xml
John
Smith
25
true
```
### JSON array containing objects, which in turn contain pairs and arrays
```json
[
{
"label": "node1",
"children": [
"child1",
"child2"
]
},
{
"label": "node2",
"children": ["child3"]
}
]
```
```xml
node1
child1
child2
node2
child3
```
### JSON object with a pair whose value is another object
```json
{
"address": {
"streetAddress": "21 2nd Street",
"city": "New York",
"state": "NY",
"postalCode": "10021-3100"
}
}
```
```xml
21 2nd Street
New York
NY
10021-3100
```
### JSON object with a pair whose value is an array of objects
```json
{
"phoneNumbers": [
{
"type": "home",
"number": "212 555-1234"
},
{
"type": "office",
"number": "646 555-4567"
}
]
}
```
```xml
home
212 555-1234
office
646 555-4567
```
### JSON Object with two pairs showing an empty array and a null value
```json
{
"children": [],
"spouse": null
}
```
```xml
```
## JSON-XML Mapping
|JSON|type(JSON)|toXML(JSON)|
|----|----------|-----------|
|JSON|N/A|``toXML(JSON)``|
|`{ "key1": value1, "key2": value2 }`|object|``*toXML(value1)*` `*toXML(value2)*``|
|`[ value1, value2 ]`|array|``*toXML(value1)*` `*toXML(value2)*``|
|`"value"`|string|`value`|
|*number*|number|*number*|
|`true` / `false`|boolean|`true` / `false`|
|`null`|null|*empty*|
## Running the test suite
A test suite, written using the [XQSuite](http://exist-db.org/exist/apps/doc/xqsuite.xml) framework for
eXist, can be run with the following command, assuming Apache Ant is installed (some properties in
`build.xml` may need to be adapted to your system):
```bash
ant test
```
The result should show something like:
```xml
```
If all is well, the `@failures` attribute should read `0`.