Zod > Zod은 정적 타입 추론을 제공하는 TypeScript 중심 스키마 검증 라이브러리입니다. 이 문서는 Zod 4의 기능, API, 사용 패턴을 포괄적으로 다룹니다.

Basic usage - Basic usage: 스키마 정의, 데이터 파싱, 오류 처리, 타입 추론을 다루는 기본 안내서 - Defining a schema - Parsing data - Handling errors - Inferring types

Ecosystem - Ecosystem: Zod 생태계 전반의 통합, 도구, 커뮤니티 자료 개요 - Resources - API Libraries - Form Integrations - Zod to X - X to Zod - Mocking Libraries - Powered by Zod - Zod Utilities

Customizing errors - Customizing errors: 검증 오류 메시지와 처리 패턴을 맞춤화하는 가이드 - The error param - Per-parse error customization - Include input in issues - Global error customization - Internationalization - Locales - Error precedence

Formatting errors - Formatting errors: Zod 오류를 포맷하고 표시하기 위한 유틸리티 - z.treeifyError() - z.prettifyError() - z.formatError() - z.flattenError()

Intro - Intro: Zod 소개 - 정적 타입 추론을 갖춘 TypeScript 중심 스키마 검증 라이브러리 - Introduction - Features - Installation - Requirements - “strict” - Ecosystem - Sponsors - Platinum - Gold - Silver - Bronze

JSON Schema - JSON Schema: Zod 스키마를 JSON Schema로 변환하는 방법 - z.fromJSONSchema() - z.toJSONSchema() - io - target - metadata - unrepresentable - cycles - reused - override - Conversion - String formats - Numeric types - Object schemas - File schemas - Nullability - Registries

For library authors - For library authors: Zod와 통합하려는 라이브러리 저자를 위한 지침과 모범 사례 - Do I need to depend on Zod? - How to configure peer dependencies? - How to support Zod 4? - Do I need to publish a new major version? - How to support Zod 3 and Zod 4 simultaneously? - How to support Zod and Zod Mini simultaneously? - How to accept user-defined schemas?

Metadata and registries - Metadata and registries: Zod 스키마에 메타데이터를 부착하고 조작하는 방법 - Registries - .register() - Metadata - z.globalRegistry - .meta() - .describe() - Custom registries - Referencing inferred types - Constraining schema types

Joining Clerk as an OSS Fellow to work on Zod 4 - Joining Clerk as an OSS Fellow to work on Zod 4: Clerk OSS 펠로우십과 Zod 4의 향후 계획 발표

