Reference Guide

Complete syntax reference, troubleshooting guide, and quick-lookup tables for JSON Path mapping.

Quick Syntax Reference

Core Operators

Operator	Name	Description	Example
`$`	Root	Document root	`$.NODE.data`
`.`	Dot	Child operator	`$.NODE.user.name`
`..`	Recursive	Deep scan	`$..price`
`*`	Wildcard	All elements	`$.NODE.*`
`[]`	Brackets	Subscript	`$.NODE['property-name']`
`[n]`	Array Index	Specific position	`$.NODE.items[0]`
`[start:end]`	Slice	Array range	`$.NODE.items[0:3]`
`[-n]`	Negative Index	From end	`$.NODE.items[-1]`
`[*]`	Array Wildcard	All array items	`$.NODE.items[*]`
`[?()]`	Filter	Conditional selection	`$.NODE[?(@.price>10)]`
`^`	Parent	Parent reference	`$.NODE.child^`
`~`	Property Name	Get key names	`$.NODE.*~`
`\|`	Pipe	Concatenation (custom)	`First\|$\|Last`

QuivaWorks-Specific Extensions

Feature	Description	Example
NODE_ID Reference	Reference any node by ID	`$.NODE_ID.property`
Pipe Operator	Concatenate static + dynamic	`Name: \|$.NODE.name`
Inline Detection	Use anywhere in object	`{"key": "$.NODE.value"}`
Multi-pipe	Multiple concatenations	`$.first\| \|$.last`

The pipe operator (|) is a QuivaWorks custom extension not found in standard JSONPath implementations.

Array Operations

Array Access Methods

Index Access
Slicing
Wildcards
Array Properties

// Positive indexing (0-based)
"$.NODE.items[0]"      // First item
"$.NODE.items[1]"      // Second item
"$.NODE.items[5]"      // Sixth item

// Negative indexing (from end)
"$.NODE.items[-1]"     // Last item
"$.NODE.items[-2]"     // Second-to-last
"$.NODE.items[-5]"     // Fifth from end

// Basic slicing [start:end]
"$.NODE.items[0:3]"    // First 3 items (0, 1, 2)
"$.NODE.items[2:5]"    // Items 2, 3, 4
"$.NODE.items[5:10]"   // Items 5-9

// Omit start (from beginning)
"$.NODE.items[:3]"     // First 3 items

// Omit end (to end)
"$.NODE.items[2:]"     // From item 2 to end

// Negative slicing
"$.NODE.items[-3:]"    // Last 3 items
"$.NODE.items[:-2]"    // All except last 2

// Get all array items
"$.NODE.items[*]"              // All items as array
"$.NODE.items[*].name"         // All names
"$.NODE.items[*].price"        // All prices

// Get all properties
"$.NODE.user.*"                // All user properties
"$.NODE.*"                     // All NODE properties

// Get property names
"$.NODE.user.*~"               // Property keys
"$.NODE.items[*]~"             // Array indices as strings

// Array length
"$.NODE.items.length"          // Number of items

// Combined with filters
"$.NODE.items[?(@.active)].length"  // Count active items

// Nested arrays
"$.NODE.users[*].orders.length"     // Each user's order count

Filter Expressions

Filter Syntax Patterns

Basic Filters

// Existence check
"$.items[?(@.id)]"                    // Has 'id' property
"$.items[?(@.active)]"                // Has truthy 'active'

// Equality
"$.items[?(@.status==='active')]"    // Strict equality
"$.items[?(@.type=='premium')]"      // Loose equality
"$.items[?(@.count===0)]"            // Zero check

// Inequality
"$.items[?(@.status!=='deleted')]"   // Not equal
"$.items[?(@.role!='guest')]"        // Loose not equal

Numeric Comparisons

// Greater than / Less than
"$.items[?(@.price>100)]"            // Price over 100
"$.items[?(@.stock<10)]"             // Low stock
"$.items[?(@.rating>=4.5)]"          // High rated
"$.items[?(@.age<=18)]"              // Max age

