Metapath Expression Language

Metaschema includes support for an expression language called Metapath, which allows for selecting and evaluating Metaschema modules and data instances that conform to a Metaschema module. 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. This provides consistent portability of Metapath expressions against multiple serialization forms for the same data set.

Metapath is a customization of the XML Path Language (XPath) 3.1, which has been adjusted to work with a Metaschema module-based model. This means the underlying XML Data model used by XPath, which exposes element and attribute nodes, is replaced with the Metaschema data model, which exposes flag, field, and assembly nodes.

XPath was chosen as a basis for Metapath because it provides for both selection of nodes and logical evaluation of node values, the latter of which is required for supporting Metaschema module constraints. Other path languages (e.g., JSON Path, JSON Pointer) were not chosen, due to limitations in evaluation capabilities and because their syntax was specific to JSON.

Data Model

Metapath operates on the Metaschema data model, which differs from XPath’s XML-based data model.

Node Types

The Metaschema data model exposes the following node types:

Unlike XPath’s element/attribute distinction, Metaschema uses assembly/field/flag to represent the hierarchical structure of data. This abstraction allows Metapath expressions to work consistently across JSON, YAML, and XML representations of the same data.

Format-Agnostic Querying

The same Metapath expression queries equivalent data regardless of format. For example, the expression /catalog/metadata/title selects the title field from:

{
  "catalog": {
    "metadata": {
      "title": "Example Catalog"
    }
  }
}

catalog:
  metadata:
    title: Example Catalog

<catalog>
  <metadata>
    <title>Example Catalog</title>
  </metadata>
</catalog>

This format independence is a key feature of Metapath, enabling validation rules and queries to be defined once and applied to any supported serialization format.

Node Identity

Each node in a Metaschema document instance has a unique identity. Two nodes are identical if and only if they represent the same node in the document tree.

Syntax Overview

Metapath expressions follow XPath 3.1 syntax with adaptations for the Metaschema data model.

Path Expressions

Path expressions select nodes from the document tree.

Predicates

Predicates filter node sequences using conditions enclosed in square brackets.

expression[predicate]

Examples:

• control[@id='ac-1'] - Select control with id flag equal to ‘ac-1’
• param[1] - Select the first param child
• part[title] - Select part children that have a title child

Operators

Comparison Operators

Logical Operators

The not() function provides logical negation.

Arithmetic Operators

Sequence Operators

Conditional Expressions

Metapath supports conditional expressions:

if (condition) then expression1 else expression2

Example:

if (count(./memory) > 0) then sum(./memory/byte-size) else 0

Variable References

Variables are referenced using the $ prefix:

$variablename

Variables are bound using <let> declarations in constraints.

Evaluation Context

When a Metapath expression is evaluated, it operates within an evaluation context that determines how the expression is interpreted.

Focus Node

The focus node (also called context node or evaluation focus) is the node against which the expression is evaluated. Path expressions are resolved relative to this node.

• The context item . refers to the current focus node
• Relative paths navigate from the focus node
• The parent axis .. navigates to the focus node’s parent

Dynamic Context

The dynamic context includes:

• Context item: The current focus node
• Context position: The position of the context item within a sequence (1-based)
• Context size: The total number of items in the current sequence
• Variable bindings: Values bound to variables via <let> declarations
• Current date and time: The current timestamp for date/time functions

Evaluation in Constraints

When Metapath expressions are used in constraints, the evaluation context varies by attribute:

For detailed constraint evaluation semantics, see Constraint Processing.

Built-in Functions

Metapath provides a library of built-in functions. Functions may have zero, one, or multiple arguments. Functions are called using the syntax:

function-name()
function-name(argument)
function-name(argument1, argument2, ...)

Node Functions

String Functions

Numeric Functions

Boolean Functions

Differences from XPath 3.1

While Metapath is based on XPath 3.1, there are notable differences:

Data Model Differences

1. Node types: Metapath uses assembly/field/flag instead of element/attribute
2. Format independence: Expressions work across JSON, YAML, and XML representations
3. Module binding: Expressions are interpreted in the context of a Metaschema module

Unsupported Features

The following XPath 3.1 features are not currently supported in Metapath:

• Namespace axis and namespace nodes
• Processing instruction nodes
• Comment nodes
• Some advanced XPath functions (consult implementation documentation)

Extended Features

Metapath extends XPath with:

• Format-agnostic path expressions
• Integration with Metaschema constraints
• Template expressions in constraint messages using {expression} syntax

Use in Constraints

Metapath expressions are primarily used in Metaschema constraints for:

For comprehensive constraint documentation, see Constraints.

For detailed information about how Metapath differs from XPath 3.1, including supported features, function library, and data model differences, see Metapath vs. XPath 3.1: Key Differences.