Skip to main content

XML Schemas

XML is a hierarchical, text-based format with strong support for structure, attributes, and namespaces.
MAPS supports XML payloads by combining XML parser configuration with schema metadata stored in SchemaConfig.

This page describes how XML schemas are represented, how parsing is configured, and how XML data is mapped into Typed Events.

1. Overview

XML offers:

  • nested elements and attributes
  • optional namespaces
  • optional validation against a schema (XSD)
  • ordered document structure

MAPS uses:

  • SchemaConfig to describe the schema resource and metadata
  • XmlConfig to control how the XML is parsed
  • Jackson’s XmlMapper to walk the XML tree and build the Typed Event

2. Schema Format (SchemaConfig + XmlConfig)

An XML schema entry is represented as a SchemaConfig with format = "xml" and an XML-specific schema object:

{
  "versionId": "1d598694-5ff3-4995-8942-36e4a710b075",
  "description": "Unit test schema for temperature readings",
  "labels": {
    "uniqueId": "113804e6-cb5d-49ba-aeb2-8dffc1108f3c",
    "comments": "Unit Tests",
    "resource": "sensor",
    "interface": "Temperature C",
    "source": "tcp://localhost:1883/topic2"
  },
  "format": "xml",
  "schema": {
    "namespaceAware": true,
    "validating": true,
    "coalescing": true
  },
  "notBefore": "2025-11-07T23:01:16.1187442Z",
  "expiresAfter": "2025-11-27T23:01:16.1187442Z"
}

The schema object maps to the following configuration type:

@Getter
@Setter
public static final class XmlConfig {
    private String rootEntry;
    private boolean namespaceAware = false;
    private boolean validating = false;
    private boolean coalescing = false;
}

When format is "xml", the server treats schema as an XmlConfig instance and applies these settings when creating an XmlMapper.

3. XmlConfig Fields

3.1 rootEntry​

Optional name of the logical root element to be treated as the entry point.

  • If set, MAPS will focus on this element when turning XML into a Typed Event.
  • If unset, the document’s outermost element is used.

Example:

"schema": {
  "rootEntry": "measurement",
  "namespaceAware": true
}

For an XML document like:

<measurement xmlns="urn:example:sensors">
  <timestamp>2025-01-01T10:00:00Z</timestamp>
  <temperature>20.1</temperature>
</measurement>

measurement becomes the top-level object for the Typed Event.

3.2 namespaceAware​

Controls whether the XML parser is namespace-aware.

  • true

    • Distinguishes elements and attributes by namespace URI + local name.
    • Necessary when working with XML vocabularies that rely on namespaces.

  • false

    • Treats element and attribute names as plain local names.
    • Simpler, but can collapse distinct elements that differ only by namespace.

This is wired through to the underlying XML parser used by XmlMapper.

3.3 validating​

Enables or disables XML validation.

  • true

    • Instructs the XML parser to validate incoming documents against a schema (for example, XSD) when configured.
    • Invalid XML results in parse errors and the event is rejected.

  • false

    • XML is parsed without schema validation.
    • Structure is still turned into a Typed Event, but structural mistakes may go unnoticed.

The actual XSD or schema artifact can be attached to the SchemaConfig using the standard schema mechanisms (for example, schemaBase64 or external URL), while validating controls whether it is enforced at parse time.

3.4 coalescing​

Controls text node coalescing.

  • true

    • Adjacent text nodes are merged into a single text node.
    • Useful when pretty-printing or whitespace leads to multiple text segments.

  • false

    • Text nodes remain as they appear in the XML stream.

For typical payloads, true is recommended so that element text values are presented as single strings in the Typed Event.

4. XML Parsing Implementation

MAPS uses Jackson’s XML support:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.xml.XmlMapper;
import com.fasterxml.jackson.core.type.TypeReference;

A configured XmlMapper is built using XmlConfig:

  • namespaceAware → influences how element and attribute names are resolved
  • validating → toggles underlying parser validation (when schema is available)
  • coalescing → merges adjacent text nodes

The parsed XML tree is then walked and converted into the internal Typed Event model.

5. Typed Event Mapping

XML is hierarchical. MAPS maps it into a structured Typed Event:

  • XML elements → nested objects / fields
  • repeated elements → arrays or lists
  • attributes → fields (according to configured mapping rules)
  • text content → scalar fields (string, numeric, boolean when inferrable)

Example XML:

<measurement>
  <timestamp>2025-01-01T10:00:00Z</timestamp>
  <temperature unit="C">20.1</temperature>
  <humidity>45</humidity>
</measurement>

Example Typed Event shape:

{
  "measurement": {
    "timestamp": "2025-01-01T10:00:00Z",
    "temperature": {
      "value": 20.1,
      "unit": "C"
    },
    "humidity": 45
  }
}

Exact field naming depends on the mapping conventions used in the XML-to-JSON conversion (as implemented by XmlMapper and the server’s Typed Event builder).

6. Example Xml SchemaConfig

{
  "versionId": "1",
  "name": "Temperature XML",
  "description": "Temperature sensor readings encoded as XML",
  "labels": {
    "uniqueId": "113804e6-cb5d-49ba-aeb2-8dffc1108f3c",
    "resource": "sensor",
    "interface": "sensor.temperature.xml"
  },
  "format": "xml",
  "schema": {
    "rootEntry": "measurement",
    "namespaceAware": true,
    "validating": true,
    "coalescing": true
  }
}

7. Limitations and Considerations

  • XML supports attributes vs elements, namespaces, and ordering.
    MAPS applies deterministic mapping, but consumers should treat field layout as defined by the schema and mapping conventions, not by raw XML serialization.

  • Validation requires a configured schema (for example, XSD).
    validating = true alone does not define the rules; it only turns enforcement on.

  • Namespaces are important in multi-vocabulary documents.
    Use namespaceAware = true when working with standard XML vocabularies.

  • Coalescing is recommended for typical sensor and event payloads to avoid fragmented text nodes.

8. Integration with MAPS

Once parsed, XML-derived Typed Events participate in:

  • filtering
  • transformation
  • statistics
  • cross-format conversion (for example, XML → JSON → Avro or Protobuf)

The schema metadata (SchemaConfig) ties the XML format into the overall schema registry and processing pipeline.