Serialization and Codecs

Default body codecs and custom serialization for clients and server adapters

HTTP values travel through URL strings, headers, or request and response bodies. These rules are shared across routes, clients, and server adapters. See the Route Builder for declaring the interface and Schemas and Validation for validation boundaries.

Path, Query, and Headers

The client stringifies scalar values. The server passes HTTP strings to request schemas, which perform any required coercion.

Undefined query and header values are omitted. Missing required path params fail on the client. Nested query objects are unsupported. A flat GET .input() uses the same query encoding as .query().

The server reconstructs tag[]=one&tag[]=two as { tag: ["one", "two"] }. A single tag[]=one remains an array. Repeated scalar keys such as tag=one&tag=two keep the last value.

Declare header schemas with lowercase names. Incoming Node and Fetch header names are normalized to lowercase and uppercase schema keys do not match them. Declare request content types through body options rather than a content-type request header.

Bodies and Content Types

Body codecs serialize values into HTTP bodies and deserialize HTTP bodies into values. .input(), .body(), .output(), and .response() default to application/json. Specifying the contentType option can select another media type. Schemas operate on values before encoding and after decoding.

Outgoing codecs are selected from the declared content type. Incoming codecs are selected from the received Content-Type header. Matching uses the lowercase base media type without parameters, so application/json; charset=utf-8 matches the JSON codec. A client response without a content-type header or body yields undefined.

For a list of request content types, select one in the client’s per-call options:

await client.files.upload(bytes, { contentType: "image/png" });

For a list of response content types, the handler selects one with its returned contentType. The schema and codecs must agree on the values represented by each selected type.

Streaming

Async iterable outputs use application/x-ndjson: each item is JSON-encoded on its own line. The client incrementally parses those lines and yields items through an async iterable.

Inferred streams, .streamOutput(), and .streamResponse() use the same framing. Streams bypass bodyCodecs. Declared item schemas validate on the server and optionally on the client with validateResponses.

Fetch Client Defaults

Client Request Serialization

Client Response Deserialization

Client response validation runs after deserialization when validateResponses is enabled. See Schemas and Validation.

Server Adapter Defaults

Servers deserialize incoming request bodies before request validation and serialize outgoing response bodies after response validation.

Server Response Serialization

Binary fallback serializers reject other values. Use a custom serializer to supply another body type supported by the adapter.

Server Request Deserialization

For Express, Fastify, and Nest, configure the framework’s request parsers or supply a custom deserializer for the content types your routes accept.

Fetch, Hono, and Node limit built-in request decoding to 1 MiB by default. Set requestBodyLimit to change the limit. Malformed bodies returns 400 Response and oversized bodies return 413 Response.

Override A Codec

Pass bodyCodecs to initClient(), registerRoutes(), createRouteHandler(), or RestRpcModule.forRoot(). Each codec has a match(mediaType) function and optional serialize and deserialize functions. Custom codecs run before the defaults. The first matching implementation wins independently for each operation, so overriding only serialization keeps the default deserializer. Both operations can be asynchronous.

For example, this codec uses Uint8Array values for binary requests and responses:

import { initClient, type BodyCodec } from "@rest-rpc/core";
import { createRouteHandler } from "@rest-rpc/fetch";
import { api } from "./contract";
import { routes } from "./routes";

const binaryCodec: BodyCodec<Request | Response> = {
	match: (mediaType) => mediaType === "application/octet-stream",
	serialize: (value) => {
		if (!(value instanceof Uint8Array)) {
			throw new TypeError("Expected Uint8Array body");
		}
		return { body: value };
	},
	deserialize: async (source) => new Uint8Array(await source.arrayBuffer()),
};

const client = initClient(api, {
	baseUrl: "https://api.example.com",
	bodyCodecs: [binaryCodec],
});

const handler = createRouteHandler(routes, {
	bodyCodecs: [binaryCodec],
});

Use schemas that accept the decoded values, and configure compatible codecs on both ends. For other server adapters, adapt deserialize to the native request source listed below and return a serialized body supported by that adapter’s response API.

Custom Server Serializer Delivery

The adapter applies the response status and headers, then delivers serialized.body as follows. A custom serializer must return a value accepted by this delivery path. Its result does not go through the default serializers.

Serializer Result

serialize(value, declaredContentType) receives the full selected content type, including parameters, and returns { body, headers?, contentType? }:

• body must be usable by the target Fetch or server response API.
• headers adds headers. Declared request or response headers take precedence. Codec headers cannot contain Content-Type, Content-Length, or Transfer-Encoding (case-insensitively).
• Omitting contentType preserves the declared content type. A string may change parameters but must keep the same base media type. null omits the explicit content-type header, allowing Fetch to supply it for bodies such as FormData.

Custom Deserializer Sources

deserialize(source) returns the value to validate and receives the native source for the configured entry point: