XSD JSON
Since Camel 4.24
The XSD JSON data format maps XML to JSON and back, driven by an XML Schema: an .xsd file, or a .wsdl file whose inline types are read. It is meant for the XML payloads of SOAP services, for example with camel-cxf in PAYLOAD mode, in low-code routes (YAML DSL and Kamelets) that have no classes generated from the schema.
A mapping without a schema, such as the one of XJ, loses information: every value is text, one repeated element gives an object and two give an array, and going back to XML the JSON has to list its fields in the right order and the route has to know the namespaces. With the schema:
-
the values have the JSON type of their XML Schema type: numbers, booleans and strings,
-
an element that may repeat is always a JSON array, even with one item,
-
marshalwrites the elements in the order of the schema, whatever the order of the JSON fields, -
marshalputs every element and attribute in its namespace, followingelementFormDefault,attributeFormDefaultandform, across imported schemas. The JSON has local names only.
unmarshal reads XML into JSON text, and marshal writes XML from JSON (JSON text in a String, bytes, a stream or a file, or a Map). The schema is read once, when the data format starts. The module has one third-party dependency, Apache XmlSchema, the library that Apache CXF uses as well.
XSD JSON Options
The XSD JSON dataformat supports the following options which are listed below.
| Name | Default | Java Type | Description |
|---|---|---|---|
| Required The XML Schema to use: an .xsd file, or a .wsdl file whose types (every xs:schema in wsdl:types) are read. A resource such as classpath:orders.xsd, file:schemas/orders.wsdl or an https URL. Imports and includes are resolved relative to it, with the same scheme only. | ||
| The root element: a global element of the schema, as {namespace}name or as a local name that is unique in the schema. Needed to marshal (JSON to XML) unless includeRoot is enabled. On unmarshal the XML document names its root element, and this option only restricts it. The header CamelXsdJsonElement overrides it per message. | ||
|
| Whether the JSON holds the root element as its single field, such as \{getOrder: \{…}}, instead of the content of the root element. | |
| A prefix for the JSON fields of XML attributes, such as _. By default attributes and child elements share the JSON object without a prefix. | ||
|
| The JSON field of the text of an element with simple content and attributes, such as \{currency: EUR, value: 9.95}. | |
|
| Whether to skip XML elements and attributes, or JSON fields, that the schema does not declare, instead of failing. | |
|
| Whether to indent the output, the JSON on unmarshal and the XML on marshal. |
Message Body
The message body at each side of the XSD JSON data format: Marshal input and Unmarshal input are the bodies marshal and unmarshal can take, and Marshal output and Unmarshal output the body after them.
| Side | Body | Description |
|---|---|---|
Marshal input |
| The JSON to write as XML: JSON text (a String, bytes, a stream or a file), or a Map of the root element. |
Marshal output |
| The XML in the stream cache, or a byte array when stream caching is off. |
Unmarshal input |
| |
Unmarshal output |
| The JSON text, typed and ordered by the schema. |
The bodies are the ones with the default options. A side that is not listed is not known, and tooling does not guess it. The carriers, the sides and the tools that use them are described in Message Body Types.
The root element
The JSON is the content of the root element: {"orderId": "42"} for <getOrder><orderId>42</orderId></getOrder>. With includeRoot the JSON has the root element as its single field instead: {"getOrder": {"orderId": "42"}}.
-
unmarshal: the XML names its root element, which must be a global element of the schema. Whenelementis set, the root element must be that one. -
marshal: theelementoption names the root element, as{namespace}nameor as a local name that is unique in the schema. WithincludeRoot, the single field of the JSON names it, so the option is not needed.
The CamelXsdJsonElement header overrides the element option for one message, for example when the reply of a SOAP service differs per operation. It may only name a global element of the schema. As a Camel* header, it is removed from messages that come in over HTTP by the header filter.
Mapping
| XML Schema | JSON | Notes |
|---|---|---|
| number | |
| number | The exact value and scale: |
| number |
|
|
|
|
| array | The items, split on whitespace, with the type of the item type. |
every other simple type: | string | The text as it is. A restriction maps as its base type. |
an element with | array | Always an array, even with one item. On marshal a single value is accepted as an array of one, and an empty array writes no element. |
a missing optional element | no field | |
an attribute | a field | Named |
simple content with attributes |
| The text is the field named by |
|
| On marshal |
| object | Marshal writes the children in the order of the sequence. Inside a repeating sequence the items are written by index: |
| object | Marshal keeps the order of the JSON. |
| object | Marshal writes the branch that is present, and fails when the JSON has more than one. In a repeating choice the items of each branch are written together, in the order of the branches, so the order between the branches is not kept. |
| Resolved by the schema: an extension is the content of the base type followed by its own. |
A JSON field that the schema does not declare fails, and so does an XML element or attribute, unless ignoreUnknown is set, which skips them. A value that does not fit its type, such as cheap for an xs:decimal, fails with a message that names the field.
Two children of one type with the same local name, or an attribute and a child element with the same name, cannot be told apart in JSON. The message names them, and for the attribute and element case the attributePrefix option solves it. When element is set, such a conflict fails when the data format starts.
Not supported
The following constructs are not mapped. A schema that has them can still be used for the other elements; the mapping fails with a message that names the construct when a message reaches one:
-
xs:anycontent (wildcards) and elements ofxs:anyTypeor without a type. Anxs:anyAttributeis accepted, and the attributes it allows are skipped. -
mixed content (
mixed="true"), -
substitution groups and abstract elements,
-
abstract types and
xsi:typewith another type than the declared one.
The data format does not validate the XML against the schema: use the Validator component or the schema validation of camel-cxf for that.
Security
The schema is configuration of the route and so is trusted. Even so, the schema, the WSDL and every document they import or include are parsed with DOCTYPE declarations refused and external entities and XInclude turned off. xs:import and xs:include are resolved relative to the document that has them, and are only followed to resources with the same scheme as the schema option: a schema loaded from https: cannot pull in a file: or classpath: resource.
The message XML is read with StAX with DTDs and external entities turned off, and a document with a DOCTYPE is refused. Nothing from the message is evaluated. The nesting of elements is limited (512 levels, or less when the XML parser of the JVM has a lower limit). The size of a message is otherwise limited by the route.
Usage
The WSDL of the following examples is a document/literal service with the operation getOrder:
<wsdl:types>
<xs:schema targetNamespace="http://example.com/orders" elementFormDefault="qualified">
<xs:complexType name="Item">
<xs:sequence>
<xs:element name="sku" type="xs:string"/>
<xs:element name="quantity" type="xs:int"/>
<xs:element name="price" type="xs:decimal"/>
</xs:sequence>
</xs:complexType>
<xs:element name="getOrder">
<xs:complexType><xs:sequence>
<xs:element name="orderId" type="xs:string"/>
</xs:sequence></xs:complexType>
</xs:element>
<xs:element name="getOrderResponse">
<xs:complexType><xs:sequence>
<xs:element name="orderId" type="xs:string"/>
<xs:element name="item" type="tns:Item" maxOccurs="unbounded"/>
</xs:sequence></xs:complexType>
</xs:element>
</xs:schema>
</wsdl:types> The response
<getOrderResponse xmlns="http://example.com/orders">
<orderId>42</orderId>
<item><sku>A-1</sku><quantity>2</quantity><price>9.95</price></item>
</getOrderResponse> is unmarshalled to
{"orderId": "42", "item": [{"sku": "A-1", "quantity": 2, "price": 9.95}]} and the JSON {"orderId": "42"} is marshalled with element=getOrder to
<?xml version="1.0" encoding="UTF-8"?><tns:getOrder xmlns:tns="http://example.com/orders"><tns:orderId>42</tns:orderId></tns:getOrder> The prefix of a namespace is the one that the schema declares for it, else ns1, ns2 and so on.
XML to JSON
-
Java
-
XML
-
YAML
from("direct:reply")
.unmarshal().xsdJson("classpath:orders.wsdl")
.to("mock:json"); <route>
<from uri="direct:reply"/>
<unmarshal>
<xsdJson schema="classpath:orders.wsdl"/>
</unmarshal>
<to uri="mock:json"/>
</route> - route:
from:
uri: direct:reply
steps:
- unmarshal:
xsdJson:
schema: classpath:orders.wsdl
- to:
uri: mock:json JSON to XML
-
Java
-
XML
-
YAML
from("direct:request")
.marshal().xsdJson("classpath:orders.wsdl", "getOrder")
.to("mock:xml"); <route>
<from uri="direct:request"/>
<marshal>
<xsdJson schema="classpath:orders.wsdl" element="getOrder"/>
</marshal>
<to uri="mock:xml"/>
</route> - route:
from:
uri: direct:request
steps:
- marshal:
xsdJson:
schema: classpath:orders.wsdl
element: getOrder
- to:
uri: mock:xml