Zod 4 릴리즈

(zod.dev)

1P by GN⁺ 3일전 | ★ favorite | 댓글 1개

스키마 선언 및 유효성 검사 라이브러리인 Zod의 버전 4 릴리즈. 주요 성능 향상과 장기 요청된 기능을 포함해 안정버전 출시
속도와 번들 크기에서 큰 개선이 이루어졌으며, 새로운 미니 버전(v4-mini)은 번들 크기를 대폭 줄임
새로운 메타데이터 레지스트리와 JSON Schema 변환, 그리고 재귀 타입 추론 기능이 추가됨
에러 메시지 커스터마이즈와 다국어 로케일 시스템 등 개발자 경험이 강화됨
향후 라이브러리 구축에 활용할 수 있는 코어 서브패키지 도입 등으로 확장성이 더욱 높아짐

Zod 4 소개

주요 출시에 대한 안내

1년간의 활발한 개발을 거쳐 Zod 4가 안정 버전으로 출시됨
Clerk의 OSS Fellowship 지원을 받아 개발 진행됨
현재 Zod 3와 병행 배포되어, Zod 4로의 점진적 마이그레이션이 쉬워짐
일부 파괴적 변경점에 대한 상세 안내는 Migration guide에서 확인 가능함

성장 배경

2021년 출시된 Zod 3 대비 Zod 4는 GitHub 스타 수와 주간 다운로드 수가 기하급수적으로 성장함
Zod 4는 훨씬 빠르고, 슬림하며, 타입스크립트 컴파일러 효율이 개선됨
장기적으로 요청이 많았던 9가지 주요 이슈가 해결됨

벤치마크 및 성능

속도 향상:
- 문자열 파싱: 14.71배 빠른 결과
- 배열 파싱: 7.43배 빠름
- 객체 파싱(safeParse): 6.5배 빠름
리포에서 직접 벤치마크를 수행할 수 있는 스크립트 제공
개선된 제네릭 구조로 인해 .extend(), .omit() 등의 메서드 체이닝 시 컴파일 성능이 10배 향상됨
대규모 스키마 및 코드베이스에서 TypeScript 컴파일 속도가 크게 개선됨

번들 크기와 Zod Mini

기본 번들 크기가 57% 감소해, v4는 v3 대비 2.3배 작은 크기 제공
zod/v4-mini는 함수 기반의 트리-쉐이크 가능한 API 제공, 번들 크기를 85%까지 줄임
core와 v4-mini의 API 차이는 공식 문서에서 상세히 정리됨
번들러에서 사용하지 않는 메서드를 쉽게 제거할 수 있도록 구조 설계됨

메타데이터 레지스트리와 JSON Schema 지원

typed metadata를 스키마에 강타입으로 등록 및 관리 가능
글로벌 레지스트리(z.globalRegistry)에서 JSON Schema 호환 메타데이터 처리 및 자동 포함 기능 제공
.meta(), .describe()를 통해 스키마 문서화 용이
.toJSONSchema()로 스키마를 JSON Schema 형식으로 변환 가능, 메타데이터 자동 반영

재귀 타입 자동 추론

재귀 객체 타입과 상호 재귀 타입을 별도의 타입 캐스팅 없이 자연스럽게 정의 및 추론 가능
기존 Zod 3 패턴보다 사용성이 크게 향상됨
재귀·상호재귀 타입에서도 모든 스키마 메서드 기능 사용 가능

파일 타입 및 검증 기능

새로운 file() 타입으로 File 인스턴스 검증 가능
파일 크기(min, max)와 MIME 타입 등 다양한 파일 제약조건 검증 제공

에러 메시지 및 로케일 시스템

글로벌 로케일 API(z.locales)로 에러 메시지의 다국어 지원 가능
공식 z.prettifyError 함수로 사용자 친화적인 에러 포맷팅 지원

포맷 함수 및 템플릿 리터럴

