JMESPath Transforms

JMESPath is a query language for JSON that allows you to transform and filter API responses before using them in YOOtheme.

What is JMESPath?

JMESPath lets you:

• Filter arrays based on conditions
• Sort data by specific fields
• Extract and reshape data
• Combine multiple operations

Basic Syntax

Accessing Fields

# Simple field
name

# Nested field
product.details.sku

# Array element
items[0]

Filtering Arrays

# Get items where status is 'active'
items[?status=='active']

# Get products with price > 100
products[?price>`100`]

# Combine conditions
items[?status=='active' && price<`50`]

Sorting

# Sort by name
sort_by(items, &name)

# Sort by price (descending)
reverse(sort_by(items, &price))

Limiting Results

# First 5 items
items[:5]

# Last 3 items
items[-3:]

# Items 5-10
items[5:10]

Projections

# Extract specific fields
items[].{title: name, cost: price}

# Flatten nested arrays
stores[].products[]

Real-World Examples

E-commerce: Featured Products

Get only featured products, sorted by price:

sort_by(products[?featured==`true`], &price)

Blog: Recent Posts

Get the 5 most recent published posts:

posts[?status=='published'] | sort_by(@, &date) | reverse(@) | [:5]

Events: Upcoming Only

Filter events to show only future dates:

events[?date>'2024-01-01']

Products: In Stock

Show only products that are in stock:

products[?stock_status=='instock']

Nested Data: Extract Images

Get all image URLs from nested structure:

products[].images[].src

Using in API Mapper

1. Open your connection settings
2. Go to the Transform section (Pro/Developer only)
3. Enter your JMESPath expression
4. Click Test to preview results
5. Save the connection

Testing Expressions

Online Tester

Use jmespath.org to test expressions with sample data.

In API Mapper

1. Click Test Connection
2. View the raw API response
3. Write your JMESPath expression
4. Preview the transformed result

Common Patterns

Safe Navigation

Handle missing data gracefully:

items[*].metadata.category || 'Uncategorized'

Combining Arrays

Merge multiple sources:

{all: join(',', [items[].name, products[].title])}

Conditional Values

Return different values based on conditions:

items[].{
  name: name,
  label: status == 'active' && 'Available' || 'Sold Out'
}

Limitations

• Complex expressions may impact performance
• Some advanced JMESPath functions may not be available
• Test thoroughly before using in production

Resources

• JMESPath Specification
• JMESPath Tutorial
• JMESPath Examples

Next Steps

• Field Mapping
• Caching