JSON Schema for the enterprise
This document specifies the JsonXml API, which offers utilities for converting JSON documents to XML, and vice-versa.
1 Introduction
1.1 Dependencies on Other Specifications
1.2 Conventions Used in This Document
2 Purpose
3 Requirements
4 Getting Started
4.1 JSON-to-XML
4.2 XML-to-JSON
5 Specification
5.1 JsonXml Schema
5.1.1 boolean
5.1.2 string
5.1.3 number
5.1.4 object
5.1.5 array
5.1.6 null
5.2 JsonXml API
5.2.1 JxConverter
6 Sample Documents
6.1 paypal.json
6.2 paypal.xml
7 Related Resources for JsonXml
7.1 Schemas for JsonXml
7.1.1 [JsonXml 0.4][#jsonxml-04]
7.1.2 JsonXml 0.3
7.1.3 JsonXml 0.2
8 Contributing
9 Special Thanks
10 License
JsonXml is JSON expressed in XML. This document presents the structural part of JsonXml, as well as the normative specification of the JsonXml API. It also contains a directory of links to related resources.
The definition of the JSON Schema Definition Language depends on the following specifications: RFC4627❐, RFC7159❐, and XMLSchema❐.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
Provide an encoding of JSON documents in an analogous form that uses XML semantics, referred to as JsonXml documents.
-
The JsonXml documents MUST be able to represent any and all legal JSON documents, as specified by RFC2119.
-
The JsonXml documents MUST be translatable to JSON documents, and vice versa, preserving all normative and non-normative features of the original document.
-
The JsonXml documents MUST provide meaningful and useful validation features via XSD validation.
The JsonXml sub-project provides convenience utilities for converting JSON documents to XML. The following illustrates example usage of the JxConverter class.
String xml = JxConverter.jsonToXml(new JsonReader(new FileReader("example.json")));String json = JxConverter.xmlToJson(new FileInputStream("example.xml"));The JsonXml Schema defines XML elements that represent an XML-equivalent of a JSON document. The JsonXml Schema represents the JSON value types as follows:
The false and true string literals.
Example: true
A double-quoted string. A JSON string may require to be escaped to a string that is legal for XML. The escaped characters are Predefined Entities in XML❐.
Example: "string"
A number that conforms to the RFC4627❐ section 2.4.
Example: 6.626E-34
A JSON object is represented by the <o> element. The <o> element does not have attributes, and may contain 0 or more <p> elements.
A JSON object property is represented by the <p> element. The <p> element contains an attribute n that specifies the property's name. The content of the <p> element can be one of boolean type, string type, number type, object type, or array type.
A JSON array is represented by the <a> element. The <a> element does not have attributes, and may contain 0 or more space delimited members conforming to boolean type, string type, number type, object type, or array type.
The null JSON value is represented by the string null.
The JsonXml API offers facilities for validating and converting JSON and JSONx documents.
The JxConverter class contains utility methods for conversion of JSON documents to XML documents, and vice versa.
Example: Convert a JSON document to a JSONx document
JxConverter.jsonToXml(new JsonReader(json, false), true);Example: Convert a JSONx document to a JSON document
JxConverter.xmlToJson(new ByteArrayInputStream(xml.getBytes()), true);This section provides a sample JSON and its JSONx alternative.
{
"id": "WH-7YX49823S2290830K-0JE13296W68552352",
"event_version": "1.0",
"create_time": "2016-05-31T17:53:29Z",
"resource_type": "refund",
"event_type": "PAYMENT.SALE.REFUNDED",
"summary": "A $ 14.99 USD sale payment was refunded",
"resource": {
"id": "29B43325P49508437",
"state": "completed",
"amount": {
"total": "14.99",
"currency": "USD"
},
"refund_to_payer": {
"value": "14.99",
"currency": "USD"
},
"parent_payment": "PAY-9MX90473V8752831HK5G4RDI",
"sale_id": "02399573KS095945W",
"create_time": "2016-05-31T17:52:18Z",
"update_time": "2016-05-31T17:52:18Z",
"links": [
{"href": "https://api.paypal.com/v1/payments/refund/29B43325P49508437", "rel": "self", "method": "GET"},
{"href": "https://api.paypal.com/v1/payments/payment/PAY-9MX90473V8752831HK5G4RDI", "rel": "parent_payment", "method": "GET"},
{"href": "https://api.paypal.com/v1/payments/sale/02399573KS095945W", "rel": "sale", "method": "GET"}
]
},
"links": [
{"href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352", "rel": "self", "method": "GET"},
{"href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352/resend", "rel": "resend", "method": "POST"}
]
}<o
xmlns="http://www.jsonx.org/jsonxml-0.4.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.jsonx.org/jsonxml-0.4.xsd http://www.jsonx.org/jsonxml.xsd">
<p n="id"> "WH-7YX49823S2290830K-0JE13296W68552352"</p>
<p n="event_version"> "1.0"</p>
<p n="create_time"> "2016-05-31T17:53:29Z"</p>
<p n="resource_type"> "refund"</p>
<p n="event_type"> "PAYMENT.SALE.REFUNDED"</p>
<p n="summary"> "A $ 14.99 USD sale payment was refunded"</p>
<p n="resource"> <o>
<p n="id"> "29B43325P49508437"</p>
<p n="state"> "completed"</p>
<p n="amount"> <o>
<p n="total"> "14.99"</p>
<p n="currency"> "USD"
</p></o></p>
<p n="refund_to_payer"> <o>
<p n="value"> "14.99"</p>
<p n="currency"> "USD"
</p></o></p>
<p n="parent_payment"> "PAY-9MX90473V8752831HK5G4RDI"</p>
<p n="sale_id"> "02399573KS095945W"</p>
<p n="create_time"> "2016-05-31T17:52:18Z"</p>
<p n="update_time"> "2016-05-31T17:52:18Z"</p>
<p n="links"> <a>
<o><p n="href"> "https://api.paypal.com/v1/payments/refund/29B43325P49508437"</p> <p n="rel"> "self"</p> <p n="method"> "GET"</p></o>
<o><p n="href"> "https://api.paypal.com/v1/payments/payment/PAY-9MX90473V8752831HK5G4RDI"</p> <p n="rel"> "parent_payment"</p> <p n="method"> "GET"</p></o>
<o><p n="href"> "https://api.paypal.com/v1/payments/sale/02399573KS095945W"</p> <p n="rel"> "sale"</p> <p n="method"> "GET"</p></o>
</a>
</p></o></p>
<p n="links"> <a>
<o><p n="href"> "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352"</p> <p n="rel"> "self"</p> <p n="method"> "GET"</p></o>
<o><p n="href"> "https://api.paypal.com/v1/notifications/webhooks-events/WH-7YX49823S2290830K-0JE13296W68552352/resend"</p> <p n="rel"> "resend"</p> <p n="method"> "POST"</p></o>
</a>
</p></o>- A JsonXml schema document XSD jsonxml-0.4.xsd❐ for JsonXml documents.
- A JsonXml schema document XSD jsonxml-0.3.xsd❐ for JsonXml documents.
- A JsonXml schema document XSD jsonxml-0.2.xsd❐ for JsonXml documents.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
Special thanks to EJ Technologies for providing their award winning Java Profiler (JProfiler) for development of the JSONx Framework.
This project is licensed under the MIT License - see the LICENSE.txt file for details.