JMESPath: API and behavior notes¶

Start with the JMESPath guide for examples and results. This page covers detailed contracts and less common options. Contributor provenance and verification scope are recorded in compatibility and the linked implementation plans.

Powertools functions and envelopes¶

Use WithPowertoolsFunctions() to enable powertools_json, powertools_base64, and powertools_base64_gzip. All require exactly one string argument. Base64 uses the shared reference validation; gzip verifies decompression errors. Decoding buffers the complete value, so applications should bound untrusted payload sizes.

ExtractDataFromEnvelope(data, envelope) enables these functions by default. Explicit options replace that default; include WithPowertoolsFunctions() alongside custom definitions when both are needed.

Expressions match the pinned constants literally. In particular SNS selects the first record, and the S3 nested envelopes select the first S3 record within each outer record; callers needing other behavior can provide their own expressions.

Custom functions and Logger integration¶

option := jmespath.WithFunctions(jmespath.Function{
    Name: "upper",
    Arguments: []jmespath.Argument{{Types: []jmespath.Type{jmespath.String}}},
    Handler: func(args []any) (any, error) {
        return strings.ToUpper(args[0].(string)), nil
    },
})
query, err := jmespath.Compile("upper(name)", option)

Signatures support unions, string/number/object/array/boolean/null, homogeneous string/number arrays, expression references, and a final variadic argument. Zero-argument functions are checked as zero-argument functions. Custom definitions may override standard functions. ExpressionReference supports user functions accepting an &expression argument. Go callbacks replace TypeScript subclassing and decorators.

Pass a compiled expression to logger.HandlerOptions.CorrelationExtractor. Logger only depends on the small Search(any) (any, error) interface, so installing Logger alone does not install this module. A configured CorrelationID callback takes precedence, followed by the extractor, then a built-in source. Extraction failures reach Logger's instrumentation error callback without changing the business result. See the offline query example.

Combine envelope decoding and Logger¶

The maintained example decodes SQS bodies and extracts a Logger correlation ID:

// Command query decodes an SQS envelope and extracts a correlation value offline.
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/rambow-cloud/powertools-lambda-go/jmespath"
    "github.com/rambow-cloud/powertools-lambda-go/logger"
)

func main() {
    event := map[string]any{"Records": []any{map[string]any{"body": `{"orderId":"order-1"}`}}}
    payloads, err := jmespath.ExtractDataFromEnvelope(event, jmespath.SQS)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(payloads)
    l := logger.New()
    handler := logger.WrapHandler(l, func(ctx context.Context, _ any) (string, error) {
        return "ok", l.WithContext(ctx).Info("order received")
    }, logger.HandlerOptions{
        CorrelationExtractor: jmespath.MustCompile("Records[0].powertools_json(body).orderId", jmespath.WithPowertoolsFunctions()),
    })
    if _, err = handler(context.Background(), event); err != nil {
        log.Fatal(err)
    }
}

It prints decoded payloads followed by a log with correlation_id: "order-1".

Objects and lifecycle¶

See the finite boundary audit for numeric conversion, JSON v2 serialization and null multi-select evidence, along with explicit native differences and remaining broad gates.