Cameleer

XML data format (Jackson XML)

The jacksonXml data format converts between XML text and a structured body: object keys become elements, lists repeat the element, and options map keys to attributes, text and namespaces.

Name: jacksonXml · Also: xml, jacksonxml (and jaxb when cameleer-soap is not registered) · Crate: cameleer-core · Cargo feature: none, always included (build features) · Apache Camel: Jackson XML

When to use it

  • Convert JSON from a REST API or an LLM into XML for a legacy or SOAP-style system, and back.
  • Read XML documents into a map so Simple, JSONPath or jq can pick fields without XPath.
  • Produce XML with attributes, namespaces and wrapper elements without writing a template.

With cameleer_main::new_main (the cameleer CLI), jaxb is the schema-typed JAXB data format from cameleer-soap; use jacksonXml or xml for this generic mapping.

Marshal and unmarshal

directionbody inbody out
marshalan object (or JSON text of one)XML text with the root element rootName. Sets Content-Type: application/xml unless contentTypeHeader: false.
unmarshalXML textan object: child elements become keys (repeated elements become lists), attributes become keys too, text-only elements become strings. Namespace prefixes are dropped.

Values are not typed on unmarshal: <qty>2</qty> gives the string "2".

Difference from Apache Camel: there is no class binding. Jackson annotations are replaced by the options attributes, textProperty, properties, namespaces and wrappers.

Example

Turn a JSON order into XML, with id as an attribute:

yaml example: jacksonxml-json-to-xml
- route:
    id: json-to-xml
    from:
      uri: direct:json-to-xml
      steps:
        - unmarshal:
            json: {}
        - marshal:
            jacksonXml:
              rootName: order
              attributes: id
json
{"id":42,"customer":"Ada","item":[{"sku":"A1","qty":2},{"sku":"B2","qty":1}]}
xml
<order id="42"><customer>Ada</customer><item><sku>A1</sku><qty>2</qty></item><item><sku>B2</sku><qty>1</qty></item></order>

Read XML into a structure and write it as JSON:

yaml example: jacksonxml-xml-to-json
- route:
    id: xml-to-json
    from:
      uri: direct:xml-to-json
      steps:
        - unmarshal:
            xml: {}
        - marshal:
            json: {}
xml
<order id="42"><customer>Ada</customer><item><sku>A1</sku></item><item><sku>B2</sku></item></order>
json
{"id":"42","customer":"Ada","item":[{"sku":"A1"},{"sku":"B2"}]}

Wrap a list in a parent element and declare a namespace:

yaml example: jacksonxml-wrappers-namespace
- route:
    id: xml-wrappers
    from:
      uri: direct:xml-wrappers
      steps:
        - unmarshal:
            json: {}
        - marshal:
            jacksonXml:
              rootName: catalog
              namespace: urn:acme:catalog
              wrappers: "books:book"
json
{"books":["Dune","Emma"]}
xml
<catalog xmlns="urn:acme:catalog"><books><book>Dune</book><book>Emma</book></books></catalog>

Rust DSL

rust
b.from("direct:xml-rust")
    .unmarshal(DataFormatDefinition::json())
    .marshal(DataFormatDefinition::xml().root_name("order"));

Options

optiondefaultdescription
rootNamerootRoot element name; may be p:name or {uri}name.
prettyPrintfalseIndent the XML.
xmlDeclarationfalseStart with <?xml version="1.0" encoding="UTF-8"?>.
contentTypeHeadertrueSet Content-Type: application/xml on marshal.
attributePrefix@Keys starting with it are written as attributes. When set explicitly, unmarshal also prefixes attribute keys with it.
attributes(none)Comma separated keys always written as attributes.
textProperty""Key holding the element's own text (#text and $ are always accepted on marshal).
properties(none)key:xmlName,... renames; xmlName may be p:local or {uri}local.
namespace(none)Default namespace of the root element (xmlns="...").
namespaces(none)prefix=uri,... declared on the root element.
wrappers(none)key:itemName,...: write the list key inside a <key> wrapper with <itemName> items; unwrapped again on unmarshal.

Common questions

How do I convert JSON to XML?

unmarshal: {json: {}} then marshal: {jacksonXml: {rootName: order}}. For XML that must match an XSD, use the JAXB data format or an XSLT template instead.

How do I write an attribute instead of an element?

List the key in attributes: id,version, or prefix the key with @ ({"@id": 42}).

Why are numbers strings after unmarshal?

XML has no types. Convert the fields you need, or use the schema-typed JAXB format.

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.

Edit this page on GitHub