Metapath vs. XPath 3.1: Key Differences

Overview

Metapath is an expression language that is part of the Metaschema Information Modeling Framework. While Metapath is explicitly described as “a customization of the XML Path Language (XPath) 3.1, which has been adjusted to work with a Metaschema module-based model” (Metapath Specification), there are significant differences between the two languages.

The Metapath specification notes: “Not all XPath features are supported by Metapath, the specifics of which will be documented in an updated version of this page in the future” (Metapath Specification).

1. Format Agnosticism

XPath 3.1

XPath 3.1 is inherently tied to XML. While implementations may work with JSON through conversion, XPath itself assumes XML document structure.

Metapath

Metapath is designed to be format-agnostic and can query:

• XML
• JSON
• YAML

As stated in the specification: “A Metapath can be used to query all Metaschema-supported formats (i.e., JSON, YAML, XML) using a common, Metaschema module-bound syntax. This means a Metapath can be used to query the same data regardless of the underlying format used, as long as that data is bound to a Metaschema module” (Metapath Specification).

This format agnosticism was a primary design goal, as other path languages like JSON Path and JSON Pointer “were not chosen, due to limitations in evaluation capabilities and because their syntax was specific to JSON” (Metapath Specification).

2. Fundamental Data Model Differences

XPath 3.1 Data Model

XPath 3.1 operates on the XML Data Model (XDM) 3.1, which exposes seven kinds of nodes:

• Document nodes (root)
• Element nodes
• Attribute nodes
• Text nodes
• Comment nodes
• Processing instruction nodes
• Namespace nodes

Metapath Data Model

Metapath replaces the XML Data Model with the Metaschema data model, which exposes three primary node types:

Key Distinction: In Metapath, there is no equivalent to XPath’s text nodes, comment nodes, processing instruction nodes, or namespace nodes. The data model is designed around the Metaschema module constructs rather than XML serialization details.

Reference: Information Modeling Specification

3. Node Selection and Addressing

XPath 3.1 Approach

XPath uses axes (child, parent, ancestor, descendant, attribute, etc.) to navigate the XML tree. Attributes are accessed using the @ prefix.

/catalog/book/@isbn
//book/title
../sibling-element

Metapath Approach

Metapath paths reference Metaschema model constructs directly:

• Flags are accessed using the @ prefix, mirroring XPath’s attribute syntax
• Fields and assemblies are accessed as path steps (similar to XPath element navigation)
• Navigation is through the Metaschema module’s defined model structure
• The current context (.) refers to a flag, field, or assembly node

.                    (current node)
..                   (parent node)
@flag-name           (flag on current node)
child-field          (child field or assembly)
$parent/sibling      (variable reference)
parent/@id           (flag 'id' on 'parent' node)

Reference: Constraints Specification - Target

4. Function Library

XPath 3.1

XPath 3.1 includes over 200 built-in functions organized in namespaces including fn:, math:, map:, and array:. See XPath and XQuery Functions and Operators 3.1.

Metapath

Metapath implements a substantial subset of XPath 3.1 functions plus custom extensions. Based on DefaultFunctionLibrary.java is the manifest of all implemented and planned to be implemented functions for the reference implementation. Below is an overview of these functions, categorized thematically into their capabilities.

Core Functions (fn:)

Boolean Functions:

• true(), false(), not(), boolean()

Numeric Functions:

• abs(), ceiling(), floor(), round()
• avg(), count(), max(), min(), sum()

String Functions:

• compare(), concat(), contains()
• starts-with(), ends-with()
• lower-case(), upper-case()
• normalize-space(), string()
• string-length(), string-join()
• substring(), substring-after(), substring-before()
• matches(), tokenize()

Sequence Functions:

• empty(), exists()
• head(), tail(), reverse()
• distinct-values(), index-of()
• insert-before(), remove()
• zero-or-one(), one-or-more(), exactly-one()

Node Functions:

• data(), path(), root()
• local-name(), name(), namespace-uri()
• has-children(), innermost(), outermost()

URI Functions:

• base-uri(), document-uri(), static-base-uri()
• resolve-uri(), QName()

Document Functions:

• doc(), doc-available()

Date/Time Functions:

• current-date(), current-dateTime(), current-time()
• dateTime(), implicit-timezone()

Date/Time Component Extraction:

• year-from-date(), year-from-dateTime()
• month-from-date(), month-from-dateTime()
• day-from-date(), day-from-dateTime()
• hours-from-dateTime(), hours-from-time()
• minutes-from-dateTime(), minutes-from-time()
• seconds-from-dateTime(), seconds-from-time()

Duration Component Extraction:

• years-from-duration(), months-from-duration()
• days-from-duration(), hours-from-duration()
• minutes-from-duration(), seconds-from-duration()

Timezone Functions:

• adjust-dateTime-to-timezone(), adjust-date-to-timezone(), adjust-time-to-timezone()
• timezone-from-date(), timezone-from-dateTime(), timezone-from-time()

Comparison Functions:

• deep-equal()

Higher-Order Functions:

• function-arity(), function-lookup(), function-name()

Array Functions (array:)

• array:get() - Get member at index
• array:size() - Get array size
• array:put() - Replace member at index
• array:append() - Append member
• array:subarray() - Extract subarray
• array:remove() - Remove member at index
• array:insert-before() - Insert member before index
• array:head() - Get first member
• array:tail() - Get all but first member
• array:reverse() - Reverse array
• array:join() - Concatenate arrays
• array:flatten() - Flatten nested arrays

Map Functions (map:)

