TypeScript → Zod 스키마

TypeScript 인터페이스와 타입 별칭을 Zod 유효성 검사 스키마로 즉시 변환. 유니언, 선택적 필드, 배열, 열거형, 중첩 객체, 타입 참조 지원. 무료, 브라우저에서 처리.

  • 브라우저에서 처리
  • 도구 입력을 ZeroTool 서버에 업로드하지 않습니다
  • 무료 · 회원가입 불필요
입력을 Address, User, Status 선언으로 바꾸고 즉시 생성합니다.
TypeScript, Zod 출력, 강조 표시와 상태를 지웁니다. 도구 안에서 Ctrl/⌘+L을 눌러도 같습니다.
interface, type 또는 enum 선언을 입력하세요. 입력을 멈춘 뒤 300밀리초 후 생성합니다. 파싱 오류가 발생하면 출력을 지우고 오류를 표시합니다. class와 제네릭 타입 정의는 지원 범위 밖입니다.
Zod 스키마 출력
import와 추론된 타입을 포함한 Zod 출력 전체를 복사합니다. 출력이 비어 있으면 복사하지 않습니다.

TypeScript를 입력하거나 예시를 불러와 Zod 스키마를 생성하세요.

예시·자세한 설명·자주 묻는 질문 실제 출력이 있는 예시, 다른 도구와의 차이, 자주 묻는 질문.

지원하는 TypeScript 기능

  • 기본 타입: string, number, boolean, null, undefined, any, unknown, void, never, bigint, symbol
  • 선택적 속성: prop?: type → .optional()
  • 유니언 타입: A | B → z.union([A, B])
  • 문자열 열거형: "a" | "b" | "c" → z.enum(["a", "b", "c"])
  • 배열: T[] / Array<T> → z.array(T)
  • 중첩 객체: 인라인 객체 타입 → z.object({})
  • 상호 참조: 선언된 타입 간의 참조 → Schema 상수
  • readonly: readonly 수식어를 허용하며, 변환 시 제거(읽기 전용 타입이 필요하면 .readonly()를 직접 추가)
  • 유틸리티 타입: Partial<T>, Record<K, V>, Promise<T>
  • 교차 타입: A & B → z.intersection(A, B)
  • 튜플: [A, B] → z.tuple([A, B])
  • 리터럴 타입: "value", 42, true → z.literal()
  • extends: interface Admin extends Base → BaseSchema.extend({ ... }). 두 번째 상위 타입은 .extend(OtherSchema.shape)를 덧붙입니다. 상위 타입이 객체 스키마가 아니면(교차 타입 별칭 등) z.intersection(BaseSchema, z.object({ ... }))가 됩니다. 입력에 선언되지 않은 상위 타입은 일반 z.object()에 주석을 붙입니다.
  • 인덱스 시그니처: 다른 속성과 함께 있는 [key: string]: V → .catchall(V)(추가 키를 검사하고 유지), 인덱스 시그니처만 있으면 z.record(z.string(), V). 파싱한 JSON 객체의 키는 모두 문자열이므로 키는 항상 z.string()입니다.
  • enum 선언: 문자열 enum → 값의 z.enum(), 숫자 또는 혼합 멤버(0 또는 직전 숫자부터 자동 증가) → z.literal()의 z.union(). const enum, declare enum도 같습니다. 1 << 2 같은 계산 값이 있는 enum은 전체를 z.unknown()으로 쓰고 주석을 붙입니다.
  • 선언 순서와 재귀: 입력 순서와 관계없이 의존하는 스키마를 먼저 출력합니다. 순환을 닫는 참조는 z.lazy(() => NameSchema)가 되고, 순환에 속한 타입은 원래 선언을 그대로 쓰고 z.ZodType<Name> 타입 주석을 붙입니다(Zod 문서의 재귀 타입 작성법). 출력은 TypeScript 5.9 strict 모드로 컴파일하고 Zod 3.25와 Zod 4에서 불러와 확인했습니다.

예시

다음 TypeScript를 입력하면:

interface Address {
street: string;
city: string;
zipCode?: string;
}

