Serialization¶

Lambda serializes handler return values with JSON.stringify. The same types that work with defaultSerdes work as handler return values.

Lambda serializes handler return values with json.dumps. Types like datetime and Decimal are safe inside steps because ExtendedTypeSerDes handles them, but returning them directly from your handler raises TypeError: Object of type X is not JSON serializable. This is a common error when working with Amazon DynamoDB results. Convert those values to JSON-safe types before returning from the handler.

Lambda serializes handler return values with Jackson. The same JacksonSerDes configuration applies to both step results and handler return values when you use DurableHandler.

The SDK decodes the handler's input and encodes its return value with encoding/json, with HTML escaping disabled. A Serdes set with WithSerdes or ConfigureSerdes does not affect them. It applies only to durable operation results.

The SDK decodes the handler's event and encodes its return value with serde_json, so the event type implements Deserialize and the return type implements Serialize. A serdes set with .serdes(..) does not affect them. It applies only to durable operation results. If serde_json cannot encode the return value, the execution fails with error type Error and the serde_json error message.

The registered ILambdaSerializer serializes everything: durable operation results and the handler's final return value. There is no separate serializer for operation results, so the same configuration always applies to both.

The default is defaultSerdes, which uses JSON.stringify to serialize and JSON.parse to deserialize. It handles any value that JSON.stringify accepts.

The default is ExtendedTypeSerDes. It uses plain JSON for primitives (None, str, int, float, bool, and lists of primitives) and an envelope format for everything else. The envelope format preserves the exact Python type through the round-trip.

Supported types beyond primitives: datetime, date, Decimal, UUID, bytes, bytearray, memoryview, tuple, list, dict, and BatchResult.

The default is JacksonSerDes, which uses Jackson's ObjectMapper. It supports Java 8 time types, serializes dates as ISO-8601 strings, and ignores unknown properties during deserialization.

Pass a custom ObjectMapper to the JacksonSerDes constructor to override the default configuration.

The default is JSONSerdes, which encodes with encoding/json and HTML escaping disabled, so <, >, and & stay literal in the stored JSON. Map keys are sorted and a nil value encodes as null. It handles any value encoding/json accepts. A type that does not round-trip through encoding/json needs a custom Serdes.

The default is durable::JsonSerdes, which encodes compact JSON with serde_json. It handles any type that implements Serialize and DeserializeOwned, and the compiler rejects an operation whose result type does not. Serde attributes such as #[serde(rename = "...")] apply. The batch result of a map or parallel operation defaults to durable::PassthroughSerdes instead, as the map section below shows.

There is no per-operation default SerDes. Register a single ILambdaSerializer at the host boundary and the SDK uses it for every durable operation result.

Use DefaultLambdaJsonSerializer (from Amazon.Lambda.Serialization.SystemTextJson) for reflection-based serialization. For AOT or trim-friendly functions, use SourceGeneratorLambdaJsonSerializer<TContext> and register your JsonSerializerContext.

import { Serdes, SerdesContext } from "@aws/durable-execution-sdk-js";

// Serdes<T> interface
interface SerdesInterface<T> {
  serialize: (value: T | undefined, context: SerdesContext) => Promise<string | undefined>;
  deserialize: (data: string | undefined, context: SerdesContext) => Promise<T | undefined>;
}

// SerdesContext
interface SerdesContextShape {
  entityId: string;
  durableExecutionArn: string;
}

Parameters:

• serialize An async function that receives the value and a SerdesContext, and returns Promise<string | undefined>.
• deserialize An async function that receives the serialized string and a SerdesContext, and returns Promise<T | undefined>.

Both methods are async so that implementations can interact with external services such as S3 or KMS.

SerdesContext fields:

• entityId The operation ID for the current step or operation.
• durableExecutionArn The ARN of the current durable execution.

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Generic, TypeVar

T = TypeVar("T")


@dataclass(frozen=True)
class SerDesContext:
    operation_id: str = ""
    durable_execution_arn: str = ""


class SerDes(ABC, Generic[T]):
    @abstractmethod
    def serialize(self, value: T, serdes_context: SerDesContext) -> str: ...

    @abstractmethod
    def deserialize(self, data: str, serdes_context: SerDesContext) -> T: ...

