Payload Shaping Functions

Payload Shaping functions transform and reshape data using JMESPath expressions. They're ideal for data mapping, format conversion, and structural transformations without AI processing.

When to Use

Use a Payload Shaping function when you need to:

Transform output from one function to match another system's format
Extract specific fields from complex nested structures
Perform calculations or aggregations on data
Rename or reorganize fields
Prepare data for downstream systems or APIs

Configuration Fields

Required Fields

Field	Type	Description
`functionName`	string	Unique identifier for the function
`type`	string	Must be `"payload_shaping"`
`shapingSchema`	string	JMESPath expression for transformation

Optional Fields

Field	Type	Default	Description
`displayName`	string	-	Human-readable display name
`tags`	string[]	-	Tags for organization

JMESPath Basics

JMESPath is a query language for JSON. Here are common patterns:

Pattern	Description	Example
`field`	Select a field	`name`
`field.subfield`	Nested selection	`vendor.name`
`array[0]`	Array index	`items[0]`
`array[*].field`	Map over array	`items[*].price`
`sum(array)`	Sum values	`sum(items[*].price)`
`length(array)`	Count items	`length(items)`
`{key: value}`	Create object	`{id: invoiceNumber}`

Examples

Simple Field Mapping

Transform invoice data to a simplified format:

Input:

{
  "invoiceNumber": "INV-001",
  "vendor": { "name": "Acme Corp", "address": "123 Main St" },
  "totalAmount": 1500.00,
  "lineItems": [...]
}

Payload Shaping Function:

{
  "functionName": "invoice-to-erp",
  "type": "payload_shaping",
  "displayName": "Invoice to ERP Format",
  "shapingSchema": "{ \"id\": invoiceNumber, \"vendorName\": vendor.name, \"total\": totalAmount }"
}

Output:

{
  "id": "INV-001",
  "vendorName": "Acme Corp",
  "total": 1500.00
}

Aggregation and Calculation

Calculate totals from line items:

{
  "functionName": "calculate-totals",
  "type": "payload_shaping",
  "shapingSchema": "{ \"itemCount\": length(lineItems), \"subtotal\": sum(lineItems[*].price), \"avgPrice\": avg(lineItems[*].price) }"
}

Complex Transformation

Restructure nested data for an API:

{
  "functionName": "api-formatter",
  "type": "payload_shaping",
  "displayName": "Format for External API",
  "shapingSchema": "{ \"reference\": invoiceNumber, \"amount\": { \"value\": totalAmount, \"currency\": \"USD\" }, \"vendor\": { \"id\": vendor.id, \"display\": vendor.name }, \"line_items\": lineItems[*].{sku: productCode, qty: quantity, unit_price: unitPrice} }",
  "tags": ["integration", "api"]
}

Extracting from Arrays

Get unique values or filter arrays:

{
  "functionName": "extract-origins",
  "type": "payload_shaping",
  "shapingSchema": "{ \"load_reference\": tenders[0].loadReference, \"total_weight_tons\": sum(tenders[*].weightTons), \"origins\": tenders[*].origin, \"submitters\": tenders[*].submitter.name }"
}

Use Cases

1. Format Conversion

Convert bem output to match your ERP, CRM, or database schema:

{
  "shapingSchema": "{ \"po_number\": purchaseOrderNumber, \"vendor_code\": vendor.id, \"line_count\": length(items), \"total_usd\": totalAmount }"
}

2. Data Enrichment Prep

Prepare data before sending to an enrichment function:

{
  "shapingSchema": "{ \"query\": join(' ', [vendor.name, vendor.address]), \"context\": { \"amount\": totalAmount, \"date\": invoiceDate } }"
}

3. Webhook Payload Formatting

Shape data for webhook delivery:

{
  "shapingSchema": "{ \"event\": 'invoice.processed', \"data\": { \"id\": invoiceNumber, \"amount\": totalAmount }, \"timestamp\": '2024-01-01T00:00:00Z' }"
}

JMESPath Reference

For complete JMESPath syntax and functions, see the JMESPath specification.

Common functions:

sum(), avg(), min(), max() - Numeric aggregations
length() - Array/string length
join() - Join array elements
sort(), sort_by() - Sort arrays
contains() - Check for value
keys(), values() - Object operations

Create a Function API

API reference for creating functions

Transform Functions

Extract data before shaping

JMESPath Tutorial

Learn JMESPath syntax

Payload Shaping Functions

Create a Function API

Transform Functions

JMESPath Tutorial

On this page