기존 문자열 포맷(email 등)은 상위 레벨 함수로 승격되어 가독성과 트리 쉐이킹이 개선됨
다양한 이메일 정규식 옵션 제공, 다양한 검증 요구 사항 충족
템플릿 리터럴 타입 지원: 타입 시스템에서 표현 가능한 문자열 패턴 및 복잡한 조합 쉽게 구현

새로 추가된 숫자 및 bigint 포맷

고정 폭의 정수, 부동소수점 타입 (int32, uint64 등) 지원
안전한 범위 내에서 자동으로 최소/최대 제약조건이 추가된 스키마 생성 가능

z.stringbool 소개

문자열 기반 불리언 파싱(yes, no 등) 가능, 환경변수 스타일 파싱도 지원
truthy/falsy 값은 커스터마이즈 가능

에러 커스터마이즈 API 통합

단일화된 error 파라미터를 통해 에러 메시지와 처리 로직 구조 정돈
기존의 여러 에러 관련 API (message, invalid_type_error, errorMap)는 deprecated

기타 핵심 개선점

판별 유니온(discriminated unions) 이 다양한 스키마, 중첩, 조합을 지원
.literal()이 동시에 여러 값 허용
.refine() 등 커스텀 검증이 더욱 직관적으로 통합됨
transform 관련 .overwrite()로 변환 타입 변경 없이 후처리 가능

라이브러리 확장성 및 새로운 코어

zod/v4/core로 핵심 기능이 별도 서브패키지로 분리, 다양한 라이브러리·플랫폼 통합/확장 가능
라이브러리 제작자를 위한 가이드 문서와 확장 예시 제공

마무리

Zod 4는 타입 안정성, 성능, 확장성, 개발자 경험 모두를 크게 개선한 자료 검증 라이브러리로 자리 잡음
향후 추가적인 설계 포스트 및 업데이트가 예고됨
기존 사용자와 라이브러리 제작자 모두를 위한 폭넓은 지원 준비됨

행복한 파싱 경험 제공
— Colin McDonnell @colinhacks

▲

GN⁺ 3일전 [-]

Hacker News 의견

저자 본인 의견 공유 요청 및 버전 관리 방식에 대한 상세한 설명 제공, npm이 Zod과 같은 상황을 처리하기에 적합하지 않음 강조, 수많은 라이브러리가 Zod 인터페이스/클래스를 직접 가져와 사용하는 점 언급, 만약 Zod이 주요 버전 변경될 때 이들 라이브러리가 모두 동시 대응해야 하며 버전 폭주 현상 발생 가능성 예상, Go와 유사하게 파괴적 변경은 새 서브패스 경로 추가 방식 사용, 타입스크립트 환경에서는 zod@^3.25.0 하나로 "zod/v3"·"zod/v4"를 동시에 지원할 수 있음 설명, 최종 이용자에게 점진적 업그레이드 경로 제공함
- Zod에 대한 기여에 감사의 인사와, 특히 tsc 성능 향상과 discriminated unions 개선에 기대감 표출, 버전 관리 방식을 충분히 이해하지만, 트랜스티브 종속성 충돌 걱정이 없는 자신 같은 사용자를 위해 4.0.0 패키지 형태로 단일 제공하는 것도 좋을 것 같다고 제안, "zod/v4"로 import를 변경해야 하는 점이 코드상 잡음 유발 및 IDE 자동 import 충돌 등 추가적인 번거로움 발생 예상, 그러나 전체적으로 매우 유망한 업그레이드라고 생각하고 감사 표시
- 모바일로 기사 확인 중이어서 미처 못 봤다면 양해 구함, .optional()과 관련한 최대 불편 사항이 이번 9/10 상위 이슈 해결에 포함됐는지 질문, Zod이 매우 뛰어나서 불편해도 계속 사용하는 중임을 언급, 훌륭한 라이브러리임에 감사 표함
- 많은 수작업 해킹 코드를 Zod 신버전에서 제거할 수 있게 되어 감사, 직접 타이포를 줄일 목적으로 zod-key-parser를 활용 중인데 이런 기능이 기본적으로 라이브러리에 들어있지 않은 이유나 범위 밖으로 보는지, 혹은 아직 구현하지 않았는지 궁금, 관련 오픈 토론들 공유
- 단기적인 고통을 최소화하는 방법이 종종 최선임을 강조, 파이썬 2/3 마이그레이션 대혼란 기억 사례 언급
- 재귀 타입과 discriminated union 형태를 동시에 사용(예: XML을 JSON 안에 포함하는 상황)에 상당한 어려움을 겪었던 경험 공유, 이번 업데이트로 상황이 많이 나아지길 희망
zod/v4-mini import에 의구심 가진다는 의견 표현, 이로 인해 오히려 번들 사이즈가 늘어날 것이라 추측, 공식문서에서 "zod/v4가 대부분의 경우 추천"한다고 해서 앱 개발자는 zod/v4를 쓰지만, 라이브러리 작성자가 번들 사이즈 절감 위해 zod/v4-mini도 추가하면 둘 다 번들에 포함되어 중복 발생 우려, 만약 zod/v4가 zod/v4-mini 래퍼라면 이런 문제 줄어들 수 있는지 질문
Zod 4의 마이그레이션을 용이하게 하려고 v3와 v4가 zod@3.25에서 동시 제공되는 방식 도입, 이런 구조가 npm의 의존성 관리 한계와 맞물려서 v4가 v3처럼 보이도록 해야 했다고 비판, npm의 peer dependencies 시스템에 비효율이 있음을 지적
- 저자 본인, 골랑(Golang) 방식의 하위 경로 추가 버전 관리 전략 재설명, npm 특성상 Zod 생태계에 도입이 어렵지만 v3, v4를 동시에 지원하며 점진적 마이그레이션을 제공하는 장점 강조
- peer dependencies가 망가져서 v4를 v3로 가장했다는 이전 의견에 꼭 동의하지 않음, 이는 점진적 마이그레이션을 위한 방편임을 강조, 하나씩 'zod/v4'로 대체한 후 완전히 v4로 업그레이드하는 구조
- 많은 사람들이 비난하는데, 실제로 npm의 본질적 한계라기보다는 큰 변경 포함된 라이브러리를 점진적으로 바꿀 수 있도록 한 실용적 결정임을 강조
- 오랜 기간 npm만 사용해서 편견일 수도 있지만 v3에서 v4로 크게 한번에 옮기지 않고 점진적으로 지원하는 더 좋은 방법이 무엇일지 궁금
- zod 4 베타로 이미 큰 개선 경험함에도 대규모 코드베이스에서 모듈 해상도 세팅이 어려워 제대로 업그레이드 못하고 있는 상황 언급, 레거시 레이어 없이 주요 버전으로만도 출시해줬으면 하는 바람, '버전 폭주 현상' 방지를 위한 저자 해설 공유, 그러나 v3 지원 병행하면 충격파 완화 가능하다는 본인 생각 남김
서버에서 반환하는 타입이 엔드포인트마다 다르거나, 필드 일부가 익명 유저처럼 null로 올 수 있는 등의 복잡한 경우 서버 응답을 어떤 타입 모델로 다뤄야 할지 질문, normalizeUser/normalizePost처럼 여러 함수 만드니 점점 관리가 복잡해지는 문제, 이 문제를 실무에서 어떻게 해결하는지 경험 공유 요청
- discriminated union 예시로 해결 방법 제시, 공통된 스키마 부분을 객체로 정의하고 특정 상황에 맞게 확장하는 방식 설명, 매우 다양한 경우에는 어차피 복잡해질 수 있으나 schema validator로 최소한 체계적으로 유지할 수 있다고 조언
- 이상적으론 User의 타입 구조를 단일 원천(예: discriminated union 형태)으로 정하는 것이 최선, 파이썬 백엔드를 가정할 경우 여러 형태의 Pydantic 모델+유니온 그리고 OpenAPI/GraphQL 코드 제너레이션으로 타입스크립트 클라이언트 타입 생성 구조 제안
- 실사용 예제를 알면 더 좋은 답이 가능하겠지만, union 타입에 구분 프로퍼티(e.g. "user_type")를 넣으면 개별 필드 접근이 쉬운 점 설명, 타입 시스템이 상황별로 알맞은 속성 인식 가능
- 서버가 직접 타입을 내보내야 한다고 고언, 별도의 타입을 클라이언트에서 일일이 다시 작성하는 건 비효율, 파이썬 백엔드는 Pydantic으로 OpenAPI 명세 자동 생성해 타입스크립트 클라이언트에 타입 생성 방법 설명
- GraphQL이 이런 케이스에 적합하게 설계되어 있음을 언급, 타입스크립트 GraphQL 라이브러리로 쿼리 결과 형태를 자동 추론할 수 있고 선택한 필드에 따라 응답 타입 유동적으로 생성됨 예시
Zod 4, 개선에도 불구하고 ArkType이 여전히 월등히 빠름 언급, 기존 라이브러리에선 하위 호환성과 문법 유지를 이유로 성능 한계가 있음, 본인 프로젝트 분석 결과 ArkType을 선택하게 된 이유는 성능과 타입스크립트 사용성 때문
- ArkType 속도 메트릭을 보았고, 실제로 그 속도가 활용에 무슨 영향을 주는지 궁금, 폼 검증 등 일반 상황에서는 영향이 적어 보여서 의문, 혹시 초고속 API 입력 검증처럼 성능 민감한 곳에서 쓰는지 질문
- ArkType이 리서치에 포함되지 않았지만 타입스크립트 사용성을 고려해 찾고 있었음, 그래도 Zod에서 옮길 계획은 없음
- ArkType 사용 경험이 매우 어려웠고 Zod는 사용성이 좋아서 선호한다고 생각
- TypeBox보다 ArkType을 선택한 특별한 이유 궁금
Zod 팀의 새 릴리즈 축하, 마이그레이션 가이드에 쏟아지는 파괴적 변경점 수를 보면 대규모 Zod 의존 프로젝트는 부담이 크고 관리가 어렵겠다는 우려, 오래된 프런트엔드 프로젝트 유지 경험에서 각 라이브러리마다 큰 변화와 문서 부족이 많아 현재 JS 발전 흐름의 아쉬움 표출
- 여러 대형 Next.js 앱을 운영 중인데 최근 1년간 Next.js 14→15, Next.js pages→app router, React 18→19, Eslint 8→9, Tailwind 3→4 등 크고 어려운 변화들 겪으며 정말 힘들었고, 오히려 Django로 지었으면 했던 생각 공유, 특히 Tailwind 3→4 마이그레이션이 의외로 가장 고통스러웠다는 점 회고
- 이런 문제를 완화하려고 'mini' 에디션의 동시 제공 전략을 도입함, 점진적 전환을 쉽게 해주고 트리쉐이킹 최적성 측면에서 'mini' 도입이 대체재들을 견제하기 위해 불가피했다고 설명
- LLM 같은 도구 활용으로 어렵지 않게 마이그레이션할 수 있는 제안
Zod가 기존 다른 대안들에 비해 훨씬 뛰어남을 언급, 하지만 웹 개발에서는 동일 데이터 구조를 여러 방식으로 기술해야 하는 게 현실, JS 입력 검증, Swagger를 통한 API 명세, 서버·클라이언트 각각 별도 정의 등 너무 반복적이고 번거롭다는 아쉬움 표출
- 타입스크립트가 정적 검사 전용 툴로 고집하는 것에서 아쉬움, 런타임 체크까지 원하지는 않으나 클래스/함수/객체의 타입 데이터를 외부로 쉽게 쓸 수 있길 희망, 지금은 여러 도구가 각자 모델과 빌더를 정의해야 해서 중복 불가피, 표준화 시도인 Standard Schema 프로젝트가 주요 검증 라이브러리들과 통합될 조짐 있지만 API 명세, ORM 쪽 확장은 초기 단계임을 공유
- 이런 툴의 핵심은 한 번 정의해 타입 세이프티를 전체 앱으로 전파할 수 있다는 점, Zod 스키마를 일종의 진실 원천(싱글 소스 오브 트루스)으로 삼을 수 있음을 강조
- 이런 번잡한 구조를 불편해하는 사람 중 실제로 타입스크립트(Zod 포함) 하나로 다 통합하자는 제안엔 거부감을 보이는 이들이 많음도 덧붙임
- 모든 API와 시스템이 항상 변화와 실험 중이라는 점, 복잡한 레이어가 많아진 현실이 단점이긴 해도 "프로젝트에서 일만 잘 돌아가면 된다"는 상황에선 결국 더 많은 일감을 만들어준다는 시각
- 전체적으로는 trpc 같은 엔드 투 엔드 타입세이프티 사용할 수도 있지만 이를 위해서는 프런트와 백엔드 모두 타입스크립트로 통일해야 하고 웹 이외 플랫폼(모바일 등) 사용이 힘들다는 점 실무 한계로 지목
전문가 아니지만 스키마 기반인 JSON-Schema가 타입스크립트 외 다른 언어에도 validator 구현이 가능하서 좋은 선택일 수 있다고 생각, ajv.js.org 같은 라이브러리 예시 기반으로 Zod과의 비교 질문
- Zod는 JSON 형태만이 아니라 JS 객체 전체(날짜, 클래스 인스턴스 등 JSON으로 표현 불가한 데이터)에도 유효성 검증이 가능, JSON 변환 과정에 쓸 수도 있어 스키마를 문자열 기반으로 작성하고, 예를 들어 ISO date string을 Date 객체로 검증해 변환할 수 있음
- Zod 4는 Zod 스키마를 JSON-Schema로 변환 지원(과거엔 외부 라이브러리 필요), Zod의 큰 차별점은 preprocess/refine 기능으로, 검증 전 콜백 추가가 가능해 MM/DD/YYYY를 DD/MM/YYYY로 바꿔서 검증하는 등 유연한 변환 가능(이건 JSON-Schema에선 불가) 예시 강조
- JSON-Schema도 좋은 선택이고, 이 경우 TypeBox가 생성에 적합, avj를 쓸 수도 있고 자체적인 검증 시스템도 사용 가능, 자체 검증이 더 빠르지만 동기 전용이고 avj는 비동기 검증 또한 가능해서 심층 검증 필요시 유리
- 여러 언어에서 사용하려면 JSON-Schema가 가장 보편적, OpenAPI로 감싸면 자동으로 API 문서까지 생성할 수 있어 장점
Zod을 새 프로젝트에 막 도입하기 시작했는데 이번 릴리즈 시기가 완벽하게 맞아떨어졌다는 기쁨, 계획대로라면 v4로 마이그레이션하려고 많은 변경이 필요했을 텐데 타이밍이 절묘
생각보다 부정적 의견이 많아서 놀랐다는 반응, v4 초기 버전 테스트 때 새로운 API는 마음에 들었으나 마이그레이션 경로가 걱정됐었고, 별도 패키지명 출시 제안까지 고민했으나 실제 저자 방식이 매우 탁월하게 문제를 해결했다고 높이 평가, 덕분에 의존성 업데이트 기다릴 필요 없이 바로 v4 채택 가능함
- 본인도 유효성 검증 같은 분야는 전부 한 번에 마이그레이션할 여력이 없다고 생각, 지금 방식이 현실적으로 최적이라고 평가

답변달기