Docs / Strand / templating/jsonpath

JSONPath Integration

JSONPath is integrated into Strand as a Jinja2 filter and function, providing powerful JSON querying capabilities.

Why JSONPath?

JSONPath excels at querying complex, nested JSON structures. Use it when direct field access becomes cumbersome or when you need to filter arrays.

Using as a Filter#

jinja


{{ payload | jsonpath('$.field.subfield') }}
{{ steps.api_call.output_payload | jsonpath('$.items[*].id') }}

Using as a Function#

jinja


{{ jsonpath('$.users[?(@.active == true)].email', payload) }}
{{ jsonpath('$.results[*].id', steps.process.output_payload) }}

Filter vs Function

Both approaches work the same way. Use whichever feels more natural:

Filter: {{ data | jsonpath('$.path') }}
Function: {{ jsonpath('$.path', data) }}

Basic Queries#

Extract Single Field#

jinja


{{ payload | jsonpath('$.user.name') }}

Extract All Matching#

jinja


{{ payload | jsonpath('$.items[*].id') }}

Nested Access#

jinja


{{ event | jsonpath('$.data.results[0].value') }}

Example: Complex Nested Access

jinja


{{ payload | jsonpath('$.users[0].addresses[?(@.primary == true)].street') }}

Built-in Functions#

Length#

jinja


{{ payload | jsonpath('$.items.`len`') }}

Counting Items

Use len to count array items or object keys:

jinja


{{ payload | jsonpath('$.users.`len`') }}

Keys#

jinja


{{ payload | jsonpath('$.object.`keys`') }}

String Operations#

Function	Description	Example
`str()`	Convert to string	`$.field.\`str()\``
`sub(/pattern/, replacement)`	Replace pattern	`$.field.\`sub(/old/, new)\``
`split(",", 0, -1)`	Split string	`$.field.\`split(",", 0, -1)\``

Backticks Required

Built-in functions must be wrapped in backticks: ` len , keys `

Filtering Arrays#

Simple Filter#

jinja


{{ payload | jsonpath('$.items[?(@.count > 5)]') }}

Multiple Conditions#

jinja


{{ payload | jsonpath('$.users[?(@.active == true & @.role == "admin")]') }}

Example: Complex Filtering

jinja


{{ payload | jsonpath('$.users[?(@.age > 18 & @.verified == true & @.country == "US")]') }}

Regex Matching#

jinja


{{ payload | jsonpath('$.users[?(@.email =~ ".*@example.com")]') }}

Regex Patterns

Use =~ for regex matching. Patterns follow standard regex syntax.

Arithmetic Operations#

jinja


{{ payload | jsonpath('$.price * 1.1') }}
{{ payload | jsonpath('$.foo + $.bar') }}
{{ payload | jsonpath('$.total - $.discount') }}

Example: Calculations

jinja


{{ payload | jsonpath('$.subtotal * (1 + $.tax_rate)') }}

Combining with Jinja2#

jinja


{% set user_ids = payload | jsonpath('$.users[*].id') %}
{% for id in user_ids %}
  https://api.example.com/users/{{ id }}
{% endfor %}

Powerful Combination

Combine JSONPath extraction with Jinja2 loops and conditionals for maximum flexibility!

When to Use JSONPath#

Use JSONPath When:#

Querying nested or complex structures
Filtering arrays based on conditions
Extracting multiple matching values
Using built-in functions
Working with dynamic/depth-unknown structures

Use Direct Access When:#

Simple field access: {{ payload.field }}
Known structure: {{ steps.node.output_payload.user_id }}
Simple conditionals: {{ payload.temperature > 25 }}

Performance

Direct access is slightly faster, but JSONPath is more flexible. Use the right tool for the job!

← Back to Strand docs