// Numeric ranges
"$.items[?(@.price>=10 && @.price<=100)]"     // Between 10-100
"$.items[?(@.quantity>0 && @.quantity<50)]"   // Range 1-49

Logical Operators

// AND operator (&&)
"$.items[?(@.active===true && @.verified===true)]"
"$.users[?(@.age>=18 && @.country==='US')]"
"$.products[?(@.inStock && @.price<100)]"

// OR operator (||)
"$.items[?(@.status==='pending' || @.status==='processing')]"
"$.users[?(@.role==='admin' || @.role==='moderator')]"
"$.items[?(@.priority==='high' || @.urgent===true)]"

// Complex combinations
"$.items[?(@.active && (@.type==='A' || @.type==='B'))]"
"$.users[?(@.verified && @.age>=18 && (@.role==='admin' || @.role==='moderator'))]"

String Matching

// Exact match
"$.items[?(@.category==='electronics')]"
"$.users[?(@.email==='john@example.com')]"

// Case sensitivity
"$.items[?(@.name==='Product')]"     // Case-sensitive
"$.items[?(@.name=='product')]"      // Still case-sensitive

// Note: Regular expressions not supported in standard JSONPath
// Use exact string matching only

Null & Undefined

// Check for null
"$.items[?(@.deletedAt===null)]"     // Is null
"$.items[?(@.value!==null)]"         // Not null

// Check existence (undefined)
"$.items[?(@.optional)]"             // Property exists and truthy
"$.items[?(!@.optional)]"            // Property missing or falsy

// Type selectors (advanced)
"$.items[?(@null())]"                // Null values only
"$.items[?(@undefined())]"           // Undefined only

Filter Expression Variables

Special Variables Reference

Variable	Scope	Description	Example
`@`	Current	The current node being filtered	`?(@.price>10)`
`@.property`	Current	Property of current node	`?(@.status==='active')`
`@.nested.prop`	Current	Nested property access	`?(@.user.age>=18)`
`@root`	Global	Root of entire JSON document	`?(@.id===@root.userId)`
`@parent`	Parent	Parent object of current node	`?(@parent.type==='premium')`
`@property`	Meta	Property name or array index	`?(@property!==0)`
`@parentProperty`	Meta	Parent’s property name	`?(@parentProperty!=='hidden')`
`@path`	Meta	JSONPath to current node	`?(@path!==\"$['items'][0]\")`

Special Functions

Aggregation
Type Selectors
Context Access

// Min/Max
"$.items[?(@.price===@min(@..price))]"    // Cheapest item
"$.items[?(@.score===@max(@..score))]"    // Highest score

// Note: @min() and @max() work on descendant values
"$.products[?(@.price===@min(@root.products[*].price))]"

// Type checking
"$..@null()"              // All null values
"$..@boolean()"           // All booleans  
"$..@number()"            // All numbers
"$..@integer()"           // Integer numbers only
"$..@string()"            // All strings
"$..@array()"             // All arrays
"$..@object()"            // All objects

// In filters
"$.items[?(@number())]"                    // Numeric items
"$.data[?(@.value@string())]"              // String values
"$.config[?(@.settings@object())]"         // Object settings

// Root reference
"$.orders[?(@.userId===@root.currentUser.id)]"    // Match root value
"$.items[?(@.category===@root.filter)]"           // Filter by root

// Parent reference  
"$.users[*].orders[?(@parent.status==='active')]" // Active user orders
"$.sections[*].items[?(@parent.visible)]"         // Items in visible sections

// Property/Path reference
"$.data[?(@property!=='internal')]"               // Exclude internal keys
"$.items[?(@path!==\"$.excluded\")]"              // Exclude specific paths

Comparison Operators

Complete Operator Table