Parameters:

• serialize(value, serdes_context) Converts the value to a string.
• deserialize(data, serdes_context) Converts the string back to the original type.

SerDesContext fields:

• operation_id The operation ID for the current step or operation.
• durable_execution_arn The ARN of the current durable execution.

import software.amazon.lambda.durable.TypeToken;
import software.amazon.lambda.durable.serde.SerDes;

// SerDes interface
interface SerDesInterface {
    String serialize(Object value);

    <T> T deserialize(String data, TypeToken<T> typeToken);
}

Parameters:

• serialize(Object value) Converts the value to a JSON string. Returns null if value is null.
• deserialize(String data, TypeToken<T> typeToken) Converts the JSON string back to type T. Returns null if data is null.

Use TypeToken<T> to capture generic type information that Java erases at runtime. For example: new TypeToken<List<String>>() {}.

The interface is Serdes. Its methods are Marshal and Unmarshal, which work with byte slices and take a context.Context for external calls.

type Serdes interface {
    Marshal(ctx context.Context, meta SerdesContext, v any) ([]byte, error)
    Unmarshal(ctx context.Context, meta SerdesContext, data []byte, v any) error
}

type SerdesContext struct {
    // OperationID is the positional ID of the operation being serialized
    // (e.g., "1", "1-2-3").
    OperationID string

    // DurableExecutionArn is the ARN of the current durable execution.
    DurableExecutionArn string
    // Has unexported fields.
}

Methods:

• Marshal(ctx, meta, v) Converts the value to bytes.
• Unmarshal(ctx, meta, data, v) Fills the pointer v from the bytes.

SerdesContext fields:

• OperationID The operation ID for the current step or operation.
• DurableExecutionArn The ARN of the current durable execution.

The interface takes any, so one Serdes serves every result type. For a serdes written for one type, use SerdesOf. A serdes failure is permanent by default. Return RetryableSerdesError to make it transient.

The trait is durable::Serdes<T>, where T is the operation's result type. Both methods return a future, so an implementation can call external services such as Amazon S3 or AWS KMS. A method that does no async work can return std::future::ready(..). The SDK serializes and deserializes step, child-context, with_retry, map item, and parallel branch results and wait-for-condition state. It only deserializes invoke results and callback payloads.

pub trait Serdes<T>: Send + Sync + 'static {
    fn serialize(
        &self,
        value: T,
        context: SerdesContext,
    ) -> impl Future<Output = Result<String, BoxError>> + Send;

    fn deserialize(
        &self,
        wire: String,
        context: SerdesContext,
    ) -> impl Future<Output = Result<T, BoxError>> + Send;
}

// ...

impl SerdesContext {
    // ...
    pub fn operation_id(&self) -> &str;
    // ...
    pub fn durable_execution_arn(&self) -> &str;
    // ...
    pub fn origin(&self) -> PayloadOrigin;
    // ...
}

// ...

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum PayloadOrigin {
    SdkRecord,
    External,
}

Methods:

• serialize(&self, value, context) Converts the value to a string.
• deserialize(&self, wire, context) Converts the string back to T.

SerdesContext methods:

• operation_id() The operation ID for the current step or operation.
• durable_execution_arn() The ARN of the current durable execution.
• origin() PayloadOrigin::SdkRecord for a value the SDK recorded, or PayloadOrigin::External for a callback payload or invoke result.

A serdes failure is permanent by default. Wrap the error in durable::serdes::RetryableSerdesError to make it transient. To share one serdes between operations, wrap it in an Arc, which implements Serdes<T> as well.

.NET has no per-operation SerDes interface. Serialization is controlled by the single ILambdaSerializer registered on ILambdaContext.Serializer.

// .NET has no per-operation SerDes interface. Serialization for every durable
// operation is handled by the single ILambdaSerializer registered on
// ILambdaContext.Serializer. Implement this interface to customize serialization.
public interface ILambdaSerializer
{
    T Deserialize<T>(Stream requestStream);

