Name

cx:jsonpath — Queries a JSON document with JSONPath.

Synopsis

This step evaluates JSONPath (RFC 9535) queries against JSON documents. The query result is returned.

Input portPrimarySequenceContent types
source✔  json 
Output portPrimarySequenceContent types
result✔  json 
Option nameTypeDefault valueRequired
queryxs:string ✔ 
parametersmap(xs:QName, item()*)?() 
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<p:import href="https://xmlcalabash.com/ext/library/jsonpath.xpl"/>
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
  |   <p:input port="source" content-types="json"/>
  |   <p:output port="result" content-types="json"/>
  |   <p:option name="query" as="xs:string" required="true"/>
5 |   <p:option name="parameters" as="map(xs:QName, item()*)?"/>
  |</p:declare-step>
Errors
CodeDescription
cxerr:XC0037It is a dynamic error (cxerr:XC0037) if the parameter provided has an unrecognized name.
cxerr:XC0039It is a dynamic error (cxerr:XC0039) if the JSONPath expression is invalid.

Description

The query provided is evaluated against the source document. The resulting JSON is returned on the result port. This step uses version 2.9.0 of the com.jayway.jsonpath implementation of JSONPath. It is a dynamic error (cxerr:XC0039) if the JSONPath expression is invalid.

The parameters show in Table 1, “JSONPath options” are supported. A parameter is enabled if its effective boolean value is true.

Table 1. JSONPath options
ParameterExplanation
as-path-listReturn paths instead of values
default-path-leaf-to-nullReturn null for missing leaves
always-return-listReturn a list even when the path is definite
suppress-exceptionsReturn an empty list or null instead of raising an error
require-propertiesRequires properties in an indefinite path

It is a dynamic error (cxerr:XC0037) if the parameter provided has an unrecognized name.

Dependencies

This step is included in the XML Calabash application. If you are getting XML Calabash from Maven, you will also need to include the extension dependencies:

  • com.jayway.jsonpath:json-path:2.9.0
  • net.minidev:json-smart:2.5.1