Zod > Zod은 정적 타입 추론을 갖춘 TypeScript 중심 스키마 검증 라이브러리입니다. 이 문서는 Zod 4의 기능, API, 사용 패턴을 포괄적으로 다룹니다. ## 스키마 정의 - 스키마 정의: 모든 Zod 스키마 유형, 메서드, 검증 기능에 대한 전체 API 참조 - 원시 타입 - 강제 변환 - 리터럴 - 문자열 - 문자열 형식 - 이메일 - UUID - URL - ISO 날짜시 - ISO 날짜 - ISO 시간 - IP 주소 - IP 블록(CIDR) - MAC 주소 - JWT - 해시 - 사용자 정의 형식 - 템플릿 리터럴 - 숫자 - 정수 - BigInt - 불리언 - 날짜 - 열거형 - .enum - .exclude() - .extract() - Stringbool - 옵셔널 - 널 가능 - Nullish - Unknown - Never - 객체 - z.strictObject - z.looseObject - .catchall() - .shape - .keyof() - .extend() - .safeExtend() - .pick() - .omit() - .partial() - .required() - 재귀 객체 - 순환 오류 - 배열 - 튜플 - 유니온 - 배타적 유니온 (XOR) - 판별 유니온 - 교차 - 레코드 - z.record - z.partialRecord - z.looseRecord - 맵 - 셋 - 파일 - 프로미스 - Instanceof - Property - Refinements - .refine() - error - abort - path - when - .superRefine() - .check() - 코덱 - 파이프 - 변환 - .transform() - .preprocess() - 기본값 - 사전 설정값 - Catch - 브랜디드 타입 - 읽기 전용 - JSON - 함수 - 사용자 정의 - 적용 ## 기본 사용법 - 기본 사용법: 스키마 정의, 데이터 파싱, 오류 처리, 타입 추론을 다루는 기본 가이드 - 스키마 정의 - 데이터 파싱 - 오류 처리 - 타입 추론 ## 코덱 - 코덱: 인코드 및 디코드를 지원하는 양방향 변환 - 조합 가능성 - 타입 안전 입력 - 비동기 및 안전한 변형 - 인코딩 작동 방식 - 코덱 - 파이프 - Refinements - 기본값 및 사전 설정값 - Catch - Stringbool - 변환 - 유용한 코덱 - stringToNumber - stringToInt - stringToBigInt - numberToBigInt - isoDatetimeToDate - epochSecondsToDate - epochMillisToDate - json(schema) - utf8ToBytes - bytesToUtf8 - base64ToBytes - base64urlToBytes - hexToBytes - stringToURL - stringToHttpURL - uriComponent ## 에코시스템 - 에코시스템: 통합, 도구, 커뮤니티 리소스를 포함한 Zod 생태계 개요 - 리소스 - API 라이브러리 - 폼 통합 - Zod에서 다른 형식으로 - 다른 형식에서 Zod로 - 모킹 라이브러리 - Zod 기반 - Zod 유틸리티 ## 오류 커스터마이징 - 오류 맞춤화: 검증 오류 메시지와 처리 패턴 커스터마이징 가이드 - error 파라미터 - 파싱별 오류 커스터마이징 - 입력 포함 - 전역 오류 커스터마이징 - 국제화 - 로케일 - 오류 우선순위 ## 오류 형식화 - 오류 형식화: Zod 오류를 형식화하고 표시하는 유틸리티 - z.treeifyError() - z.prettifyError() - z.formatError() - z.flattenError() ## 소개 - 소개: 정적 타입 추론을 갖춘 TypeScript 중심 스키마 검증 라이브러리인 Zod 소개 - 소개글 - 기능 - 설치 - 요구사항 - “strict” - 에코시스템 - 후원사 - 플래티넘 - 골드 - 실버 - 브론즈 ## JSON 스키마 - JSON 스키마: Zod 스키마를 JSON Schema로 변환하는 방법 - z.fromJSONSchema() - z.toJSONSchema() - io - 타겟 - 메타데이터 - 표현 불가능 항목 - 순환 - 재사용 - 오버라이드 - 변환 - 문자열 형식 - 숫자 타입 - 객체 스키마 - 파일 스키마 - 널 가능성 - 레지스트리 ## 라이브러리 저자용 - 라이브러리 저자용: Zod와 통합하는 라이브러리 저자를 위한 가이드와 모범 사례 - Zod를 의존해야 하나요? - 피어 의존성 구성 방법 - Zod 4 지원 방법 - 새 메이저 버전을 배포해야 하나요? - Zod 3과 Zod 4를 동시에 지원하는 방법 - Zod와 Zod Mini를 동시에 지원하는 방법 - 사용자 정의 스키마를 수용하는 방법 ## 메타데이터 및 레지스트리 - 메타데이터 및 레지스트리: Zod 스키마에 메타데이터를 첨부하고 조작하기 - 레지스트리 - .register() - 메타데이터 - z.globalRegistry - .meta() - .describe() - 사용자 정의 레지스트리 - 추론된 타입 참조 - 스키마 타입 제약 ## Zod 4 작업을 위한 Clerk OSS 펠로우 참여 - Zod 4 작업을 위한 Clerk OSS 펠로우 참여: Clerk OSS Fellowship 및 Zod 4 예정 내용 발표 - 다음은: Zod 4 - Zod의 현재 자금 스토리 - Clerk 펠로우십 - OSS, 자금 모델, 실험 ## Zod 코어 - Zod 코어: 사용자 정의 구현을 위한 최소한의 핵심 기능을 제공하는 Zod Core 패키지 - 스키마 - 내부 - 파싱 - 체크 - 오류 - 이슈 ## Zod Mini - Zod Mini: 트리 쉐이킹 가능한 Zod Mini - 트리 쉐이킹 - Zod Mini 사용 시기/비사용 시기 - 개발자 경험 - 백엔드 개발 - 인터넷 속도 - ZodMiniType - .parse - .check() - .register() - .brand() - .clone(def) - 기본 로케일 없음 ## Zod - Zod: Zod 라이브러리의 내부 구조 및 구성 요소 ## 마이그레이션 가이드 - 마이그레이션 가이드: Zod 3에서 Zod 4로 업그레이드하기 위한 전체 변경 로그 및 마이그레이션 안내 - 오류 커스터마이징 - message 인수 폐지 - invalid_type_error 및 required_error 제거 - errorMap 제거 - ZodError - 이슈 형식 업데이트 - 오류 맵 우선순위 변경 - .format() 폐기 - .flatten() 폐기 - .formErrors 제거 - .addIssue() 및 .addIssues() 폐기 - z.number() - 무한값 없음 - .safe()가 더 이상 부동 소수점 허용 안 함 - .int()가 안전 정수만 허용 - z.string() 업데이트 - .email() 등 폐기 - .uuid() 엄격해짐 - .base64url() 패딩 제거 - z.string().ip() 제거 - z.string().ipv6() 업데이트 - z.string().cidr() 제거 - z.coerce 업데이트 - .default() 업데이트 - z.object() - 옵셔널 필드 내에 기본값 적용 - .strict() 및 .passthrough() 폐기 - .strip() 폐기 - .nonstrict() 제거 - .deepPartial() 제거 - z.unknown() 선택성 변경 - .merge() 폐기 - z.nativeEnum() 폐기 - z.array() - .nonempty() 타입 변경 - z.promise() 폐기 - z.function() - .implementAsync() 추가 - .refine() - 타입 술어 무시 - ctx.path 제거 - 두 번째 인수로 함수 제거 - z.ostring() 등 제거 - z.literal() - 심볼 지원 제거 - 정적 .create() 팩토리 제거 - z.record() - 단일 인수 사용 제거 - 열거형 지원 개선 - z.intersection() - 병합 충돌 시 Error 발생 - 내부 변경 - 제네릭 업데이트 - z.core 추가 - ._def 이동 - ZodEffects 제거 - ZodTransform 추가 - ZodPreprocess 제거 - ZodBranded 제거 ## 릴리스 노트 - 릴리스 노트: 성능 개선 및 브레이킹 체인지를 포함한 Zod 4 릴리스 노트 및 신규 기능 - 버전 관리 - 왜 새로운 메이저 버전인가? - 벤치마크 - 문자열 파싱 14배 빠름 - 배열 파싱 7배 빠름 - 객체 파싱 6.5배 빠름 - tsc 인스턴스화 100배 감소 - 코어 번들 크기 2배 감소 - Zod Mini 소개 - 코어 번들 크기 6.6배 감소 - 메타데이터 - 글로벌 레지스트리 - .meta() - JSON Schema 변환 - 재귀 객체 - 파일 스키마 - 국제화 - 오류 예쁘게 출력하기 - 최상위 문자열 형식 - 사용자 정의 이메일 정규식 - 템플릿 리터럴 타입 - 숫자 형식 - Stringbool - 간소화된 오류 맞춤화 - 업그레이드된 z.discriminatedUnion() - z.literal()의 다중 값 - 스키마 내부에서 실행되는 Refinements - .overwrite() - 확장 가능한 기반: zod/v4/core - 마무리 ## 버전 관리 - 버전 관리: Zod 4의 버전 전략 및 호환성 정보 - 업데이트 — 2025년 7월 8일 - Zod 4의 버전 관리 - 왜? - 라이브러리가 v3와 v4를 동시에 지원할 수 없는 이유 --- 이 문서는 TypeScript 중심 스키마 검증 라이브러리인 Zod v4를 다룹니다. 위 URL을 통해 스키마 정의, 검증, 오류 처리, 고급 패턴에 대한 자세한 정보를 확인하세요.