Operator	Description	Works With	Example
`===`	Strict equality	All types	`?(@.status==='active')`
`!==`	Strict inequality	All types	`?(@.type!=='hidden')`
`==`	Loose equality	All types	`?(@.count==5)`
`!=`	Loose inequality	All types	`?(@.value!=null)`
`<`	Less than	Numbers, strings	`?(@.age<18)`
`>`	Greater than	Numbers, strings	`?(@.price>100)`
`<=`	Less than or equal	Numbers, strings	`?(@.score<=50)`
`>=`	Greater than or equal	Numbers, strings	`?(@.quantity>=10)`
`&&`	Logical AND	Boolean expressions	`?(@.a && @.b)`
`\|\|`	Logical OR	Boolean expressions	`?(@.a \|\| @.b)`
`!`	Logical NOT	Boolean expressions	`?(!@.deleted)`

Important Differences:

Use === (triple equals) not = (single equals)
Use !== not ! for inequality
Strings in comparisons must be quoted: 'value' or "value"

Operator Precedence

From highest to lowest priority:

Grouping: ()
Property Access: ., []
Logical NOT: !
Comparison: <, >, <=, >=
Equality: ===, !==, ==, !=
Logical AND: &&
Logical OR: ||

// This evaluates as: (@.active && @.verified) || @.admin
"$.users[?(@.active && @.verified || @.admin)]"

// Result: Active+Verified users OR any admin (even inactive)

// This evaluates as: @.active && (@.verified || @.admin)
"$.users[?(@.active && (@.verified || @.admin))]"

// Result: Active users who are either verified OR admin

Common Patterns Quick Reference

Pattern Library

Basic Property Access

"$.NODE.property"
"$.NODE.nested.deep.value"
"$.NODE['property-name']"
"$.NODE['property with spaces']"

Array Operations

"$.NODE.array[0]"
"$.NODE.array[-1]"
"$.NODE.array[*]"
"$.NODE.array[0:3]"
"$.NODE.array.length"

Concatenation

"Text|$.NODE.value"
"$.NODE.first| |$.NODE.last"
"$.NODE.city|, |$.NODE.state"
"Prefix:|$.NODE.data|:Suffix"

Filtering

"$.NODE[?(@.active)]"
"$.NODE[?(@.price>100)]"
"$.NODE[?(@.status==='done')]"
"$.NODE[?(@.type==='A' || @.type==='B')]"

Deep Scanning

"$..property"
"$..price"
"$..id"
"$.NODE..status"

Wildcards

"$.NODE.*"
"$.NODE.users[*].name"
"$.NODE.items[*].price"
"$.NODE.*~"

Complex Filters

"$.NODE[?(@.a && @.b)]"
"$.NODE[?(@.x>10 && @.y<20)]"
"$.NODE[?(@.status!=='deleted')]"
"$.NODE[?(@.price>=@min(@..price))]"

Combining Patterns

"$.NODE.items[?(@.active)][0]"
"$.NODE.users[*].orders[?(@.paid)]"
"$.NODE[?(@.type==='A')].value|text"
"First: |$.NODE[0].name"

Troubleshooting Guide

Common Errors & Solutions

❌ Undefined or Empty Result

Symptoms: Path returns undefined, filter returns empty array [], or property seems to exist but isn’t found.Common Causes:Incorrect Node ID

// ❌ Wrong
"$.wrong_node_id.property"

// ✅ Correct
"$.correct_node_id.property"

Case Sensitivity

// ❌ Wrong case
"$.NODE.Username"

// ✅ Correct case
"$.NODE.username"

Array Index Out of Bounds

// ❌ Array only has 3 items
"$.NODE.items[5]"

// ✅ Check length first
"$.NODE.items[2]"

Property Doesn’t Exist

// ❌ Typo in property name
"$.NODE.custmor_name"

// ✅ Correct spelling
"$.NODE.customer_name"

Solutions: Verify node ID matches exactly in flow, check property names in Flow Debugger, test with simpler paths and build up, and use .length to check array sizes.

❌ Filter Not Working

Symptoms: Filter returns wrong items, filter returns nothing, or comparison seems correct but fails.Common Causes:Using = Instead of ===

// ❌ Single equals doesn't work
"$.items[?(@.status='active')]"

// ✅ Use triple equals
"$.items[?(@.status==='active')]"

Missing Quotes on Strings

// ❌ String without quotes
"$.items[?(@.type===premium)]"

