Abstract

The Unified Navigation Language (UNL) is designed as an embeddable query language. This specification describes its syntax, data model, type system, and the necessary components of an execution environment for integration into a host programming language. UNL provides a single, coherent syntax to query, navigate, and transform data across multiple structured formats, including XML, JSON, CSV, and RDF.

Introduction

In an increasingly heterogeneous data ecosystem, developers must master multiple query languages (XPath for XML, JSONPath for JSON, SPARQL for RDF, etc.). UNL was designed to eliminate this complexity by offering a unified abstraction layer.

UNL's key innovations are:

• Optional Navigation ?: A unique syntax to elegantly handle variable or incomplete data structures.
• Node/Leaf Distinction (@): Provides fundamental semantic clarity by distinguishing between navigable containers and final values.
• Advanced Structural Navigation (outer(), root()): Enables complex, type-based navigation jumps that are difficult to achieve with other languages.
• Fluid Transformations (|format): The pipe operator allows for on-the-fly data conversion within a single navigation expression.
• Native URI and Namespace Support: Full integration with semantic web standards (RDF, XML) via EQName syntax.
• Unified Syntax: One language to rule all your formats.

Design Principles

• LALR(1) Parsable: The grammar is designed to be unambiguous and easily parsable.
• Extensible: The system can incorporate new formats without changing the core parser.
• Compatible: It is inspired by the best ideas from XPath and CSS without creating conflicts.
• Intuitive: The syntax is designed to be read naturally.

Operating Models

A UNL query is always evaluated against an initial context. The initial context can be a single document or a sequence of documents.

// context: Node(Object)
let myJson = { "user": { "name": "John" } };
// query: String
let inMemoryQuery = "user/@name";

// unl.run(context: Node, query: String) → Sequence(Leaf)
let result = unl.run(myJson, inMemoryQuery);
// result is a Sequence containing one item: Leaf("John")
          

// query: String (A ResourceQuery)
let resourceQuery = "data.csv|csv/*[1]/@price";

// unl.run(query: String) → Sequence(Leaf)
let result = unl.run(resourceQuery);
// result is a Sequence containing one item: Leaf("some_price")
          

Host Language Integration

UNL is designed to be embedded within a host programming language (e.g., Python, JavaScript, Java). A UNL engine implementation MUST be provided with an Execution Environment by the host. This environment supplies the context and configurations necessary to execute a query.

The components of the Execution Environment are:

Initial Context

This is the data upon which the UNL query will run. It corresponds to one of the Operating Models: either a pre-parsed object/node (for In-Memory Navigation) or a string/list of strings representing Resource Locators.

Namespace Mappings

For queries involving prefixed QNames (e.g., foaf:name), the host environment MUST provide a mapping of prefixes to their full namespace URI strings. This is typically a hash map or dictionary. The UNL engine uses this map to resolve EQNames.

Variable Bindings (Optional)

To write secure and reusable queries, an implementation SHOULD support external variable binding. Variables within a UNL query are denoted with a `$` prefix (e.g., $username). The host environment can provide a map of variable names to their values. These values are mapped to UNL's conceptual data types, and can be primitive Leaves (String, Number, Boolean) or structured Nodes (Object, Array).

// Pseudo-code for variable binding
let variables = {
  "user_id": 123,
  "allowed_roles": ["admin", "editor"]
};
// Use a numeric variable in a predicate
unl.run(context, "users[@id = $user_id]", { variables });
// Use an array variable in a predicate
unl.run(context, "users[role = $allowed_roles]");
            

Custom Function Library (Optional)

For advanced extensibility, an implementation MAY allow the host language to register custom functions. To prevent name collisions with built-in functions, custom functions MUST be namespaced. The host environment provides a mapping of namespace prefixes to collections of functions.

// Pseudo-code for registering and using a custom function
// my_validators.js
const is_internal_email = (email_string) => email_string.endsWith('@example.com');

// Main application
unl.registerFunctionLibrary("validate", { isInternal: is_internal_email });

unl.run(context, "//user[validate:isInternal(@email)]");
            

Sequence Transformations

UNL includes a powerful two-stage pipeline model to process sequences of results. This allows for both efficient, low-memory streaming and complex, full-sequence aggregations.

Fundamental Principles

UNL's data model is based on three core principles.

Node (No Prefix)

Represents a navigable structure that contains other nodes or leaves. Examples: an XML element, a JSON object, a CSV row represented as a node.

Leaf (@ Prefix)

Represents a final, non-navigable atomic value. It is the endpoint of a navigation path. Examples: a string, a number, a boolean value, or a node's metadata attribute.

The Pipe Transformation Principle (| Operator)

A Leaf is normally a terminal point of navigation. However, the pipe operator | allows the value of a Leaf to be re-interpreted as a new data source. This operation performs a type-casting of the leaf's value, creating a new, navigable Node structure. This mechanism is the key to nested parsing and is fundamental to UNL's power.
Symbolically: .../Leaf(String) |json → New Node(JSON)

