ajp — A JSONPATH processor for RFC9535 implemented in Invisible XML, XSLT and XPath

XMLPrague 2024 Presentation

For more detailed information concerning JSONPATH and its definitions, please refer to the XML Prague 2024 presentation JSONPath: an IETF Proposed Standard, with comparisons to XPath [PRAG2024]Alan Painter, JSONPath: an IETF Proposed Standard, with comparisons to XPath, XML Prague, 2024-06-07, https://​archive​.xmlprague​.cz​/2024​/files​/xmlprague​-2024​-proceedings​.pdf#page​=47. . This paper will make extensive use of JSONPATH vocabulary which is described in that paper.

Identifiers, Segments and Selectors

Section 1.4 of RFC9353 [RFC9535]S. Gössner, G. Normington, C Bormann, JSONPath: Query Expressions for JSON, 2024, Internet Engineering Task Force (IETF), https://​datatracker​.ietf​.org​/doc​/rfc9535/. gives an overview of the elements of a JSONPATH query, notably as Identifiers (2), Segments (2 types) and Selectors (5 different selectors). The Identifiers are only used within filter selectors, with the exception of the obligatory first character of any JSONPATH expression that must be the root-identifier, the character '$'. Following the '$' char is a possibly-empty sequence of segments, with each segment being either a child or a descendant segment. Finally, each segment is composed of one or more selectors. This is the very simple structure of a JSONPATH query string.

Figure 1Elements of a JSONPATH query

The SYNTAX of JSONPATH/RFC9535

The details of the JSONPATH query expression are largely described in the RFC9535 ABNF (Augmented Backus Naur Form) grammar [RFC5234]D. Crocker, P. Overell, Augmented BNF for Syntax Specifications: ABNF, https://​www​.rfc​-editor​.org​/rfc​/rfc5234​.txt. which can be used to "parse" the query expression. This grammar is provided in its entirety in Appendix A of RFC9535 [RFC9535]S. Gössner, G. Normington, C Bormann, JSONPath: Query Expressions for JSON, 2024, Internet Engineering Task Force (IETF), https://​datatracker​.ietf​.org​/doc​/rfc9535/. .

The Semantics of JSONPATH/RFC9535

Whereas the ABNF grammar description can be considered to be the syntax of RFC9535, the semantics of the JSONPATH standard are described in other sections of RFC9535, specifically in the sections labelled "Semantics" (i.e. 2.2.2, 2.3.1.2, 2.3.2.2, 2.3.3.2, etc). The semantics are described at length in RFC9535. The experience of developing ajp has shown a few spots where the non-normative JSONPATH Compliance Test Suite [JPTHCTS]Glyn Normington et al., JSONPath Compliance Test Suite, https://​github​.com​/jsonpath​-standard​/jsonpath​-compliance​-test​-suite. greatly clarifies the descriptions in RFC9535. A specific case is described below.

An XSLT package

The current implementation of ajp (i.e. version 0.0.3) is contained within an XSLT 3.0 package. The component that uses ajp must also be XSLT 3.0.

The implementation repo also includes a Java API for calling ajp and retrieving the results.

In general, an XSLT package is meant to be usable from any XSLT environment and host language. In the case of the version 0.0.3 of ajp, the XPath extension functions necessary for the Invisible XML (ixml) parsing are currently available only in Java.

XPath3.1 and JSON

