Complex nested Codecs

[julienmonnard]

Hello! I tried asking on Discord as well, but not everybody is there, and I want to increase my chances of getting help 🙂

I found a somewhat similar discussion, but the goal seems different than what I am trying to achieve.

I am currently investigating if I could use the new codecs to transform a complex data structure from our server to our client. As this new feature has a few examples in the documentation and is even cited as "very useful when parsing data at a network boundary", I assume this is the way to go.

What is not in the documentation or examples though, is how to handle codecs that are nested into one-another, and this is where my issues start.

Assuming I have 2 types of elements, that have slightly different shape between my server and my client, I would create codecs like this. I will try to simplify as much as possible for this discussion:

const ParagraphItem = z.literal('paragraph');
const ImageItem = z.literal('image');

const ServerParagraph = z.object({
    type: ParagraphItem,
    value: z.string(),
});

const ClientParagraph = z.object({
    type: ParagraphItem,
    value: z.object({ text: z.string() }),
});

const ServerImage = z.object({
    type: ImageItem,
    value: z.url(),
});

const ClientImage = z.object({
    type: ImageItem,
    value: z.object({ url: z.url() }),
});

const Paragraph = z.codec(ServerParagraph, ClientParagraph, {
    decode: (serverParagraph) => ({
        type: serverParagraph.type,
        value: { text: serverParagraph.value },
    }),
    encode: (clientParagraph) => ({
        type: clientParagraph.type,
        value: clientParagraph.value.text,
    }),
});
const Image = z.codec(ServerImage, ClientImage, {
    decode: (serverImage) => ({
        type: serverImage.type,
        value: { url: serverImage.value },
    }),
    encode: (clientImage) => ({
        type: clientImage.type,
        value: clientImage.value.url,
    }),
});

const Content = z.union([Paragraph, Image]);
// I also tried doing it with discriminated union, but unfortunately it breaks at runtime
// const Content = z.discriminatedUnion('type', [Paragraph, Image]);

So far so good.

What get's tricky for me to understand though, is how to define the parent schemas based on this.

This is, purely in types, what I need to deal with:

type ServerSchema = {
    serverContent:
        | {
              type: 'paragraph';
              value: string;
          }
        | {
              type: 'image';
              value: string;
          };
};

type ClientSchema = {
    clientContent:
        | {
              type: 'paragraph';
              value: { text: string };
          }
        | {
              type: 'image';
              value: { url: string };
          };
};

Instinctively, the way I would replicate it with Zod is by using Content this way:

const ServerSchema = z.object({
    data: Content,
});

const ClientSchema = z.object({
    data: Content,
});

const Schema = z.codec(ServerSchema, ClientSchema, {
    decode: ...,
    encode: ...,
});

but then the function for decode and encode start to feel off.
From what I understood, all the schemas in Zod are processed from the lower levels to the upper levels. But this leads to the data arriving to the codec as partially transformed, and in order to satisfy both TS and the runtime, I end up having to re-transform the data so that it can be handled by the "upper" codec, like this:

const Schema = z.codec(ServerSchema, ClientSchema, {
    decode: (serverData) => ({
        data: Content.encode(serverData.data),
    }),
    encode: (clientData) => ({
        data: Content.decode(clientData.data),
    }),
});

and it quickly gets worse as I add more nesting 😕

I found some kind of alternative like this, but it still feels wrong, because it works only if I use out, but not if I also use in:

const Content = z.union([Paragraph, Image]);
const ContentOut = z.union([Paragraph.out, Image.out]);

const ServerSchema = z.object({
    serverContent: Content,
});

const ClientSchema = z.object({
    clientContent: ContentOut,
});

const Schema = z.codec(ServerSchema, ClientSchema, {
    decode: (serverData) => ({
        clientContent: serverData.serverContent,
    }),
    encode: (clientData) => ({
        serverContent: clientData.clientContent,
    }),
});

and I suspect that the data ends up not being transformed correctly at all the levels.

So my question is basically, is there a better way of doing this, or am I abusing the feature to do something it was not meant to do?

The documentation says that codecs are like any other schema, and there are no rules on where I can use them, so I assume it's more of a skill issue than a feature limitation 😅

I hope somebody with a better understanding of codecs can help me figure it out 🤞🏻
Thanks!

[dosubot[bot]]

You're on the right track—Zod codecs are fully composable and can be nested inside objects, arrays, and other schemas, with no restrictions on where you use them. When you call .encode() or .decode() on an object schema with nested codecs, Zod will automatically apply the transformations recursively to those properties. However, unions and discriminated unions do not automatically propagate the encode/decode logic of their inner codecs. This means you need to manually wire the encode/decode logic at higher levels, as you've noticed in your examples. This is a current design decision in Zod v4, not a skill issue or a feature limitation "Codecs composability".

For unions/discriminated unions, the recommended pattern is to keep your encode/decode logic DRY by reusing the encode/decode functions from your inner codecs. You can also compose smaller codecs using intersections (.and()) to help manage complexity and avoid duplication "Codec composition". There isn't a built-in way to treat inner codecs as true black boxes in unions or containers—schemas like inputSchema or outputSchema aren't exposed for automatic extraction "Discussion".

So, your approach is correct given the current API. For deeply nested structures, helper functions and careful manual wiring are the way to go. If you want to keep things DRY, consider extracting encode/decode helpers and using intersections for composition. If you hit any runtime issues with discriminated unions, it's usually because the underlying shape is transformed by codec logic in unexpected ways—so double-check your encode/decode paths.

If you have a runnable reproduction or hit a specific edge case, feel free to share it—@colinhacks will see it and can weigh in. If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[julienmonnard]

@dosu So having to call encode within decode like below is the expected approach? 🤔

const Schema = z.codec(ServerSchema, ClientSchema, {
    decode: (serverData) => ({
        data: Content.encode(serverData.data),
    }),
    encode: (clientData) => ({
        data: Content.decode(clientData.data),
    }),
});

It does feel unintuitive though, and I'm curious about the performance impact of having to transform the data multiple times like this. Wouldn't it be quite costly on bigger payloads?

And you didn't tell me if an approach using Paragraph.in and Paragraph.out would be possible? These properties don't seem to be documented, but they do exist, are part of the TS inferred suggestions, and return the input and output schemas of the Paragraph codec (probably because codecs are built with pipes).

[dosubot[bot]]

Yes, manual wiring of encode and decode for unions (and discriminated unions) is the expected approach in Zod v4. This is because unions do not automatically propagate the encode/decode logic of their inner codecs, so you need to explicitly call the relevant methods at each level of nesting. This pattern is documented and discussed as a current design decision, not a misuse or limitation "Codecs composability", "Discussion".

On performance: Zod processes nested transformations by chaining encode/decode calls, so the runtime cost scales with the depth and size of your data structure. There are no hidden optimizations—each transformation is explicit and recursive. For large or deeply nested payloads, the cost is proportional to the number and complexity of transformations you define. If you encounter concrete performance bottlenecks, sharing a reproduction would be valuable for @colinhacks and the community.

Regarding .in and .out: these properties exist on codecs because they're implemented with pipes, but they are not documented or supported as part of the public API. They're TypeScript-accessible shortcuts to the underlying input/output schemas, not designed to simplify encode/decode wiring for unions or containers. Relying on them is risky—they may change or break in future versions, and they don't guarantee correct transformation at all levels "Discussion".

If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}