Type System and Comparisons

UNL operates on a set of conceptual data types defined in the Data Model Mapping appendix. The behavior of comparison and equality operators depends on these types.

Navigation Syntax

Handling Special Characters and Quoting

Many characters have a special syntactic meaning in UNL (e.g., / ? @ * [ ] ( ) | . :). If a node or leaf name in the source data contains one of these characters, it must be enclosed in single (') or double (") quotes to be treated as a literal name.

This quoting mechanism applies to any path segment that is a name test.

Rules for Quoting

When to Quote

A name segment MUST be quoted if it contains any special UNL characters or if it is ambiguous with a numeric literal (e.g., a key named "3").

Escaping within Quotes

To include a quote character within a quoted name, it MUST be escaped with a backslash (\). A literal backslash MUST also be escaped (\\).

Examples

// Example 1: JSON key with a forward slash
// Data: { "a/b": { "c": 1 } }
// Query: "a/b"/c/@value

// Example 2: Filename with special characters
// Resource Locator: my-archive.zip
// Path in zip: reports/report-[v1].xml
my-archive.zip|decomp:zip/reports/"report-[v1].xml"|xml//...

// Example 3: XML element name with dots
// Data: <com.example.Node>Value</com.example.Node>
// Query: "com.example.Node"/text()

// Example 4: Quoting a name containing quotes
// Data: { "node with \"quotes\"": 42 }
// Query: "node with \\\"quotes\\\""/@value
    

URIs and Namespaces

UNL provides robust support for namespaced data formats like XML and RDF. To ensure unambiguous queries, UNL adopts the EQName (Extended QName) notation from [[XPATH-31]].

Prefixed QName (e.g., atom:title)

The classic prefix:local-name syntax. Its use is supported but discouraged in favor of EQNames, as it relies on an external context to map the prefix to a namespace URI.

EQName / URI-Qualified Name (e.g., Q{http://www.w3.org/2005/Atom}title)

The Q{namespace-uri}local-name syntax. This is the recommended approach as it includes the full namespace URI directly within the expression, making queries self-contained and unambiguous.

Because RDF predicates are full URIs, using the EQName syntax is the most precise method for navigating RDF graphs.

// EQName syntax is unambiguous and recommended
Q{http://www.w3.org/2005/Atom}feed/Q{http://www.w3.org/2005/Atom}entry/title

// EQName used to query an RDF property
Q{http://xmlns.com/foaf/0.1/}Person/Q{http://xmlns.com/foaf/0.1/}knows

// Full URI used in a predicate value
*[rdf:type = <http://xmlns.com/foaf/0.1/Person>]
    

Format Transformations

The pipe operator (|) is used for transformations. As described in the Operating Models, the first pipe in a ResourceQuery serves to load and parse a resource. Subsequent pipes transform the current selection, often by type-casting a Leaf's value into a new Node structure, as defined in the Core Principles.

Data Serialization Formats

These transformations parse a string-based or binary Leaf or resource into a navigable Node structure.

Filesystem Operations

This operator treats a local directory path as a navigable archive-like structure.

Decompression (decomp: prefix)

These transformations operate on a resource or a binary Leaf, decompressing it to expose a virtual filesystem of Nodes or a raw binary stream.

Decoding (decode: prefix)

These are intermediate transformations that type-cast a Leaf's value.

Predicates (Filters)

Predicates, placed between square brackets [...], are used to filter sets of nodes. Path expressions inside a predicate can be absolute (starting with /) or relative to the current node.

// Filter items where category leaf matches a global configuration value
// The path /config/default_category starts from the document root
//item[@category = /config/default_category]
    

Built-in Functions

Built-in functions are called without a namespace prefix (e.g., text()). Custom functions provided by a host language MUST use a namespace prefix (e.g., myfuncs:my_func()).

Examples

The following examples illustrate the two operating models and advanced features.

// In-Memory: Get an attribute from an XML node
doc/book/@isbn

// In-Memory: Get the name from the first object in a JSON array
users[1]/@name

// Resource Loading: Get a column from a specific row in a CSV file
data.csv|csv/*[@id="ABC"]/@name

// Resource Loading: Navigate into a ZIP file to get an XML element
http://example.com/data.zip|decomp:zip/docs/report.xml|xml//title
        

// Recursive Parsing: A leaf's value is piped into a new parser
// Gets the 2nd tag from a comma-separated string within a CSV cell
users.csv|csv/*[1]/@tags|csv/*[1]/@*[2]

// API Chaining: A payload contains gzipped XML data
// The query decodes, decompresses, and parses the data in one pipeline
api/data|json/@payload|decode:base64|decomp:gz|xml//important

// Sequence Processing: Get all unique, sorted authors from a set of files
"data/*.xml"|xml//author/text()||distinct|order-by(.)