    void Serialize<T>(T response, Stream responseStream);
}

Methods:

• Serialize<T>(T response, Stream responseStream) Writes the serialized form of response to responseStream.
• Deserialize<T>(Stream requestStream) Reads requestStream and returns the deserialized value of type T.

The same ILambdaSerializer handles every durable operation result and the handler's return value.

Implement Marshal and Unmarshal on a type. For a serdes that handles one result type, SerdesOf is shorter, as the next example shows.

package main

import (
    "context"
    "encoding/json"

    "github.com/aws/aws-durable-execution-sdk-go/durable"
)

type Order struct {
    ID    string `json:"id"`
    Total string `json:"total"`
}

// orderSerdes implements durable.Serdes for Order results.
type orderSerdes struct{}

func (orderSerdes) Marshal(_ context.Context, _ durable.SerdesContext, v any) ([]byte, error) {
    return json.Marshal(v)
}

func (orderSerdes) Unmarshal(_ context.Context, _ durable.SerdesContext, data []byte, v any) error {
    return json.Unmarshal(data, v)
}

Implement Serdes<T> on a type for the result type T it handles.

use aws_durable_execution_sdk as durable;
use durable::serdes::{Serdes, SerdesContext};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Order {
    id: String,
    total: String,
}

struct OrderSerdes;

