@ymgn-dev/zodify v2.5.0

Zodify

A tool that generates Zod type definitions from OpenAPI YAML.

!WARNING Please note that this tool only targets YAML generated based on TypeSpec definitions.

Japanese version: README_ja.md

Setup

git clone git@github.com:ymgn-dev/zodify.git
cd zodify
npm run build

Usage

Specify the OpenAPI YAML file with the -i option and the output .ts file with the -o option.

node dist/index.mjs -i ./path/to/openapi.yaml -o ./path/to/output.ts

Supported Syntax

Comment Decorators

You can add comments to models and properties using the @doc() decorator.

@doc("This is a comment for the model")
model SampleModel {
  @doc("This is the model's ID")
  @format("uuid")
  id: string;

  @doc("Creation date")
  createdAt: utcDateTime;

  @doc("Update date")
  updatedAt: utcDateTime;
}

The above model will be converted as follows:

// This is a comment for the model
export const sampleModelSchema = z.object({
  // This is the model's ID
  id: z.string().uuid(),

  // Creation date
  createdAt: z.string().datetime(),

  // Update date
  updatedAt: z.string().datetime(),
})

Additionally, if you want to generate Zod schemas that cannot be expressed using the standard decorators below, you can use an extended notation for the @doc() decorator. Write regular comments (optional) to the left of zod:, and the Zod schema on the right. Note that when using this extended notation, the type-specific decorators below will be ignored.

model SampleModel {
  @doc("Email address, unset defaults to an empty string zod: z.union([z.string().email(), z.literal("")]).default("")")
  email: string;
}

export const sampleModelSchema = z.object({
  // Email address, unset defaults to an empty string
  email: z.union([z.string().email(), z.literal('')]).default(''),
})

Models

This syntax is used for defining top-level models.

model SampleModel {
  a: numeric;
  b: string;
}

model ArraySampleModel is Array<SampleModel> {}

enum EnumSample {
  A,
  B,
  C
}

Scalars

This syntax is used for defining types that do not exist in TypeSpec.

@doc("UUID")
@format("uuid")
scalar Uuid extends string;

@doc("Integer greater than 100")
@minValueExclusive(100)
scalar Gt100 extends int32;

The above model will be converted as follows:

// UUID
export const uuidSchema = z.string().uuid()

// Integer greater than 100
export const gt100Schema = z.number().int().gt(100)

Numbers

Additional Notes

To make properties in a TypeSpec model optional, add a ? after the property name. You can also set default values using =. It is possible to combine both optional and default values.

model Sample {
  a?: int32;
  b: integer = 42;
  c?: float = 3.14;
}

The above model will be converted as follows:

export const sampleSchema = z.object({
  a: z.number().int().optional(),
  b: z.number().int().default(42),
  c: z.number().optional().default(3.14),
})

@doc("Numeric values")
model NumericValues {
  @minValue(42.6)
  @maxValue(95.8)
  a: numeric;

  @minValueExclusive(8)
  @maxValueExclusive(16)
  b: integer;

  @doc("Optional input")
  c: float;

  @doc("Has a default value")
  d: int64 = 42;
  e: int32;
  f: int16;
  g: int8;
  h: safeint;
  i: uint64;
  j: uint32;
  k: uint16;
  l: uint8;
  m: float64;
  n: float32;
  o: decimal;
  p: decimal128;
}

Strings

!WARNING bytes is not supported because it is not defined in Zod.

!NOTE Some types are not supported in TypeSpec but are supported in Zod. These types can be converted using the @format() decorator described below.

Additional Notes

To make properties in a TypeSpec model optional, add a ? after the property name. You can also set default values using =. It is possible to combine both optional and default values.

model Sample {
  a?: string;
  b: string = "Sample string";
  c?: string = "Sample string";
}

The above model will be converted as follows:

export const sampleSchema = z.object({
  a: z.string().optional(),
  b: z.string().default('Sample string'),
  c: z.string().optional().default('Sample string'),
})

@doc("String values")
model StringValues {
  @minLength(42)
  @maxLength(96)
  a: string;

  b: plainDate;
  c: plainTime;
  d: utcDateTime;
  e: offsetDateTime;
  f: duration;
  g: url;

  @format("email")
  h: string;

  @format("uuid")
  i: string;
}

Booleans

Additional Notes

To make properties in a TypeSpec model optional, add a ? after the property name. You can also set default values using =. It is possible to combine both optional and default values.

model Sample {
  a?: boolean;
  b: boolean = true;
  c?: boolean = false;
}

The above model will be converted as follows:

export const sampleSchema = z.object({
  a: z.boolean().optional(),
  b: z.boolean().default(true),
  c: z.boolean().optional().default(false),
})

@doc("Boolean values")
model BooleanValues {
  a: boolean;
}

Arrays, Objects, and Enums

!WARNING Record<Element> is not currently supported.

Additional Notes

To make properties in a TypeSpec model optional, add a ? after the property name. You can also set default values using =. For arrays, TypeSpec requires default values to be written as #[...]. It is possible to combine both optional and default values.

model OtherModel {
  @format("uuid")
  id: string;
}

@doc("Array test")
model Sample {
  a?: string[];
  b: string[] = #["sample1", "sample2"];
  c?: string[] = #[];
  d: int32[] = #[4, 8, 32];
  e: OtherModel[] = #[];
}

The above model will be converted as follows:

export const otherModelSchema = z.object({
  id: z.string().uuid(),
})

// Array test
export const sampleSchema = z.object({
  a: z.array(z.string()).optional(),
  b: z.array(z.string()).default(['sample1', 'sample2']),
  c: z.array(z.string()).optional().default([]),
  d: z.array(z.number().int()).default([4, 8, 32]),
  e: z.array(otherModelSchema).default([]),
})

@doc("Arrays")
model ArrayValues {
  @minItems(42)
  @maxItems(96)
  a: string[];

  b: OtherModel[];
}

Others

!WARNING null, unknown, void, and never are not currently supported.