Skip to main content

​
Overview

Express Zod API uses branded types to distinguish its proprietary schemas from regular Zod schemas. These brands enable special handling for dates, files, forms, and raw data. 
import { ez } from "express-zod-api";

​
The ez Object

All proprietary schemas are accessed through the ez object: 
export const ez = {
  dateIn,
  dateOut,
  form,
  upload,
  raw,
  buffer,
  paginated,
};

​
Schema Brands

Each proprietary schema has a unique brand for type identification: 
type ProprietaryBrand =
  | typeof ezFormBrand
  | typeof ezDateInBrand
  | typeof ezDateOutBrand
  | typeof ezUploadBrand
  | typeof ezRawBrand
  | typeof ezBufferBrand;

​
Date Schemas

​
ezDateInBrand

Identifies schemas created with ez.dateIn(). 
import { ez } from "express-zod-api";

const schema = ez.dateIn();
// Brand: ezDateInBrand
// Input: ISO string
// Output: Date object

​
ezDateOutBrand

Identifies schemas created with ez.dateOut(). 
const schema = ez.dateOut();
// Brand: ezDateOutBrand
// Input: Date object
// Output: ISO string

​
File Schemas

​
ezUploadBrand

Identifies file upload schemas created with ez.upload(). 
const schema = ez.upload();
// Brand: ezUploadBrand
// Content-Type: multipart/form-data

​
ezBufferBrand

Identifies buffer schemas for binary responses. 
const schema = ez.buffer();
// Brand: ezBufferBrand
// Used in ResultHandler positive schemas

​
Form Schema

​
ezFormBrand

Identifies form data schemas created with ez.form(). 
const schema = ez.form({ name: z.string() });
// Brand: ezFormBrand
// Content-Type: application/x-www-form-urlencoded

​
Raw Data Schema

​
ezRawBrand

Identifies raw buffer schemas created with ez.raw(). 
const schema = ez.raw();
// Brand: ezRawBrand
// Input: Raw Buffer from request body

​
Brand Usage

The framework uses these brands internally to:
  1. Select correct parsers - Form data, JSON, multipart, or raw
  2. Generate accurate OpenAPI specs - Correct content types and schemas
  3. Transform data - Convert between Date objects and ISO strings
  4. Validate input - Apply appropriate validation logic

​
Type Safety

Brands ensure type safety throughout the request/response cycle: 
// Input transformation
ez.dateIn() // string -> Date
ez.raw()    // raw body -> Buffer
ez.form()   // form data -> validated object
ez.upload() // multipart -> UploadedFile

// Output transformation  
ez.dateOut() // Date -> string
ez.buffer()  // Buffer -> binary response

​
Combining Schemas

Proprietary schemas work seamlessly with regular Zod schemas: 
import { z } from "zod";
import { ez } from "express-zod-api";

const input = z.object({
  title: z.string(),
  publishDate: ez.dateIn(),
  image: ez.upload().optional(),
});

const output = z.object({
  id: z.string(),
  createdAt: ez.dateOut(),
  url: z.string().url(),
});

​
See Also

ez Schemas

Complete ez schema reference

Zod Plugin

Zod extensions and helpers

Schema Validation

Input/output validation

OpenAPI

OpenAPI schema generation

Build docs developers (and LLMs) love

Get started for freeTalk to us