// ✅ Quoted string
"$.items[?(@.type==='premium')]"

Wrong Comparison Type

// ❌ Comparing string to number
"$.items[?(@.id===123)]"
// If id is string "123"

// ✅ Match types
"$.items[?(@.id==='123')]"

Forgetting @ in Filter

// ❌ Missing @ symbol
"$.items[?(price>10)]"

// ✅ Include @ for current node
"$.items[?(@.price>10)]"

Solutions: Always use === for equality (not =), quote string values in comparisons, use @ to reference current node, and check data types match in comparisons.

❌ Type Mismatch Errors

Symptoms: Comparison fails unexpectedly, filter returns empty when data exists, or inconsistent results.Common Causes:String vs Number

// ❌ Comparing string "10" to number 10
"$.items[?(@.quantity===10)]"
// When quantity is string "10"

// ✅ Match the type in source data
"$.items[?(@.quantity==='10')]"

Boolean as String

// ❌ Boolean comparison fails
"$.items[?(@.active===true)]"
// When active is string "true"

// ✅ String comparison
"$.items[?(@.active==='true')]"

Null vs Undefined

// ❌ These are different
"$.items[?(@.value===null)]"      // Explicitly null
"$.items[?(!@.value)]"             // Undefined or falsy

// ✅ Be specific
"$.items[?(@.value===null)]"       // Only null
"$.items[?(@value)]"               // Exists check

Solutions: Check source data types in debugger, use loose equality == if types vary, and convert types in earlier flow nodes if needed.

❌ Pipe Operator Issues

Symptoms: Pipe concatenation not working, literal | appears in output, or parts missing from concatenated string.Common Causes:Spaces Around Pipe

// ❌ Spaces might cause issues
"$.NODE.first | $.NODE.last"

// ✅ No spaces around pipe
"$.NODE.first|$.NODE.last"

Empty/Undefined Values

// ❌ If middle_name doesn't exist
"$.first| |$.middle| |$.last"
// Result: "John  Smith" (double space)

// ✅ Ensure all values exist or handle in flow

Wrong Pipe Type

// ❌ Using filter pipe instead of concat
"$.items | $.NODE.name"

// ✅ Custom concat pipe
"Text|$.NODE.name"

Solutions: Remove spaces around pipes, check all referenced values exist, and remember that | is a QuivaWorks custom extension (not standard JSONPath).

❌ Performance Issues

Symptoms: Slow flow execution, timeouts on large datasets, or high memory usage.Common Causes:Deep Scan on Large Data

// ❌ Scans entire tree
"$..price"

// ✅ Specific path
"$.NODE.products[*].price"

Multiple Filters

// ❌ Separate filters compound
"$.items[?(@.active)][?(@.verified)][?(@.premium)]"

// ✅ Combined filter
"$.items[?(@.active && @.verified && @.premium)]"

Unnecessary Wildcards

// ❌ Gets all properties
"$.NODE.*"

// ✅ Get only what you need
"$.NODE.specificProperty"

Solutions: Use specific paths instead of deep scan, combine filter conditions, limit array slicing ranges, and process data in smaller batches if possible.

❌ Special Characters in Property Names

Symptoms: Properties with special characters not accessible, syntax errors with property names, or unexpected undefined results.Common Causes:Spaces in Property Names

// ❌ Dot notation fails
"$.NODE.user name"

// ✅ Bracket notation
"$.NODE['user name']"

Hyphens/Dashes

// ❌ Interpreted as subtraction
"$.NODE.user-id"

// ✅ Bracket notation
"$.NODE['user-id']"

Special Characters

// ❌ Dot notation fails
"$.NODE.user@email"
"$.NODE.price$amount"

// ✅ Bracket notation
"$.NODE['user@email']"
"$.NODE['price$amount']"

Numeric-Starting Names

// ❌ Confusing syntax
"$.NODE.2fa_enabled"

// ✅ Bracket notation
"$.NODE['2fa_enabled']"

Solutions: Use bracket notation ['property'] for special characters, spaces, hyphens, @, $, etc., and for properties that start with numbers.