섹션 제목: “Zod > Zod은 정적 타입 추론을 갖춘 TypeScript 중심 스키마 검증 라이브러리입니다. 이 문서는 Zod 4의 기능, API, 사용 패턴을 포괄적으로 다룹니다. ## 스키마 정의 - 스키마 정의: 모든 Zod 스키마 유형, 메서드, 검증 기능에 대한 전체 API 참조 - 원시 타입 - 강제 변환 - 리터럴 - 문자열 - 문자열 형식 - 이메일 - UUID - URL - ISO 날짜시 - ISO 날짜 - ISO 시간 - IP 주소 - IP 블록(CIDR) - MAC 주소 - JWT - 해시 - 사용자 정의 형식 - 템플릿 리터럴 - 숫자 - 정수 - BigInt - 불리언 - 날짜 - 열거형 - .enum - .exclude() - .extract() - Stringbool - 옵셔널 - 널 가능 - Nullish - Unknown - Never - 객체 - z.strictObject - z.looseObject - .catchall() - .shape - .keyof() - .extend() - .safeExtend() - .pick() - .omit() - .partial() - .required() - 재귀 객체 - 순환 오류 - 배열 - 튜플 - 유니온 - 배타적 유니온 (XOR) - 판별 유니온 - 교차 - 레코드 - z.record - z.partialRecord - z.looseRecord - 맵 - 셋 - 파일 - 프로미스 - Instanceof - Property - Refinements - .refine() - error - abort - path - when - .superRefine() - .check() - 코덱 - 파이프 - 변환 - .transform() - .preprocess() - 기본값 - 사전 설정값 - Catch - 브랜디드 타입 - 읽기 전용 - JSON - 함수 - 사용자 정의 - 적용 ## 기본 사용법 - 기본 사용법: 스키마 정의, 데이터 파싱, 오류 처리, 타입 추론을 다루는 기본 가이드 - 스키마 정의 - 데이터 파싱 - 오류 처리 - 타입 추론 ## 코덱 - 코덱: 인코드 및 디코드를 지원하는 양방향 변환 - 조합 가능성 - 타입 안전 입력 - 비동기 및 안전한 변형 - 인코딩 작동 방식 - 코덱 - 파이프 - Refinements - 기본값 및 사전 설정값 - Catch - Stringbool - 변환 - 유용한 코덱 - stringToNumber - stringToInt - stringToBigInt - numberToBigInt - isoDatetimeToDate - epochSecondsToDate - epochMillisToDate - json(schema) - utf8ToBytes - bytesToUtf8 - base64ToBytes - base64urlToBytes - hexToBytes - stringToURL - stringToHttpURL - uriComponent ## 에코시스템 - 에코시스템: 통합, 도구, 커뮤니티 리소스를 포함한 Zod 생태계 개요 - 리소스 - API 라이브러리 - 폼 통합 - Zod에서 다른 형식으로 - 다른 형식에서 Zod로 - 모킹 라이브러리 - Zod 기반 - Zod 유틸리티 ## 오류 커스터마이징 - 오류 맞춤화: 검증 오류 메시지와 처리 패턴 커스터마이징 가이드 - error 파라미터 - 파싱별 오류 커스터마이징 - 입력 포함 - 전역 오류 커스터마이징 - 국제화 - 로케일 - 오류 우선순위 ## 오류 형식화 - 오류 형식화: Zod 오류를 형식화하고 표시하는 유틸리티 - z.treeifyError() - z.prettifyError() - z.formatError() - z.flattenError() ## 소개 - 소개: 정적 타입 추론을 갖춘 TypeScript 중심 스키마 검증 라이브러리인 Zod 소개 - 소개글 - 기능 - 설치 - 요구사항 - “strict” - 에코시스템 - 후원사 - 플래티넘 - 골드 - 실버 - 브론즈 ## JSON 스키마 - JSON 스키마: Zod 스키마를 JSON Schema로 변환하는 방법 - z.fromJSONSchema() - z.toJSONSchema() - io - 타겟 - 메타데이터 - 표현 불가능 항목 - 순환 - 재사용 - 오버라이드 - 변환 - 문자열 형식 - 숫자 타입 - 객체 스키마 - 파일 스키마 - 널 가능성 - 레지스트리 ## 라이브러리 저자용 - 라이브러리 저자용: Zod와 통합하는 라이브러리 저자를 위한 가이드와 모범 사례 - Zod를 의존해야 하나요? - 피어 의존성 구성 방법 - Zod 4 지원 방법 - 새 메이저 버전을 배포해야 하나요? - Zod 3과 Zod 4를 동시에 지원하는 방법 - Zod와 Zod Mini를 동시에 지원하는 방법 - 사용자 정의 스키마를 수용하는 방법 ## 메타데이터 및 레지스트리 - 메타데이터 및 레지스트리: Zod 스키마에 메타데이터를 첨부하고 조작하기 - 레지스트리 - .register() - 메타데이터 - z.globalRegistry - .meta() - .describe() - 사용자 정의 레지스트리 - 추론된 타입 참조 - 스키마 타입 제약 ## Zod 4 작업을 위한 Clerk OSS 펠로우 참여 - Zod 4 작업을 위한 Clerk OSS 펠로우 참여: Clerk OSS Fellowship 및 Zod 4 예정 내용 발표 - 다음은: Zod 4 - Zod의 현재 자금 스토리 - Clerk 펠로우십 - OSS, 자금 모델, 실험 ## Zod 코어 - Zod 코어: 사용자 정의 구현을 위한 최소한의 핵심 기능을 제공하는 Zod Core 패키지 - 스키마 - 내부 - 파싱 - 체크 - 오류 - 이슈 ## Zod Mini - Zod Mini: 트리 쉐이킹 가능한 Zod Mini - 트리 쉐이킹 - Zod Mini 사용 시기/비사용 시기 - 개발자 경험 - 백엔드 개발 - 인터넷 속도 - ZodMiniType - .parse - .check() - .register() - .brand() - .clone(def) - 기본 로케일 없음 ## Zod - Zod: Zod 라이브러리의 내부 구조 및 구성 요소 ## 마이그레이션 가이드 - 마이그레이션 가이드: Zod 3에서 Zod 4로 업그레이드하기 위한 전체 변경 로그 및 마이그레이션 안내 - 오류 커스터마이징 - message 인수 폐지 - invalid_type_error 및 required_error 제거 - errorMap 제거 - ZodError - 이슈 형식 업데이트 - 오류 맵 우선순위 변경 - .format() 폐기 - .flatten() 폐기 - .formErrors 제거 - .addIssue() 및 .addIssues() 폐기 - z.number() - 무한값 없음 - .safe()가 더 이상 부동 소수점 허용 안 함 - .int()가 안전 정수만 허용 - z.string() 업데이트 - .email() 등 폐기 - .uuid() 엄격해짐 - .base64url() 패딩 제거 - z.string().ip() 제거 - z.string().ipv6() 업데이트 - z.string().cidr() 제거 - z.coerce 업데이트 - .default() 업데이트 - z.object() - 옵셔널 필드 내에 기본값 적용 - .strict() 및 .passthrough() 폐기 - .strip() 폐기 - .nonstrict() 제거 - .deepPartial() 제거 - z.unknown() 선택성 변경 - .merge() 폐기 - z.nativeEnum() 폐기 - z.array() - .nonempty() 타입 변경 - z.promise() 폐기 - z.function() - .implementAsync() 추가 - .refine() - 타입 술어 무시 - ctx.path 제거 - 두 번째 인수로 함수 제거 - z.ostring() 등 제거 - z.literal() - 심볼 지원 제거 - 정적 .create() 팩토리 제거 - z.record() - 단일 인수 사용 제거 - 열거형 지원 개선 - z.intersection() - 병합 충돌 시 Error 발생 - 내부 변경 - 제네릭 업데이트 - z.core 추가 - ._def 이동 - ZodEffects 제거 - ZodTransform 추가 - ZodPreprocess 제거 - ZodBranded 제거 ## 릴리스 노트 - 릴리스 노트: 성능 개선 및 브레이킹 체인지를 포함한 Zod 4 릴리스 노트 및 신규 기능 - 버전 관리 - 왜 새로운 메이저 버전인가? - 벤치마크 - 문자열 파싱 14배 빠름 - 배열 파싱 7배 빠름 - 객체 파싱 6.5배 빠름 - tsc 인스턴스화 100배 감소 - 코어 번들 크기 2배 감소 - Zod Mini 소개 - 코어 번들 크기 6.6배 감소 - 메타데이터 - 글로벌 레지스트리 - .meta() - JSON Schema 변환 - 재귀 객체 - 파일 스키마 - 국제화 - 오류 예쁘게 출력하기 - 최상위 문자열 형식 - 사용자 정의 이메일 정규식 - 템플릿 리터럴 타입 - 숫자 형식 - Stringbool - 간소화된 오류 맞춤화 - 업그레이드된 z.discriminatedUnion() - z.literal()의 다중 값 - 스키마 내부에서 실행되는 Refinements - .overwrite() - 확장 가능한 기반: zod/v4/core - 마무리 ## 버전 관리 - 버전 관리: Zod 4의 버전 전략 및 호환성 정보 - 업데이트 — 2025년 7월 8일 - Zod 4의 버전 관리 - 왜? - 라이브러리가 v3와 v4를 동시에 지원할 수 없는 이유 --- 이 문서는 TypeScript 중심 스키마 검증 라이브러리인 Zod v4를 다룹니다. 위 URL을 통해 스키마 정의, 검증, 오류 처리, 고급 패턴에 대한 자세한 정보를 확인하세요.”