export interface User {
id: number;
name: string;
role: "admin" | "user" | "guest";
age?: number;
isActive: boolean;
tags: string[];
address: Address;
}

export type Status = "active" | "inactive" | "pending";

다음과 같이 생성됩니다:

import { z } from "zod";

export const AddressSchema = z.object({
street: z.string(),
city: z.string(),
zipCode: z.string().optional(),
});
export type Address = z.infer<typeof AddressSchema>;

export const UserSchema = z.object({
id: z.number(),
name: z.string(),
role: z.enum(["admin", "user", "guest"]),
age: z.number().optional(),
isActive: z.boolean(),
tags: z.array(z.string()),
address: AddressSchema,
});
export type User = z.infer<typeof UserSchema>;

export const StatusSchema = z.enum(["active", "inactive", "pending"]);
export type Status = z.infer<typeof StatusSchema>;

예시: 회원가입 폼

입력:

interface SignupForm {
email: string;
password: string;
nickname?: string;
referrer: string | null;
age?: number | undefined;
plan: "free" | "pro";
}

출력:

import { z } from "zod";

export const SignupFormSchema = z.object({
email: z.string(),
password: z.string(),
nickname: z.string().optional(),
referrer: z.union([z.string(), z.null()]),
age: z.union([z.number(), z.undefined()]).optional(),
plan: z.enum(["free", "pro"]),
});
export type SignupForm = z.infer<typeof SignupFormSchema>;

생성한 스키마로 zod 3.25에서 세 데이터를 검증한 결과:

SignupFormSchema.safeParse({ email: "not-an-email", password: "1", referrer: null, plan: "pro" })
// success: true  (타입은 맞음, 형식 규칙은 아직 없음)

SignupFormSchema.safeParse({ email: "a@example.com", password: "x", plan: "free" })
// referrer: Invalid input  (string | null은 키가 반드시 있어야 하며 생략할 수 없음)

SignupFormSchema.safeParse({ email: "a@example.com", password: "x", referrer: "ad", plan: "team" })
// plan: Invalid enum value. Expected 'free' | 'pro', received 'team'

토스페이먼츠 Payment 객체로 확인하기

토스페이먼츠 코어 API 문서의 Payment 객체에서 status는 READY, IN_PROGRESS, WAITING_FOR_DEPOSIT, DONE, CANCELED, PARTIAL_CANCELED, ABORTED, EXPIRED 중 하나이고, method와 approvedAt은 nullable · string으로 표시돼 있습니다. 문서의 필드 일부를 그대로 옮겨 적으면:

type PaymentStatus =
| "READY"
| "IN_PROGRESS"
| "WAITING_FOR_DEPOSIT"
| "DONE"
| "CANCELED"
| "PARTIAL_CANCELED"
| "ABORTED"
| "EXPIRED";

interface Payment {
paymentKey: string;
orderId: string;
orderName: string;
method: string | null;
totalAmount: number;
status: PaymentStatus;
requestedAt: string;
approvedAt: string | null;
}
import { z } from "zod";

export const PaymentStatusSchema = z.enum(["READY", "IN_PROGRESS", "WAITING_FOR_DEPOSIT", "DONE", "CANCELED", "PARTIAL_CANCELED", "ABORTED", "EXPIRED"]);
export type PaymentStatus = z.infer<typeof PaymentStatusSchema>;

export const PaymentSchema = z.object({
paymentKey: z.string(),
orderId: z.string(),
orderName: z.string(),
method: z.union([z.string(), z.null()]),
totalAmount: z.number(),
status: PaymentStatusSchema,
requestedAt: z.string(),
approvedAt: z.union([z.string(), z.null()]),
});
export type Payment = z.infer<typeof PaymentSchema>;

여러 줄에 걸친 유니언도 맨 앞의 |를 읽고 여덟 값을 하나의 z.enum()으로 묶습니다. 결제 대기 상태처럼 method와 approvedAt이 null인 데이터는 통과하고, status가 목록에 없는 PAID이면 실패합니다. approvedAt 키 자체가 빠진 데이터도 실패합니다. 문서의 nullable은 값이 null일 수 있다는 뜻일 뿐 키를 생략해도 된다는 뜻이 아니고, string | null로 만든 스키마도 키가 있어야 통과합니다.

