.ts · text/typescript

Zod 스키마: 런타임 JSON 검증 스키마

Zod 스키마는 런타임 JSON 검증(`z.object`, `z.array`, `.optional()`)과 `z.infer<typeof schema>`를 통한 정적 TypeScript 타입 추론을 결합합니다.

빠른 답변: Zod 스키마는 런타임 JSON 검증(`z.object`, `z.array`, `.optional()`)과 `z.infer<typeof schema>`를 통한 정적 TypeScript 타입 추론을 결합합니다. 런타임 API 경계 검증, tRPC/React Hook Form 스키마 및 단일 소스 TypeScript 타입 추론.

구조 유형타입 코드
사람 가독성높음
중첩 지원지원
LLM 토큰 효율보통
파일 확장자.ts
MIME 유형text/typescript
추천 용도런타임 API 경계 검증, tRPC/React Hook Form 스키마 및 단일 소스 TypeScript 타입 추론.

장점

  • 실행 시점에 비신뢰 JSON을 검증하면서 정적 TypeScript 타입까지 동시에 도출
  • 누락된 키, 잘못된 원시 타입 및 API 스펙 드리프트를 명확한 오류로 조기 포착
  • 미정의 추가 키를 차단하는 엄격한 객체 검사(.strict()) 지원

단점 및 주의사항

  • 컴파일 시 지워지는 순수 TypeScript 인터페이스 대비 약간의 런타임 번들 증가
  • 깊은 재귀 스키마에는 명시적인 수동 타입 힌트가 필요할 수 있음
  • 엄격 객체 모드는 API에 새 필드가 추가될 때 하위 호환 오류를 낼 수 있음

참고 자료

Zod 스키마 로컬 변환 및 정리 도구

관련 엔지니어링 가이드

Zod 스키마 자주 묻는 질문

일반 TypeScript 인터페이스 대신 Zod 스키마를 생성하는 이유는 무엇인가요?

TypeScript 타입은 런타임에 사라집니다. Zod는 실제 수신 JSON 응답을 실행 시 검증하고 z.infer<typeof schema>를 자동으로 내보냅니다.

JSON to Zod에서 '엄격한 z.strictObject()' 옵션은 무슨 역할을 하나요?

생성된 z.object(...)에 .strict()를 적용해 스키마에 정의되지 않은 알 수 없는 키가 들어오면 조용히 제거하지 않고 오류를 발생시킵니다.

중첩된 JSON 객체나 혼합 타입 배열도 자동으로 처리되나요?

네. 중첩 구조에 맞춰 z.object(), z.array(), z.union() 및 .nullable() / .optional() 수식어를 깔끔하게 생성합니다.