Error Messages Reference

Common Error Messages

Error Message	Cause	Solution
`JSONPath syntax error`	Invalid JSONPath expression	Check syntax, ensure proper quotes and brackets
`Unexpected token`	Malformed JSON or path	Verify JSON structure and path syntax
`Cannot read property of undefined`	Accessing non-existent property	Check if property exists before accessing
`Invalid array index`	Array index out of bounds	Verify array length, use `.length`
`Filter expression error`	Invalid filter syntax	Check filter uses `@`, `===`, proper operators
`Type error in comparison`	Comparing incompatible types	Ensure types match or use loose equality `==`
`Circular reference`	Parent/root creates infinite loop	Avoid self-referential filters
`Maximum call stack exceeded`	Infinite recursion in path	Review recursive descent usage `..`

Best Practices

Do’s and Don’ts

✅ Do
❌ Don't
⚡ Performance
🔒 Security

Do These Things:✅ Use specific paths when possible: $.NODE.user.name✅ Use triple equals in filters: ?(@.status==='active')✅ Quote strings in filters: ?(@.type==='premium')✅ Check array length before accessing: $.items.length✅ Use bracket notation for special characters: ['user-id']✅ Combine filters with && and ||: ?(@.a && @.b)✅ Use meaningful node IDs in flows for clarity✅ Test paths with Flow Debugger before deploying✅ Use array slicing for pagination: [0:10]✅ Validate data structures in earlier nodes when possible

Avoid These Mistakes:❌ Use single equals: ?(@.status='active') ← Wrong!❌ Forget quotes on strings: ?(@.type===premium) ← Wrong!❌ Forget @ in filters: ?(status==='active') ← Wrong!❌ Use deep scan unnecessarily: $..property (slow)❌ Chain multiple separate filters: [?(@.a)][?(@.b)] (slow)❌ Access properties without checking existence❌ Use incorrect case: $.NODE.Username when it’s username❌ Mix types in comparisons: ?(@.id===123) when id is string❌ Use wildcards when you need specific properties❌ Assume array order is stable without sorting first

Performance Optimization Tips:⚡ Specific Paths > Wildcards: $.NODE.items[*] better than $.NODE..*⚡ Combined Filters > Multiple Filters: One ?(@.a && @.b) better than [?(@.a)][?(@.b)]⚡ Array Slicing > Full Array: [0:10] better than [*] for large arrays⚡ Property Access > Deep Scan: $.NODE.property better than $..property⚡ Early Filtering: Filter data as early as possible in your flow⚡ Limit Recursion: Avoid .. on deeply nested structures⚡ Cache Results: Store filtered results in variables instead of re-filtering⚡ Batch Processing: Process large datasets in smaller chunks

Testing Strategies

How to Test Your Paths

Start Simple

Begin with basic property access and verify it works:

"$.NODE.property"

Add Complexity Gradually

Add one feature at a time (arrays, then filters):

"$.NODE.items[0]"
"$.NODE.items[?(@.active)]"

Use Flow Debugger

Test each path in the Flow Debugger to see actual results before deploying.

Test Edge Cases

Test with empty arrays [], missing properties undefined, null values null, and different data types.

Verify Output Format

Check if you need an array [...] or single value, and adjust accordingly:

"$.NODE.items[?(@.active)][0]"  // Single item
"$.NODE.items[?(@.active)]"     // Array of items

Migration from Other Systems

From Zapier

// Zapier uses {{double.braces}}
{{1.customer.name}}
{{2.order.items.0.price}}

// QuivaWorks uses $.NODE_ID.path
"$.step1.customer.name"
"$.step2.order.items[0].price"

From Make (Integromat)

// Make uses {{module.field}}
{{1.name}}
{{2.items[].name}}

// Similar but with $ and proper array syntax
"$.module1.name"
"$.module2.items[*].name"

From n8n

// n8n uses {{$node["Node Name"].json.field}}
{{$node["HTTP Request"].json.data.name}}

// Use node IDs instead of names
"$.http_request.data.name"

