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