impl Serdes<Order> for OrderSerdes {
    fn serialize(
        &self,
        value: Order,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<String, durable::BoxError>> + Send {
        std::future::ready(serde_json::to_string(&value).map_err(Into::into))
    }

    fn deserialize(
        &self,
        wire: String,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<Order, durable::BoxError>> + Send {
        std::future::ready(serde_json::from_str(&wire).map_err(Into::into))
    }
}

Implement ILambdaSerializer and register it at the host boundary. The custom serializer applies to every durable operation result, not a single operation.

using System.Text.Json;
using Amazon.Lambda.Core;

// .NET has no per-operation SerDes. Serialization is controlled by the single
// ILambdaSerializer registered on ILambdaContext.Serializer. To customize how
// durable operation results are serialized, implement ILambdaSerializer and
// register it at the host boundary instead of passing a SerDes per operation.
public class OrderLambdaSerializer : ILambdaSerializer
{
    private static readonly JsonSerializerOptions Options = new()
    {
        PropertyNameCaseInsensitive = true,
    };

    public T Deserialize<T>(Stream requestStream)
    {
        using var reader = new StreamReader(requestStream);
        string json = reader.ReadToEnd();
        return JsonSerializer.Deserialize<T>(json, Options)!;
    }

    public void Serialize<T>(T response, Stream responseStream)
    {
        string json = JsonSerializer.Serialize(response, Options);
        using var writer = new StreamWriter(responseStream, leaveOpen: true);
        writer.Write(json);
        writer.Flush();
    }
}

Pass WithStepSerdes to override the serializer for one step's result. Other operations keep the default. The other per-operation options are WithChildSerdes, WithInvokePayloadSerdes, WithInvokeResultSerdes, and WithTypedBranchSerdes. A per-operation option takes precedence over the handler default set with WithSerdes or ConfigureSerdes.

package main

import (
    "context"
    "encoding/json"

    "github.com/aws/aws-durable-execution-sdk-go/durable"
)

type Order struct {
    ID    string `json:"id"`
    Total string `json:"total"`
}

var orderSerdes = durable.SerdesOf(
    func(_ context.Context, _ durable.SerdesContext, o Order) ([]byte, error) {
        return json.Marshal(o)
    },
    func(_ context.Context, _ durable.SerdesContext, data []byte) (Order, error) {
        var o Order
        err := json.Unmarshal(data, &o)
        return o, err
    },
)

func handler(ctx durable.Context, _ any) (Order, error) {
    return durable.Step(ctx, "fetch-order", func(durable.StepContext) (Order, error) {
        return Order{ID: "order-123", Total: "99.99"}, nil
    }, durable.WithStepSerdes(orderSerdes))
}

func main() { durable.Start(handler) }

Pass a serdes to the step's .serdes(..). Other operations keep the default. The serdes must implement Serdes<O> for the step's result type O. The builders of child contexts, with_retry, invoke, callbacks, wait for callback, wait for condition, map, and parallel have the same .serdes(..) method. An invoke also has .payload_serdes(..) for its input, which takes a durable::PayloadSerializer. JsonSerdes is the default payload serializer.

use aws_durable_execution_sdk as durable;
use durable::serdes::{Serdes, SerdesContext};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Order {
    id: String,
    total: String,
}

struct OrderSerdes;

impl Serdes<Order> for OrderSerdes {
    fn serialize(
        &self,
        value: Order,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<String, durable::BoxError>> + Send {
        std::future::ready(serde_json::to_string(&value).map_err(Into::into))
    }

    fn deserialize(
        &self,
        wire: String,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<Order, durable::BoxError>> + Send {
        std::future::ready(serde_json::from_str(&wire).map_err(Into::into))
    }
}

async fn handler(
    _event: serde_json::Value,
    ctx: durable::DurableContext,
) -> Result<Order, durable::BoxError> {
    let order = ctx
        .step(|_| async {
            Ok(Order {
                id: "order-123".to_owned(),
                total: "99.99".to_owned(),
            })
        })
        .name("fetch-order")
        .serdes(OrderSerdes)
        .await?;
    Ok(order)
}

#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
    durable::init_default_subscriber()?;
    durable::run(handler).await
}

StepConfig does not expose a serializer. The step result is serialized with the ILambdaSerializer registered at the host boundary. Register a custom ILambdaSerializer there to change how step results are serialized.

using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;

public class StepConfigExample
{
    public Task<DurableExecutionInvocationOutput> Handler(
        DurableExecutionInvocationInput input, ILambdaContext context)
        => DurableFunction.WrapAsync<object, Order>(Workflow, input, context);

    private async Task<Order> Workflow(object input, IDurableContext ctx)
    {
        // StepConfig has no serializer slot. The step result is serialized with
        // the ILambdaSerializer registered on ILambdaContext.Serializer. To
        // customize serialization, register a custom ILambdaSerializer at the
        // host boundary instead of setting a per-step SerDes.
        var config = new StepConfig
        {
            RetryStrategy = RetryStrategy.Exponential(maxAttempts: 3),
        };

        Order order = await ctx.StepAsync(
            async (_, _) => new Order("order-123", "99.99"),
            name: "fetch-order",
            config: config);
        return order;
    }
}

public record Order(string Id, string Total);

In TypeScript, the callback SerDes only needs deserialize. The serialize method is not used because the external system provides the payload directly.

import {
  DurableContext,
  Serdes,
  SerdesContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

interface ApprovalResult {
  approved: boolean;
  reason: string;
}

// Callbacks only need deserialization — the external system sends the payload.
const approvalSerdes: Omit<Serdes<ApprovalResult>, "serialize"> = {
  deserialize: async (data: string | undefined, _ctx: SerdesContext) =>
    data !== undefined ? (JSON.parse(data) as ApprovalResult) : undefined,
};

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const [approval, callbackId] = await context.createCallback("await-approval", {
      serdes: approvalSerdes,
    });

    // Send callbackId to the external system here.
    console.log("Callback ID:", callbackId);

    const result = await approval;
    return result;
  },
);

The default callback deserializer is RawSerdes, which returns the submitted bytes unchanged. So by default the result type must be string, []byte, or json.RawMessage. Any other type fails with a *SerdesError. Pass WithCallbackSerdes(JSONSerdes) to decode a JSON payload into a struct.

For a callback payload, the per-operation WithCallbackSerdes takes precedence over the handler-wide Deserializer. When neither is set, the payload passes through RawSerdes. Set the handler-wide Deserializer with WithCallbackDeserializer, or from inside the handler with the CallbackDeserializer field of ConfigureSerdes. A Deserializer has one method, Unmarshal(data []byte, v any) error. The handler-level WithSerdes does not apply to callback payloads. WaitForCallback accepts the same WithCallbackSerdes option and decodes the payload once, at the WaitForCallback operation.

package main

import (
    "github.com/aws/aws-durable-execution-sdk-go/durable"
)

type ApprovalResult struct {
    Approved bool   `json:"approved"`
    Reason   string `json:"reason"`
}

func handler(ctx durable.Context, _ any) (ApprovalResult, error) {
    // JSONSerdes decodes the payload the external system sends into the struct.
    approval, err := durable.CreateCallback[ApprovalResult](ctx, "await-approval",
        durable.WithCallbackSerdes(durable.JSONSerdes))
    if err != nil {
        return ApprovalResult{}, err
    }

    // Send approval.ID() to the external system here.
    ctx.Logger().Info("Callback ID", "callbackId", approval.ID())

    return approval.Result(ctx)
}

func main() { durable.Start(handler) }

Pass the serdes to the callback builder's .serdes(..). The SDK calls only its deserialize, which decodes the payload as JSON in this example. The trait requires serialize too, but the SDK never calls it for a callback. Without .serdes(..), the default JsonSerdes decodes the payload as JSON into the result type. To receive the payload unchanged, use .serdes(PassthroughSerdes) with create_callback::<String>().

use aws_durable_execution_sdk as durable;
use durable::serdes::{Serdes, SerdesContext};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct ApprovalResult {
    approved: bool,
    reason: String,
}

struct ApprovalSerdes;

impl Serdes<ApprovalResult> for ApprovalSerdes {
    fn serialize(
        &self,
        value: ApprovalResult,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<String, durable::BoxError>> + Send {
        std::future::ready(serde_json::to_string(&value).map_err(Into::into))
    }

    fn deserialize(
        &self,
        wire: String,
        _context: SerdesContext,
    ) -> impl Future<Output = Result<ApprovalResult, durable::BoxError>> + Send {
        std::future::ready(serde_json::from_str(&wire).map_err(Into::into))
    }
}

async fn handler(
    _event: serde_json::Value,
    ctx: durable::DurableContext,
) -> Result<ApprovalResult, durable::BoxError> {
    let approval = ctx
        .create_callback::<ApprovalResult>()
        .name("await-approval")
        .serdes(ApprovalSerdes)
        .await?;

    // Send the callback ID to the external system here.
    tracing::info!("Callback ID: {}", approval.id());

    let result = approval.result().await?;
    Ok(result)
}

#[tokio::main]
async fn main() -> Result<(), lambda_runtime::Error> {
    durable::init_default_subscriber()?;
    durable::run(handler).await
}

CallbackConfig does not expose a serializer. The payload the external system delivers is deserialized with the ILambdaSerializer registered at the host boundary. Register a custom ILambdaSerializer there to change how the callback payload is deserialized.

using Amazon.Lambda.Core;
using Amazon.Lambda.DurableExecution;

public class CallbackConfigExample
{
    public Task<DurableExecutionInvocationOutput> Handler(
        DurableExecutionInvocationInput input, ILambdaContext context)
        => DurableFunction.WrapAsync<object, ApprovalResult>(Workflow, input, context);

    private async Task<ApprovalResult> Workflow(object input, IDurableContext ctx)
    {
        // CallbackConfig has no serializer slot. The callback payload delivered by
        // the external system is deserialized with the ILambdaSerializer registered
        // on ILambdaContext.Serializer. To customize deserialization, register a
        // custom ILambdaSerializer at the host boundary.
        var config = new CallbackConfig
        {
            Timeout = TimeSpan.FromHours(1),
        };

        ICallback<ApprovalResult> callback =
            await ctx.CreateCallbackAsync<ApprovalResult>("await-approval", config);

        // Send callback.CallbackId to the external system here.
        return await callback.GetResultAsync();
    }
}

public record ApprovalResult(bool Approved, string Reason);

import {
  BatchResult,
  DurableContext,
  MapConfig,
  Serdes,
  SerdesContext,
  withDurableExecution,
} from "@aws/durable-execution-sdk-js";

interface ProcessedItem {
  id: string;
  status: string;
}

const itemSerdes: Serdes<ProcessedItem> = {
  serialize: async (value: ProcessedItem | undefined, _ctx: SerdesContext) =>
    value !== undefined ? JSON.stringify(value) : undefined,
  deserialize: async (data: string | undefined, _ctx: SerdesContext) =>
    data !== undefined ? (JSON.parse(data) as ProcessedItem) : undefined,
};

const mapConfig: MapConfig<string, ProcessedItem> = {
  itemSerdes,
};

export const handler = withDurableExecution(
  async (event: unknown, context: DurableContext) => {
    const items = ["a", "b", "c"];
    const result: BatchResult<ProcessedItem> = await context.map(
      "process-items",
      items,
      async (_ctx, item) => ({ id: item, status: "done" }),
      mapConfig,
    );
    return result.getResults();
  },
);

• itemSerdes serializes each item result.
• serdes serializes the aggregated BatchResult.
• ParallelConfig has the same two fields.

import json

from aws_durable_execution_sdk_python import (
    DurableContext,
    durable_execution,
)
from aws_durable_execution_sdk_python.config import MapConfig
from aws_durable_execution_sdk_python.serdes import SerDes, SerDesContext


class ItemSerDes(SerDes[dict]):
    def serialize(self, value: dict, ctx: SerDesContext) -> str:
        return json.dumps(value)

    def deserialize(self, data: str, ctx: SerDesContext) -> dict:
        return json.loads(data)


@durable_execution
def handler(event: dict, context: DurableContext) -> list:
    items = ["a", "b", "c"]
    result = context.map(
        items,
        lambda ctx, item, idx, arr: {"id": item, "status": "done"},
        config=MapConfig(item_serdes=ItemSerDes()),
    )
    return result.get_results()

• item_serdes serializes each item result.
• serdes serializes the aggregated BatchResult.
• When you provide only serdes, the SDK uses it for both for backward compatibility. ParallelConfig has the same two fields.

import java.util.List;
import java.util.Map;
import software.amazon.lambda.durable.DurableContext;
import software.amazon.lambda.durable.DurableHandler;
import software.amazon.lambda.durable.config.MapConfig;
import software.amazon.lambda.durable.model.MapResult;
import software.amazon.lambda.durable.serde.JacksonSerDes;

public class MapConfigExample extends DurableHandler<Object, List<Map<String, String>>> {
    @Override
    public List<Map<String, String>> handleRequest(Object input, DurableContext context) {
        MapConfig config = MapConfig.builder()
            .serDes(new JacksonSerDes())
            .build();

        List<String> items = List.of("a", "b", "c");
        MapResult<Map<String, String>> result = context.map(
            "process-items",
            items,
            Map.class,
            (item, index, ctx) -> Map.of("id", item, "status", "done"),
            config
        );
        return result.succeeded();
    }
}

• serDes applies to each item result.
• Java ParallelConfig does not have a serDes field.

Two batch options apply to both Map and Parallel:

• WithBatchSerdes serializes each item result. Default: the handler serdes.
• WithBatchResultSerdes serializes the aggregated BatchResult. Without it, the SDK stores the BatchResult through the item serdes.

package main

import (
    "context"
    "encoding/json"

    "github.com/aws/aws-durable-execution-sdk-go/durable"
)

type ProcessedItem struct {
    ID     string `json:"id"`
    Status string `json:"status"`
}

var itemSerdes = durable.SerdesOf(
    func(_ context.Context, _ durable.SerdesContext, p ProcessedItem) ([]byte, error) {
        return json.Marshal(p)
    },
    func(_ context.Context, _ durable.SerdesContext, data []byte) (ProcessedItem, error) {
        var p ProcessedItem
        err := json.Unmarshal(data, &p)
        return p, err
    },
)

func handler(ctx durable.Context, _ any) ([]ProcessedItem, error) {
    items := []string{"a", "b", "c"}
    result, err := durable.Map(ctx, "process-items", items,
        func(_ durable.Context, item string, _ int) (ProcessedItem, error) {
            return ProcessedItem{ID: item, Status: "done"}, nil
        },
        durable.WithBatchSerdes(itemSerdes),
    )
    if err != nil {
        return nil, err
    }
    return result.Results(), nil
}

func main() { durable.Start(handler) }