Payment 객체에는 currency, mId 등 여기 적지 않은 필드가 더 있습니다. Zod는 스키마에 없는 키를 기본적으로 지우므로 검증은 통과하지만 parse() 결과에서는 빠집니다. 문서에 적힌 orderId 길이(6자 이상 64자 이하) 같은 제약은 타입에 없으니 .min(6).max(64)처럼 직접 추가하세요. 값은 이 페이지용 예시입니다.

null, undefined, optional의 차이

  • prop?: T는 .optional()이 됩니다. 키가 없어도 됩니다.
  • T | null은 z.union([T, z.null()]), 즉 T.nullable()과 같습니다. 키는 반드시 있어야 하고 값은 null일 수 있습니다. referrer가 없는 데이터는 실패합니다.
  • prop?: T | null은 z.union([T, z.null()]).optional()이 됩니다. 키가 없어도 되고 값이 null이어도 되므로 T.nullish()와 같습니다.

한글 속성 이름

속성 이름과 타입 이름은 TypeScript 식별자 규칙으로 읽으므로 한글을 그대로 쓸 수 있습니다. 따옴표 없는 한글 키가 있는 다음 interface에서는:

interface Member {
id: string;
이름: string;
"닉네임": string;
}
import { z } from "zod";

export const MemberSchema = z.object({
id: z.string(),
이름: z.string(),
"닉네임": z.string(),
});
export type Member = z.infer<typeof MemberSchema>;

이름은 그대로 속성 이름이 되고, 따옴표로 감싼 "닉네임"은 따옴표째 출력됩니다. 이름이 빠진 데이터는 검증에 실패합니다. 타입 이름도 한글로 쓸 수 있어 interface 회원은 회원Schema가 됩니다.

콜론을 빠뜨리면 그 속성을 건너뛰지 않고 위치와 함께 오류를 냅니다. 입력:

interface 회원 {
id: string;
이름 string;
}