Since version 3.1, the XPath Data Model (XDM, [XDM31]Norman Walsh, John Snelson, Andrew Coleman, XQuery and XPath Data Model 3.1, 2017-03-21, World Wide Web Consortium (W3C), https://​www​.w3​.org​/TR​/xpath​-datamodel​-31/. ) contains types for arrays and for maps, where the JSON object type is the equivalent of an XPath map with a string key. The XPath 3.1 data model can represent JSON as well as the XML data types from previous versions of XDM.

The fundamental structures used in ajp

The XPath definitions for segments and nodelists are fundamental data structures for the implementation.

Nodelist

In section 1.1 Terminology, RFC9535 defines a Nodelist as an ordered list of Nodes. A Node itself is described as a pair of values: a String representing the location of the Node within the Query Argument and the JSON value at that location in the Query Argument.

RFC9535 does not define the concrete structure for the Node and the Nodelist, leaving that to the implementation. Within ajp and using XPath, a Node is defined as a singleton map (i.e. a map with a single entry) with a xs:string key and an item()? value. A Nodelist is an XPath sequence of Nodes.

An example of values in a Nodelist can be seen below. It is important to note that the Nodelist is used as an input as well as an output of segment processing. In addition, a Nodelist is used as an intermediate value for comparison and test expressions within a filter-selector.

Figure 2The XPath Nodelist Structure

Segments

RFC9535 shows the general structure of a JSONPATH query to be the root-identifier (or '$') followed by a sequence of segments, possibly an empty sequence, for which each segment is composed of one or more selectors. The ajp implementation describes this as a sequence of singleton maps, each map having either the key 'child' or 'descendant' to indicate the type of segment, and having a non-empty sequence of arrays of two functions, one array per selector, as the value. This is the output form for the segments as produced by ajp's query compilation. The segments produced by an example JSONPATH query is given below:

Figure 3The XPath Segments Structure

Arrays of Functions for the Selectors

The values in the segments maps are ordered, non-empty sequences of arrays of functions, with one array for each selector in the segment. An array for a selector will have two functions, a Keys() function in the first position of the array and a Test() function in the second position of the array.

Since XPath 3.0, functions have been added to the XPath Data Model (XDM) data types, allowing functions to be arguments of functions, return values of functions and also data values. ajp is using an array to hold the two functions that are used to implement a given selector.

The Keys() and Test() selector functions have the below function signatures. The Keys() function takes, as its single argument $item, a JSON XDM value, and it returns the keys that correspond to that value for that selector. For instance, if the JSON value is an array of size 5 and the selector is the index-selector with index 4 (i.e. 0-based index in JSONPATH), then a call to the Keys() selector function on that array would return a single item, the value of the last element of the array. If the array had size 4, then the call to the selector function Keys() for the smaller array would return an empty sequence, because there is no element at 0-based index 4 in the array. If item is something other than an array, say a JSON object or a JSON primitive, then the index selector Keys() function would also return an empty sequence, since the item itself is not an array.

The Test() function takes three arguments, including a reference to the $root or query argument, and returns a boolean value to indicate if the node should be included in the output nodelist from that segment. Note that for all selectors other than the filter-selector, the Test() function returns a trivial true() value.

Figure 4Signatures of the Selector Functions

Three phases of ajp evaluation

The ajp processor executes globally in three phases as described below. The first two phases correspond to the compile time phase and the third phase is the run time phase, which can be executed repetitively on different JSON values without requiring re-compilation for the same JSONPATH expression.

1. Phase 1 — Using Invisible XML (ixml), generate an XML document / Abstract Syntax Tree (AST) from the JSONPATH query expression.

2. Phase 2 — Using XSLT and the AST from Phase 1, generate the segments description of the query expression.

3. Phase 3 — Using the segments description from Phase 2 and given a JSON value, produce the resulting nodelist output.

The three phases are described in the following diagram.

Figure 5Three phases of processing a JSONPATH expression on a JSON value

Two XPath functions to encapsulate the three phases

The three phases described in the previous section are encapsulated within two XPath functions.

1. $segments := ajp:getSegments($jsonquery)

2. $nodelist := ajp:applySegments($root, $segments)

The function ajp:getSegments() accepts a JSONPATH string argument and returns a segments description. This function essentially is the compilation of the JSONPATH expression into a reusable form. In case of any error in the JSONPATH expression, an error is raised and the segments description is not created.

The function ajp:applySegments() takes two arguments: a JSON value (or Query Argument) and the segments description returned from previous function. ajp:applySegments() can be called multiple times in order to apply the same JSONPATH expression to different JSON values. This function is essentially the runtime phase of JSONPATH evaluation.

Figure 6Two functions that encapsulate the three phases of processing a JSONPATH expression on a JSON value

Errors

RFC9535 Section 2.1 Overview indicates that any errors in the query expression must be discovered independently of any JSON value in the query argument. In the case of ajp, this means that the error must be discovered during the call to ajp:getSegments(). The implementation will raise an XPath error in this case. (See [XPATH31F]Dr Michael Kay, XPath and XQuery Functions and Operators 3.1, 2017-03-21, World Wide Web Consortium (W3C), https://​www​.w3​.org​/TR​/xpath​-functions​-31/. Section 3.1 Raising errors.)

RFC9535 also indicates that no errors can be raised other than errors in the validity of the query expression.

Segment Processing

RFC9535 Section 2.1.2 "JSONPATH Syntax and Semantics -- Semantics" describes how segments are processed.

"The query is a root identifier followed by a sequence of zero or more segments, each of which is applied to the result of the previous root identifier or segment and provides input to the next segment. These results and inputs take the form of nodelists."

"The nodelist resulting from the root identifier contains a single node (the query argument). The nodelist resulting from the last segment is presented as the result of the query."

The Segment Processing is performed in ajp via a few short functions in XPath:

The two-argument version of ajp:applySegments() is called from the using application. Here, the initial $nodelist containing only the query argument (i.e. $root) is constructed and passed to the recursive, three-argument version of ajp:applySegments(), along with the segments description from ajp:getSegments(). As a third parameter, the $root is also passed so that it can be used within a filter-selector in case a subquery references the root-identifier or '$'. This use of $root will be addressed below.

Before returning the result $nodelist to the caller, any $NULL values are replaced with empty sequences by the function ajp:convertNulls(). The reason for the $NULL value is addressed below.

The three-argument version of ajp:applySegments() will apply the selectors of the head segment (i.e. head($segments)?*) to the incoming $nodelist by calling either the ajp:children() or the ajp:descendants() function to traverse the nodes in the $nodelist, apply this segment's selectors and then capture the head segment's output as $resultNodelist in a let variable in order to then pass it to a recursive call to ajp:applySegments() in order to process the selectors of any remaining segments.

These functions implement RFC9535 Section 2.1.2.

Selector Processing

In order to implement the selector processing and traverse the nodes in the $nodelist, either the children or descendants according to the segment type, ajp:applySegments() calls either ajp:children() or ajp:descendants(). It is within this former function, ajp:children(), that all selector processing is performed.

RFC9535 Section 2.5 and 2.5.1.1 describe the output of Nodes in an output Nodelist as a function of the input Nodes in the input Nodelist as well as the selectors within a segment. In Section 2.5, describing in general both child and descendant segments:

For each node in an input nodelist, segments apply one or more selectors to the node and concatenate the results of each selector into per-input-node nodelists, which are then concatenated in the order of the input nodelist to form a single segment result nodelist.

Conclusion: the ajp runtime is very simple

This section has presented the handful of small XPath functions that perform the "runtime" evaluation of a JSONPATH expression that has been "compiled" into a segments description. The brevity and simplicity of these functions give witness to the overall simplicity of the runtime evaluation with this segments description. This evaluation mechanism motivates the creation of the segments description.

Processing the JSONPATH query with Invisible XML (ixml)

Invisible XML (ixml) is a recent initiative that provides tools for describing structured data as a grammar and then serializing the description of the data into XML. [IXML10]Steven Pemberton, Invisible XML Specification, 2022-06-20, CWI, Amsterdam, https://​invisiblexml​.org​/1​.0/. ajp uses ixml for parsing the JSONPATH query as it is defined by the ABNF (Augmented Backus Naur Form) grammar [RFC5234]D. Crocker, P. Overell, Augmented BNF for Syntax Specifications: ABNF, https://​www​.rfc​-editor​.org​/rfc​/rfc5234​.txt. within RFC9535 (Appendix A). ajp uses in its first version the ixml processor nineml [NINEML]Norman Tovey-Walsh, nineml -- A family of Earley and Generalized LL (GLL) parsing tools, https://​github​.com​/nineml​/nineml. but with the expectation that other ixml processors will also be available in the future, as nineml is currently limited to Java as a host language.

Adapting ABNF to ixml

The RFC9535 grammar is around 150 lines of ABNF which was converted to around 200 lines of ixml for ajp. The increase in linecount is partly explained by additional blank lines in the ixml version to separate different blocks of grammar constructs. For the most part, the original grammar names are retained.

There are a number of differences between ABNF and ixml grammars. A few of these differences are noted below.

• ABNF separates by spaces the sequences of factors (terminals and non-terminals) that make up rules, whereas ixml uses a comma (',') to separate factors in a sequence.

• An ixml rule ends with a period character ('.') whereas ABNF rules end with a pair of CRLF chars.

• ixml rule names can be separated from the rule definitions with either the equals sign ('=') or the colon (':') character whereas ABNF is always an equals sign ('='). ajp uses the equals sign for similarity to ABNF.

• ABNF alternatives within a rule are separated by a forward slash (aka solidus) character ('/') while ixml alternatives can be separated by either semicolon (';') or vertical bar ('|') characters. ajp uses the vertical bar ('|') character.

• ixml uses notations to determine the serialization of the processed input. For instance, an ixml terminal or non-terminal can indicate that it must be recognized as input but without output serialization by adding a minus character ('-') before the rule name or the terminal or non-terminal factor.

There are many other differences between the two grammar definitions but these are among the most striking. The serialization options allow ajp to simplify the XSLT processing rules in certain cases. A highlighted comparison of six JSONPATH grammar rules in ABNF and ixml can be found in the following figure:

Figure 12Comparison of a few JSONPATH rules in ixml and ABNF

Amongst the differences, the terminal "$" and the non-termal root-identifier are preceeded by a '-' char in the ixml grammar to indicate that those values are not to be serialized.

Generating the Abstract Syntax Tree (AST) using ixml

The JSONPATH ixml grammar is loaded into the ixml processor to create a parser for the JSONPATH query. This parser is then invoked with the JSONPATH query to generate an XML document that constitutes the AST. The figure below gives an example of a JSONPATH query and the first part of the resultant AST.

Figure 13A JSONPATH expression and the start of the resultant AST

An overview of ajp:getSegments()

A high-level overview of the compile time process can be shown in a few fragments of XSLT code:

The variable ajp:parser is created at the time of the XSLT stylesheet compilation thanks to the static attribute on the variable element. This is the parser created by the Coffee Sacks function cs:load-grammar(), part of the nineml suite of tools. [NINEML]Norman Tovey-Walsh, nineml -- A family of Earley and Generalized LL (GLL) parsing tools, https://​github​.com​/nineml​/nineml. The parser is invoked by the function ajp:getAST() which passes to the parser the string containing the JSONPATH query and receives the XML document that represents the Abstract Syntax Tree in return. The function ajp:getSegments() calls ajp:getAST() and invokes xsl:apply-templates on the resultant AST. That's the high-level process for generating the segments description.

Applying templates to the AST

Looking at the templates used to create the segments description, we can start at the top-most templates and work our way down to the most detailed.

Partial Function Application to generate Keys() functions

Four of the array functions templates use Partial Function Application (PFA) in order to generate the Keys() function that has the following signature, taking a single item()? as an argument.

function keys($item as item()?) as item()*

The three Keys() functions, before PFA, are the following:

function ajp:nameSelectorKeys($item  as item()?, $match as xs:string
                             ) as item()? 
{
    if (($item instance of map(*))
          and
        ($match instance of xs:string))
    then $match[ map:contains($item, $match) ]
    else ()
}

function ajp:indexSelectorKeys($item  as item()?, $match as xs:integer 
                              ) as item()? 
{
    if ($item instance of array(*) and $match instance of xs:integer)
    then let $length := array:size($item),
             $index := ( if ($match ge 0)
                         then ($match + 1)
                         else ($match + 1 + $length)
                       )
         return $index[(. gt 0) and (. le $length)]
         else ()
}

function ajp:sliceSelectorKeys($item  as item()?, $start as xs:integer?,
                                                  $end   as xs:integer?,
                                                  $step  as xs:integer?
                              ) as item()* 
{
    if ($item instance of array(*))
    then ajp:sliceProvider($item, $start, $end, $step) => ajp:keysFromProvider()
    else ()
}

The PFA of these three Keys() functions is the following, from the templates:

[ ajp:nameSelectorKeys(?, .),                 ajp:wildcardSelectorTest#3 ]

[ ajp:indexSelectorKeys(?, ajp:integer(.)),   ajp:wildcardSelectorTest#3 ]

[ ajp:sliceSelectorKeys(?, start, end, step), ajp:wildcardSelectorTest#3 ]

With PFA, the function arguments that are not called with an ArgumentPlaceholder (i.e. a '?' character) are bound to the provided values. The signature of the resultant function (i.e. post PFA) contains only those arguments for which an ArgumentPlacehoder is provided. A particular utility here of PFA is that the information that is available at JSONPATH expression compile time (i.e. during the call to ajp:getSegments()) is "captured" by PFA within the resultant partially-applied function, ready then to be used at JSONPATH runtime. Also, the resultant function after PFA matches the signature that is required for the Keys() function, taking only the runtime argument item()? that comes from the JSONPATH query argument.

PFA is also used for the Test() functions which will be described later.

The Slice Provider: inspired by generators

The JSONPATH slice-selector allows for selecting values in a subset of the elements of a JSON array. The fixed parameters for the slice are: start index, end index and step, all of which can be absent and even negative. In the case of a negative step, the values are selected in descending index order.

The slice-selector specifics are provided in RFC9535 Section 2.3.4 Array Slice Selector. The ajp implementation of the Keys() function for the slice-selector is inspired by the generators proposal made by Dimitre Novatchev [GENXPATH]Dimitre Novatchev, Generators in XPath, https://​medium​.com​/@dimitrenovatchev​/generators​-in​-xpath​-987a609cfbd5​?sk​=6334d48f9565f78eba90b212e461243b. . Because the implementation in ajp is not nearly as general as the proposed generators, it is called here a provider to avoid any confusion with full-blown generators.

The slice keys are created by calling a series of functions that are members of the map(*) that makes up the sliceProvider. The call to $provider?get-current() retrieves the current value of the provider and the call to $provider?move-next($provider) returns an updated map containing a new current value, up to the point that the end bound has been reached.

This mechanism allows for lazy evaluation of the slice indices. The XPath functions for implementing the sliceProvider itself can be found in the ajp repo file slice-provider.xslt.

Chaining Test() functions with Partial Function Application

The use of PFA for creating the Keys() functions has been shown in the earlier sections. PFA is also used for the Test() functions and, especially, for chaining them together.

To demonstrate why function chaining is necessary, we can look at part of the ixml grammar for a filter-selector.

filter-selector  = - "?" , S , logical-expr .

logical-expr     = logical-or-expr          .

logical-or-expr  = logical-and-expr , ( S , - "||" , S , logical-and-expr )* .

logical-and-expr = basic-expr       , ( S , - "&&" , S , basic-expr       )* .

Here we see that a filter-selector is a terminal '?' followed by a non-terminal logical-expr which, itself, is simply a logical-or-expr. These first two rules are handled by two simple XSLT templates, for which we've seen the first template previously. These templates simply "drill down" into the AST via recursive calls to xsl:apply-templates.

The next two non-terminals, logical-or-expr and logical-and-expr, are more interesting, because they both involve an arbitrary number of factors separated by '||' or '&&'. The XSLT templates that handle these two expressions need to handle the cases where boolean algebra is to be applied.

In the case where the count of $operands is 1, then no disjunction (i.e. "or") or conjunction (i.e. "and") operation is necessary and the template will simply return the single function created by recursive xsl:apply-templates; however, if there is more than one function in $operands, then the appropriate boolean operation needs to be applied on the multiple operands. In this case, the template will return the result of PFA on ajp:logicalOrExpr() or ajp:logicalAndExpr() where the $operands parameter is "captured" at JSONPATH compile time, much in the same fashion as for the Keys() functions that are the result of PFA.

function ajp:logicalOrExpr($key      as item(), 
                           $item     as item()?, 
                           $root     as item()?,
                           $operands as function(*)*
                          ) as xs:boolean
{
    some $operand in $operands
    satisfies $operand($key, $item, $root)
}

function ajp:logicalAndExpr($key      as item(), 
                            $item     as item()?, 
                            $root     as item()?,
                            $operands as function(*)*
                           ) as xs:boolean
{
    every $operand in $operands
    satisfies $operand($key, $item, $root)
}
		        

This term "chaining" is used in this paper to describe, as an example, the call from the function ajp:logicalOrExpr() to the "captured" functions in $operands, each time passing the three arguments for the runtime calls to the Test() functions.

Function chaining with SubQueries / SubSegments

Within a filter-selector it is often the case that a value is referenced with a subquery. For example in the following JSONPATH query involving a single child segment having a filter-selector, there are two subqueries: @.a and @.b. It is also possible to have a subquery that references the query argument (i.e. $root) itself by using the root-identifier or '$'. These are examples of what is called here a subquery. (N.B. RFC9535 does not employ the terms subquery and subsegment but does mention subexpression in section 2.3.5 Filter Selector.)

$[[email protected] == length(@.b)]

Just as in the global JSONPATH query, a subquery is evaluated using an input nodelist consisting initially of a single node which is either the current node (if the subquery starts with a '@' character) or the root node (if the subquery starts with a '$' character). In both cases, what follows the initial character is a possibly-empty sequence of segments that can be described by the same segments description as presented previously. To evaluate the nodelist results of the subquery, a call is made from some point in the function chain to the three-argument variant of ajp:applySegments() that was presented in the earlier ajp runtime section.

We can take the previous filter-selector expression as an example to view the different chained functions that result.

Figure 18A JSONPATH expression and the start of the resultant AST

The top-level function call for the filter-selector will be the call to ajp:comparisonExpr() which will, in turn, call the functions associated with its two comparable operands, ajp:singularQuery() and ajp:functionExpr(). Both of these functions will chain calls to ajp:applySubSegments() in order evaluate their respective subqueries which are represented by segments. The segments are generated at compile time and "captured" by PFA in the same fashion as described previously. The function ajp:applySubSegments() looks like this:

function ajp:applySubSegments($key      as item(), 
                              $item     as item()?, 
                              $root     as item()?,

                              $segments as map(xs:string, array(function(*))+)*,
                              $relative as xs:boolean
                             )          as map(xs:string, item()?            )*
{
    let $startNodelist := if ($relative)
                          then map { '@' : $item($key) }
                          else map { '$' : $root       }
    return ajp:applySegments($startNodelist, $segments, $root)
}

The function ajp:applySubSegments() is very simple: it creates the initial nodelist of one node, $startNodeList, using the $relative value "captured" by PFA to determine $startNodeList's contents, and then calls ajp:applySegments() with that nodelist, applying the $segments that were "captured" by PFA at JSONPATH compile time. It is for this usage that the $root parameter is passed to the Keys() functions.

JSONPATH Function Extensions

RFC9535 Section 2.4 Function Extensions describes how the filter-selector can call functions at certain points. These function extensions allow additional "filter expression functionality". Five base function extensions are defined within RFC9535 that are required in a conformant implementation: length(), count(), match(), search(), value().

A type system is defined in RFC9535 Section 2.4.1 "Type System for Function Expressions" in order to describe both the return types of the function extensions and also the argument types of those functions. This type system is very simple but it does introduce a few new values over and above those in JSON. Reproducing here the "Table 13: Function Extension Type System" from RFC9535

The XML element value $NULL was presented in the ajp runtime section of this paper. The value $NOTHING is implemented in a similar fashion.

All of these specific types and values, that is the three Function Extension types and the two specific values, $NULL and $NOTHING, are bound as global variables referencing unique elements for use throughout ajp. The function extensions for ajp are defined via these references:

Here the required function extensions are presented with their types. Note that ajp contains additional function extensions that are not presented here for reasons of brevity.

At compile time, the function extension's parameters and result types are checked and can result in compile time errors. (N.B. RFC9535 explicitly forbids any errors at runtime, hence any errors are necessarily raised at compile time.)

As an example, when the supplied actual parameter to a function is a filter-query and, concomitantly, the function argument's type is defined as $VALUE_TYPE, an additional compile time check is required to verify that the filter-query is a singular-query. The implementation of the template that handles a function-argument which is a filter-query has this look:

This template definition may require some explanation. Line 1 shows that the template will match a function-argument that is materialized by a filter-query (as opposed to being materialized by one of the other three possibilities, i.e. a literal, a logical-expr or a function-expr). Line 5 will retrieve the $argumentType for this argument of this function. Line 7 binds the Test() function, created by recursive xsl:apply-templates and that implements the filter-query, to a variable, $query. Line 11 starts a series of chained if .. then .. else if statements that handle the cases presented by different function argument types. If the function argument's type is $NODES_TYPE then the result of the function $query is already in the right form, as a Nodelist, hence no adaptation is required and the template will simply produce the $query function. If the function argument's type is $LOGICAL_TYPE, then an adaptation is required by "chaining" via PFA of ajp:nodesToLogical(), a function which returns the value true()if there is at least one Node in the Nodelist returned from the "chained" call to $query.

At Line 15 is the case of the function argument which is $VALUE_TYPE but also requires that the filter-query be a singular query, checked via the XPath function ajp:isSingularQuery(). (It may be interesting to note in passing that this is a very useful property of the XSLT template that the function associated with the filter-query has already been bound to the variable $query by recursive xsl:apply-templates but that we also have filter-query available for inspection by XPath.)

At Lines 15-17, if the if condition is evaluated as true(), then "chaining" via PFA is performed on the function ajp:singularQuery(), which returns the value of the single Node returned in the Nodelist, if there is one and, otherwise, returns the constant $NOTHING. If the if condition is evaluated as false(), then the unconditional else statement raises an XPath error via ajp:error() to indicate that the filter-query is not singular and, this, in order to better orient the query writer to a solution for the error.

Use by ajp of XML element types within Nodelists and Segments

Whereas JSONPATH takes JSON values as input and output, RFC9535 mentions a value, Nothing, can be returned by function extensions that return values of $VALUE_TYPE (e.g. the function extensions length() and value()) and also by singular query expressions that produce an empty Nodelist,in Section 2.4.5 "Well-Typedness of Function Expressions Point 2 (singular query).

$NOTHING matters

Because ajp is based upon XPath and hence the XPath Data Model [XDM31]Norman Walsh, John Snelson, Andrew Coleman, XQuery and XPath Data Model 3.1, 2017-03-21, World Wide Web Consortium (W3C), https://​www​.w3​.org​/TR​/xpath​-datamodel​-31/. , it is convenient to use non-JSON data, in this case an XML element, in order to distinguish this special value, $NOTHING.

To give an example of why $NOTHING matters, we can take the following JSONPATH query and its Query Argument and Resulting Nodelist.

Figure 19$NOTHING matters

The table shows the intermediate values of the comparison, including the values produced by the subquery @.a, which is 1 for the first child object and the empty sequence () for the second and third children, and the value produced by the subexpression length(@.b) which, for the three child objects of the query argument, produces for each object the value $NOTHING. The perhaps nonintuitive Nodelist result, containing the second and third children, is due to the rule for equality comparison:

2.3.5.2.2. Comparisons

When either side of a comparison results in an empty nodelist or the special result Nothing (see Section 2.4.1):

• A comparison using the operator == yields true if and only the other side also results in an empty nodelist or the special result Nothing.

$NULL is different from empty

RFC9535 mentions that the JSON literal null should not be confused with the absence of a value. In section 2.4.1 "Type System for Function Expressions" under Notes:

The special result Nothing represents the absence of a JSON value and is distinct from any JSON value, including null.

Similarly, in the Section 2.6. "Semantics of null"

Note: JSON null is treated the same as any other JSON value, i.e., it is not taken to mean "undefined" or "missing".

To convert JSON text serializations into XPath Data Model values, the XPath function fn:parse-json(), under Rule 6, "[t]he JSON value null is converted to the empty sequence."

Because the empty sequence is used as the result of many different operations. Take, for instance, the return value for $a('b')where $a is a map. This expression will return the empty sequence for both the situation where the map $a has no entry with the key 'b' and the situation where $a has an entry with the key 'b' and value of empty sequence. In order to disambiguate these result values, it is convenient to use the XML element value $NULL for the results that reference an isolated JSON literal null value.

Any JSONPATH queries that compare a value to JSON literal null will rely on this disambiguation. An example of such a test is below.

Figure 20$NULL is different from empty

It is for this reason that the two-argument version of ajp:applySegments converts any $NULL values in the final return nodelist to empty sequences.