Understanding XML path

XML path is a syntax used to navigate through elements in an XML document. Think of it as an address system for finding specific information. When you have a complex XML file, it allows you to pinpoint the exact piece of data you need.

This is crucial for data mapping, as it lets you accurately select source data to transform and move to a target system.

warning

Zparse does not support the full XPath specification, only basic selection.

XML example

We will use the following XML document, which contains a list of customer orders, as the basis for all our examples.

<orders>
  <order>
    <purchase_id>ORD-9876</purchase_id>
    <client_details>
      <firstname>Jane</firstname>
      <lastname>Smith</lastname>
      <contact_email>jane.smith@example.com</contact_email>
    </client_details>
    <items>
      <item>
        <sku>TS-BLUE-L</sku>
        <item_name>Blue T-Shirt - Large</item_name>
        <qty>1</qty>
        <price>19.99</price>
      </item>
      <item>
        <sku>MUG-LOGO</sku>
        <item_name>Company Logo Mug</item_name>
        <qty>2</qty>
        <price>9.5</price>
      </item>
    </items>
  </order>
  <order>
    <purchase_id>ORD-9877</purchase_id>
    <client_details>
      <firstname>John</firstname>
      <lastname>Doe</lastname>
      <contact_email>john.doe@example.com</contact_email>
    </client_details>
    <items>
      <item>
        <sku>TS-RED-M</sku>
        <item_name>Red T-Shirt - Medium</item_name>
        <qty>2</qty>
        <price>19.99</price>
      </item>
    </items>
  </order>
</orders>

Basic selection

You can select nodes by defining a path starting from the root. The forward slash / is used to separate elements in the path.

A path selects the first element that matches it. This is what you get when extracting a scalar value or a single XML node. All matching elements are returned only when the path is used by a function with Value type = Array (for example Value from path), which emits every match as an array of XML nodes.

Path	First match (scalar / XML)	All matches (Value type = Array)
/orders	The root element <orders>.	[<orders>]
/orders/order	The first <order> element (ORD-9876).	Both <order> elements.
/orders/order/items/item	The first <item> of the first order.	All three <item> elements.

Path rules

• Paths are absolute and include the root tag: the first path segment must be the root element's own name (/orders/..., not /order/...).
• The leading / is optional: orders/order and /orders/order are equivalent.
• ., / or an empty path select the current node itself.

Gotcha

A single-segment path (no / after the first name, e.g. orders on its own) returns the current (root) node without checking that the name matches.

Not supported

Zparse only implements the basic selection described above. The following XPath features are not supported:

• // descendant search (e.g. //item).
• Predicates and indexes: [1], [last()], [@id='x']...
• @attr attribute syntax — attributes are read with the dedicated Key parameter of Attribute from path.
• Wildcards (*).
• XPath functions (text(), count()...).