상태 표시에 파싱 오류: 3행 3열: "이름" 뒤에 ":"가 없습니다.가 나오고 출력은 지워집니다. 열은 글자 단위로 셉니다. 그 밖의 구문 오류 본문은 영어이며 파서가 예상하지 못한 첫 토큰만 알려 줍니다. 닫는 중괄호가 없는 interface A { a: string는 Expected "}" got "", const 문만 있는 입력은 "interface 또는 type 선언을 찾을 수 없습니다."가 됩니다.

TypeScript로 표현할 수 없는 규칙 추가

TypeScript 타입에는 형식과 범위가 없어서 위의 첫 데이터는 잘못된 이메일과 한 글자 비밀번호로도 통과합니다. 생성 후 제약을 추가하세요:

export const SignupFormSchema = z.object({
email: z.string().email(),
password: z.string().min(8),
nickname: z.string().max(20).optional(),
referrer: z.string().nullable(),
age: z.number().int().min(13).optional(),
plan: z.enum(["free", "pro"]),
});

생성한 z.infer 타입을 유일한 정의로 두고 원래 interface를 지우면 둘이 어긋나지 않습니다.

제한 사항

선언은 TypeScript 컴파일러가 아니라 자체 소형 파서로 읽기 때문에 다른 파일의 타입을 해석하지 않고 타입 검사도 하지 않습니다. 사용하기 전에 다음을 확인하세요.

  • 선언되지 않은 이름은 z.unknown()이 됩니다. Date나 import한 타입처럼 입력에 선언이 없는 타입은 z.unknown() /* Name */로 출력되니 z.date()나 해당 스키마로 바꾸세요. 선언되지 않은 상위 타입은 일반 z.object()에 주석 /* extends Name: not declared in the input */을 붙입니다.
  • enum은 값을 복사합니다. 스키마는 enum의 값("RED", 0)을 검사하며 런타임 enum 객체를 쓰지 않습니다. enum을 import할 수 있다면 z.nativeEnum(Color)(Zod 3)나 z.enum(Color)(Zod 4)도 같은 결과입니다.
  • 인덱스 시그니처의 키는 항상 z.string()입니다. .catchall()과 함께 쓰면 선언된 속성도 자기 스키마에 맞아야 합니다.
  • 리터럴 키의 Record(Record<"read" | "write", boolean>)는 z.record(z.enum(["read", "write"]), z.boolean())가 됩니다. Zod 4는 TypeScript처럼 두 키를 모두 요구하고, Zod 3는 하나만 있어도 통과시킵니다.
  • 이름의 유니코드 이스케이프는 해석하지 않습니다. \u0061: string은 a가 아니라 u0061이라는 속성이 됩니다.
  • 전각 문자는 콜론만 반각으로 읽습니다. 전각 물음표 등은 알 수 없는 문자로 건너뛰므로 age?: number는 선택적 속성이 되지 않고 age: z.number()가 됩니다.
  • 변환하지 않는 것: 제네릭 타입 매개변수, class, 메서드, get / set 접근자, 호출 시그니처와 생성자 시그니처(건너뜀), 매핑된 타입과 조건부 타입, keyof, typeof. 템플릿 리터럴 타입은 z.string()이 됩니다.

FAQ

어떤 TypeScript 구문을 지원하나요?

interface와 type alias 선언을 지원하며, 기본 타입(string, number, boolean, null, undefined, any, unknown), 선택적 속성(?), 유니언 타입(A | B), 문자열 열거형(리터럴 유니언), enum 선언, extends, 인덱스 시그니처, 재귀 타입, 배열(T[], Array<T>), 인라인 중첩 객체, 선언된 타입 간의 상호 참조, Partial<T>·Record<K, V>·Array<T>·Promise<T> 등의 유틸리티 타입을 지원합니다.

타입 간의 상호 참조는 어떻게 처리되나요?

입력에 여러 interface 또는 type alias가 선언된 경우, 선언된 타입 이름에 대한 참조는 해당 Schema 상수로 변환됩니다. 예를 들어 Address 타입의 필드는 출력에서 AddressSchema가 됩니다. 입력에서 선언되지 않은 타입은 z.unknown()(주석 포함)이 됩니다.

생성된 스키마는 어떤 Zod 버전과 호환되나요?

출력은 Zod 3와 Zod 4 모두에 있는 z.object(), z.string(), z.union(), z.enum(), z.array(), .optional(), z.literal(), z.record(키, 값), .extend(), .shape, .catchall(), z.lazy(), z.ZodType, z.infer<> 등의 API만 사용합니다. Zod 4는 값만 받는 z.record()를 허용하지 않으므로 Record에는 항상 키 스키마를 씁니다. Promise<T>에서 생성되는 z.promise()는 Zod 4에서 사용 중단(deprecated) 표시가 있습니다.

문자열 유니언 타입은 어떻게 변환되나요?

문자열 리터럴의 유니언(예: "admin" | "user" | "guest")은 간결하게 z.enum(["admin", "user", "guest"])로 자동 변환됩니다. 혼합 유니언(예: string | null)은 z.union([z.string(), z.null()])을 사용합니다.

TypeScript class나 제네릭 타입 정의를 변환할 수 있나요?

아니요. class 선언은 건너뛰므로 class만 있는 입력에는 "interface 또는 type 선언을 찾을 수 없습니다."가 표시됩니다. 선언한 타입 자신의 타입 매개변수는 펼치지 않습니다. interface Box<T> { value: T }의 value는 z.unknown() /* T */가 됩니다. 구체적인 타입에 적용된 유틸리티 타입(Array<string>, Record<string, number>)은 변환됩니다.

코드가 서버로 전송되나요?

아니요. 파서와 Zod 생성기는 지금 보고 있는 브라우저 탭 안에서 실행되며, 코드를 서버로 보내지도 브라우저 저장소에 저장하지도 않습니다. 페이지 통계는 입력을 고친 뒤 포커스를 옮길 때와 예시를 누를 때 사용 이벤트(도구 이름과 동작 generate)만 기록하며, 코드 내용은 담지 않습니다.