Key Difference: QuivaWorks uses standard JSONPath syntax with custom extensions, making it more powerful for complex data transformations.

Keyboard Shortcuts & Tips

Flow Builder Shortcuts

Shortcut	Action
Test Path	Click “Test” button in mapping field
View Source Data	Open Flow Debugger panel
Copy Path	Right-click property in debugger
Format JSON	Auto-formats in code view
Validate Syntax	Automatic on field blur

Debugging Tips

Start Small

Test basic path first, then add complexity one step at a time.

Use Console

Test JSONPath expressions in browser console with sample data.

Check Types

Use typeof or Flow Debugger to verify data types before filtering.

Log Intermediate Results

Create intermediate nodes to see transformation steps.

Next Steps

Examples

See real-world usage examples

Advanced Techniques

Learn power user strategies

Filters & Expressions

Deep dive into filtering

Basic Syntax

Review the fundamentals

Quick Reference Card

Print-Friendly Quick Reference

JSONPath Cheat Sheet

Basic Syntax:

$.NODE.property - Access property
$.NODE.array[0] - Array index
$.NODE.array[*] - All items
$.NODE.array[0:3] - Slice (first 3)
$.NODE.array[-1] - Last item
$.NODE.array.length - Array length

Filtering:

$.NODE[?(@.property)] - Exists
$.NODE[?(@.x===value)] - Equals
$.NODE[?(@.x>10)] - Greater than
$.NODE[?(@.a && @.b)] - AND
$.NODE[?(@.a || @.b)] - OR

Pipe Operator (Custom):

Text|$.NODE.value - Concatenate
$.NODE.first| |$.NODE.last - With space
$.a|, |$.b|, |$.c - Multiple pipes

Common Patterns:

$.NODE[?(@.active)][0] - First active item
$.NODE[*].property - All properties
$.NODE[?(@.price<100)].length - Count filtered

Remember:

Use === not =
Quote strings in filters
Always use @ in filters
Array indexes start at 0
Negative indexes from end

Bookmark this page! This reference guide contains everything you need for JSONPath mapping in QuivaWorks flows.

​Reference Guide

​Quick Syntax Reference

​Core Operators

​QuivaWorks-Specific Extensions

​Array Operations

​Array Access Methods

​Filter Expressions

​Filter Syntax Patterns

​Filter Expression Variables

​Special Variables Reference

​Special Functions

​Comparison Operators

​Complete Operator Table

​Operator Precedence

​Common Patterns Quick Reference

​Pattern Library

Basic Property Access

Array Operations

Concatenation

Filtering

Deep Scanning

Wildcards

Complex Filters

Combining Patterns

​Troubleshooting Guide

​Common Errors & Solutions

​Error Messages Reference

​Common Error Messages

​Best Practices

​Do’s and Don’ts

​Testing Strategies

​How to Test Your Paths

​Migration from Other Systems

​From Zapier

​From Make (Integromat)

​From n8n

​Keyboard Shortcuts & Tips

​Flow Builder Shortcuts

​Debugging Tips

Start Small

Use Console

Check Types

Log Intermediate Results

​Next Steps

Examples

Advanced Techniques

Filters & Expressions

Basic Syntax

​Quick Reference Card

​JSONPath Cheat Sheet

Reference Guide

Quick Syntax Reference

Core Operators

QuivaWorks-Specific Extensions

Array Operations

Array Access Methods

Filter Expressions

Filter Syntax Patterns

Filter Expression Variables

Special Variables Reference

Special Functions

Comparison Operators

Complete Operator Table

Operator Precedence

Common Patterns Quick Reference

Pattern Library

Troubleshooting Guide

Common Errors & Solutions

Error Messages Reference

Common Error Messages

Best Practices

Do’s and Don’ts

Testing Strategies

How to Test Your Paths

Migration from Other Systems

From Zapier

From Make (Integromat)

From n8n

Keyboard Shortcuts & Tips

Flow Builder Shortcuts

Debugging Tips

Next Steps

Quick Reference Card

JSONPath Cheat Sheet