• map:merge() - Merge maps
• map:size() - Get map size
• map:keys() - Get all keys
• map:contains() - Check if key exists
• map:get() - Get value for key
• map:find() - Find values for key recursively
• map:put() - Add/update entry
• map:entry() - Create single-entry map
• map:remove() - Remove entry
• map:for-each() - Apply function to each entry

Metapath-Specific Functions (mp:)

Cast Functions

Metapath automatically generates cast functions for all Metaschema data types (e.g., xs:string(), xs:integer(), xs:boolean(), etc.).

Functions Marked for Future Implementation

The source code indicates these XPath 3.1 functions are planned but not yet implemented:

P1 (Priority 1):

• generate-id(), last(), replace()
• round-half-to-even(), subsequence(), translate()

P2 (Priority 2):

• format-date(), format-dateTime(), format-integer()
• format-number(), format-time(), position()

P3 (Priority 3):

• array:for-each(), array:filter()
• array:fold-left(), array:fold-right()
• array:for-each-pair(), array:sort()

Namespace URIs:

• XPath Functions namespace: http://www.w3.org/2005/xpath-functions
• Metapath namespace: http://csrc.nist.gov/ns/metaschema/metapath (prefix: mp)

Reference: DefaultFunctionLibrary.java

5. Variable Binding

XPath 3.1

XPath 3.1 supports let expressions for variable binding:

let $x := /catalog/book return $x/title

Metapath

Metapath supports variable binding in two ways:

1. Programmatically - Variables can be bound through the Metapath API when executing expressions
2. Using let statements - Within the Metaschema constraint model via the <let> assembly

Example using let in constraints:

<constraint>
  <let var="parent" expression=".."/>
  <let var="sibling-count" expression="count($parent/sibling)"/>
  <expect target="." test="$sibling-count = 3"/>
</constraint>

Key behaviors:

• Variables are evaluated in encounter order
• If a previous variable is bound with the same name, the new value is bound in a sub-context to avoid side effects
• The sub-context is available to subsequent constraints and child node constraints

Reference: Let Expressions Specification

6. XPath 3.1 Feature Support in Metapath

Metapath supports most XPath 3.1 expression features. Based on the Metapath10.g4 grammar:

Fully Supported XPath 3.1 Features

Supported Axes

Forward axes:

• child::, descendant::, self::, descendant-or-self::
• following-sibling::, following::
• flag:: (Metapath-specific for accessing flags)

Reverse axes:

• parent::, ancestor::, ancestor-or-self::
• preceding-sibling::, preceding::

Abbreviated syntax:

• . (context item), .. (parent), @ (flag/attribute), // (descendant-or-self)

Features Not Supported (Data Model Differences)

Metapath-Specific Extensions

Reference: The grammar is derived from the XPath 3.1 grammar by Ken Domino et al. with modifications for the Metaschema data model.

7. Constraint Integration

XPath 3.1

XPath expressions can be used with XSLT, XQuery, or Schematron for validation, but this requires additional tooling.

Metapath

Metapath is natively integrated with Metaschema’s constraint system. Constraints are first-class citizens:

• allowed-values - Enumerated value restrictions
• expect - Boolean test expressions
• has-cardinality - Occurrence count validation
• index - Create addressable indexes
• index-has-key - Cross-reference validation
• is-unique - Uniqueness validation
• matches - Datatype and regex validation

Reference: Constraints Specification

8. Evaluation Context Differences

XPath 3.1

The evaluation context includes:

• Static context (namespaces, variable declarations, function signatures)
• Dynamic context (context item, position, size, variable values, current date/time)
• Focus (context item, context position, context size)

Metapath

The evaluation context is tied to the Metaschema module:

• The evaluation focus is the content node being processed
• Constraints are evaluated against content nodes associated with definitions
• Variables can be bound through let expressions in the constraint context

Key Point: “A constraint is defined relative to an assembly, field, or flag definition in a Metaschema module. All constraints associated with a definition MUST be evaluated against all associated content nodes” (Constraints Processing).

9. Type System

XPath 3.1

Uses XSD (XML Schema Definition) types and the XDM type hierarchy, including atomic types, node types, and function types.

Metapath

Uses Metaschema data types, which include:

Simple types:

• string, token, uri, uri-reference, uuid
• decimal, integer, non-negative-integer, positive-integer
• boolean
• date, date-time, date-with-timezone, date-time-with-timezone
• day-time-duration, year-month-duration
• base64, email-address, hostname, ip-v4-address, ip-v6-address

Markup types:

• markup-line (inline markup)
• markup-multiline (block-level markup)

Reference: Data Types Specification

10. Implementation

Grammar

The reference implementation and the Metapath specification uses an ANTLR-based grammar for parsing ([Metapath10.g4](https://github.com/metaschema-framework/metaschema-java/blob/develop/core/src/main/antlr4/Metapath10.g4)), derived from but distinct from XPath 3.1’s grammar.

Reference: Metapath10.g4

Available Implementations

• Java: Metaschema Java Tools - Primary implementation
• XSLT: Metaschema XSLT - XSLT-based implementation
• Go: GoComply Metaschema - Community implementation

Summary Comparison Table

References

1. Metapath Expression Language Specification
2. XPath 3.1 W3C Recommendation
3. Metaschema Specification
4. Metaschema Java Tools
5. Information Modeling Specification
6. Constraints Specification
7. Data Types Specification
8. GitHub: metaschema-framework/metaschema
9. GitHub: metaschema-framework/metaschema-java
10. XPath and XQuery Data Model 3.1
11. Metapath10.g4 Grammar
12. BuildCSTVisitor.java
13. DefaultFunctionLibrary.java