This example shows how to plug a third-party serialization library into the Durable Task Python SDK by implementing a custom DataConverter. It uses pydantic to serialize and validate payloads, and proves the integration works end-to-end with in-process tests that need no sidecar, emulator, or Azure resources.

You can copy this entire folder into a new directory and run it as a standalone project.

By default the SDK serializes payloads with its built-in JSON codec (JsonDataConverter), which understands builtins, dataclasses, and objects that expose to_json() / from_json() hooks. It does not know about pydantic models. Supplying a custom DataConverter lets you route serialization through any library you like — pydantic, attrs, marshmallow, a schema registry, an encryption layer, etc. — at every payload boundary the SDK touches.

Both the worker and the client accept a data_converter argument, and the SDK routes every payload boundary through it — orchestrator / activity / entity inputs and outputs, external events, and custom status:

converter = PydanticDataConverter()

worker = DurableTaskSchedulerWorker(..., data_converter=converter)
client = DurableTaskSchedulerClient(..., data_converter=converter)

A DataConverter implements three methods:

The converter in src/converter.py recognizes pydantic.BaseModel subclasses and uses pydantic for them, delegating everything else to the default JsonDataConverter. This "handle my types, delegate the rest" shape is a good starting point for a real converter — it costs nothing for non-pydantic payloads.

There is one extra detail for reconstructing inbound orchestrator/activity inputs. Before the SDK hands an input to your converter, it asks the converter whether the function's annotated input type is something it can rebuild, via DataConverter.can_reconstruct(target_type). The default implementation recognizes dataclasses and from_json()-capable types (and Optional / list wrappers) — it does not know about pydantic models, so without an override an input annotated order: Order would arrive as a plain dict.

The converter overrides can_reconstruct to also recognize pydantic.BaseModel subclasses, deferring everything else to the same JsonDataConverter fallback it uses for serialization:

def can_reconstruct(self, target_type):
    if _is_model_type(target_type):
        return True
    return self._fallback.can_reconstruct(target_type)  # dataclasses, from_json, ...

The base DataConverter.can_reconstruct is conservative — it returns False, so a converter only claims the types it actually rebuilds. Outbound values, return_type= arguments, and typed client accessors (state.get_output(Receipt)) don't depend on this hook — they pass the type to the converter directly.

custom_data_converter/
├── README.md
├── requirements.txt
├── src/
│   ├── __init__.py
│   ├── converter.py    # PydanticDataConverter — the integration point
│   ├── workflows.py    # pydantic models + orchestrator/activities
│   └── app.py          # runs against a real DTS backend / emulator
└── test/
    ├── __init__.py
    └── test_custom_converter.py  # in-process proof using the in-memory backend

The models in src/workflows.py are plain pydantic.BaseModel subclasses — not dataclasses — so they only round-trip correctly because of the custom converter. The tests in test/test_custom_converter.py verify:

1. A pydantic Order passed as orchestration input arrives at the orchestrator/activity as a validated model instance (attribute access), not a raw dict.
2. The orchestration's pydantic Receipt result is reconstructed, typed, on the client via state.get_output(Receipt).
3. The wire payload is genuine pydantic JSON (model_dump_json), confirming the custom converter — not the default codec — handled it.
4. An input that violates a pydantic constraint fails the orchestration with a validation error, instead of passing bad data through.
5. For contrast, the default JsonDataConverter cannot serialize a pydantic model at all (it raises TypeError) — which is exactly what motivates the custom converter.

1. Copy this folder to a new location and cd into it:

   cd custom_data_converter

2. Create and activate a virtual environment:

   Bash:

   python -m venv .venv
   source .venv/bin/activate

   PowerShell:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

3. Install dependencies:

   pip install -r requirements.txt

From the custom_data_converter/ directory:

pytest test/

This is the self-contained proof: it runs the full orchestration in-process against the in-memory backend.

Start the DTS emulator, then from the custom_data_converter/ directory:

python -m src.app