Selecting Data
A JSON Pointer in a Runtime Expression selects a single location in a JSON document, and that location has to be known in advance. It cannot filter an array by the value of a property, and it does not apply to XML. A workflow may need to do either of these to extract a value from an API response.
The Selector Object addresses this by applying a JSONPath, XPath, or JSON Pointer expression to a value that a Runtime Expression provides. The Expression Type Object can then state which version of the query language an expression uses.
The Selector Object
A Selector object has three fields, all of which are required:
contextis a Runtime Expression that must evaluate to structured data.selectoris the expression to apply to that data.typeis the type of the expression, which isjsonpath,xpath, orjsonpointer.
Our Tic Tac Toe example has a reviewOpening workflow that reads the board and publishes two values using Selector objects:
outputs:
winner: $response.body#/winner
centerMark:
context: $response.body
selector: $.board[1][1]
type: jsonpath
topRow:
context: $response.body
selector: /board/0
type: jsonpointer
The centerMark output uses JSONPath to select the center square, as array positions start at zero. The topRow output uses a JSON Pointer to select the first row of the board.
These values could also be written as Runtime Expressions, as $response.body#/board/1/1 and $response.body#/board/0. We use the shorter form in winner, which is the better choice for a fixed location in a JSON document. Our Selector objects show the syntax, but they are not necessary for a response this small.
Choosing an Expression Type
A Selector object is needed when a Runtime Expression can’t express the query. JSONPath can, for example, select items from a list based on their content. The Tic Tac Toe API does not return such a list, so this fragment uses a hypothetical items array:
outputs:
firstItemId:
context: $response.body
selector: $.items[?(@.available == true)].id
type: jsonpath
XPath serves the same purpose for XML. This fragment selects a value from a hypothetical XML response:
outputs:
invoiceNumber:
context: $response.body
selector: /Invoice/Header/InvoiceNumber
type: xpath
Where Selector Objects Can Be Used
The fragments above are in outputs, which is the most common use. A Selector object can also provide:
- The
valueof a Parameter object. - A value in the
payloadof a Request Body object. - The
valueof a Payload Replacement object.
For example, a Step can pass a value selected from an earlier response as a parameter, without first publishing it as a separate output:
parameters:
- name: invoiceNumber
in: query
value:
context: $steps.fetchInvoice.outputs.invoice
selector: /Invoice/Header/InvoiceNumber
type: xpath
The Expression Type Object
Query languages have more than one version, and the same expression can behave differently in each. By default, jsonpath means RFC 9535, xpath means XPath 3.1, and jsonpointer means RFC 6901.
If an API or a tool needs a different version, an Expression Type object replaces the string value of type. Both of its fields are required:
outputs:
invoiceNumber:
context: $response.body
selector: /Invoice/Header/InvoiceNumber
type:
type: xpath
version: xpath-30
The allowed values for version are:
rfc9535ordraft-goessner-dispatch-jsonpath-00for JSONPath.xpath-31,xpath-30,xpath-20, orxpath-10for XPath.rfc6901for JSON Pointer.
Implementations must apply the semantics of the stated version. Only declare a version if you need something other than the default.
The syntax of JSONPath and XPath is defined by their own specifications, so we do not cover it in this topic.
The complete
reviewOpeningworkflow is in our example Arazzo Description.
Summary
In this topic we’ve learned that:
- A Selector object applies a JSONPath, XPath, or JSON Pointer expression to a value provided by a Runtime Expression.
- A Runtime Expression with a JSON Pointer is sufficient for a fixed location in JSON, and a Selector object is needed for queries and XML.
- Selector objects can provide outputs, parameter values, and payload values.
- An Expression Type object states the version of a query language if the default is not suitable.