92 lines
10 KiB
Markdown
92 lines
10 KiB
Markdown
---
|
|
title: official-doc / Zod — TypeScript-first Schema Validation (parse / safeParse runtime contract)
|
|
source_type: official-doc
|
|
url: https://zod.dev/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
related_branches: []
|
|
related_projects: [ca-skeleton-frontend]
|
|
tags: [official-doc, ca-skeleton, frontend, validation, javascript]
|
|
created: 2026-07-18
|
|
last_reviewed: 2026-07-18
|
|
---
|
|
|
|
# Zod — TypeScript-first Schema Validation (parse / safeParse runtime contract)
|
|
|
|
> Layer: `raw/official-docs/` — Zod 공식 문서(zod.dev)의 스키마 정의·`.parse()`/`.safeParse()` 런타임 계약 원문 발췌.
|
|
> `ca-skeleton-frontend` 가 plain-JavaScript(컴파일 타임 TypeScript 타입 없음) 스켈레톤에서 zod 를 API 응답/폼 입력 등 경계(boundary)의 런타임 스키마 검증 계층으로 채택하는 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Parent | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/project-notes/ca-skeleton-frontend-operational-contract]] | plain-JavaScript ca-skeleton-frontend 스켈레톤에서 zod 를 API 응답·폼 입력 등 경계의 런타임 스키마 검증 계층으로 채택하는 근거 (컴파일 타임 타입 부재를 런타임 `.parse()`/`.safeParse()` 로 보완) |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://zod.dev/ (Intro 페이지) + https://zod.dev/basics (Basic usage 페이지 — `.parse()`/`.safeParse()`/에러 처리 상세)
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Colin McDonnell (@colinhacks) — Zod 프로젝트 메인테이너, zod.dev 는 프로젝트 공식 문서 사이트
|
|
- 발행일: 명시 없음 (페이지 배너 기준 "Zod 4 is now stable" — Zod 4 시점 문서, 정확한 발행일은 문서에 없음)
|
|
- 마지막 확인일: 2026-07-18
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`ca-skeleton-frontend` 는 plain JavaScript(컴파일 타임 타입 없음) 스켈레톤이므로, API 응답이나 폼 입력처럼 신뢰할 수 없는 외부 데이터가 들어오는 경계에서 컴파일러가 형태를 보장해줄 수 없다. zod 의 `.parse()`/`.safeParse()` 는 "스키마를 먼저 정의하고, 그 스키마로 실제 데이터를 런타임에 검증한다"는 계약을 공식 API로 제공하므로, 이 경계 검증 계층 채택의 1차 근거로 보관.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, 5문장)
|
|
|
|
> [Intro §Introduction] "Zod is a TypeScript-first validation library. Using Zod, you can define schemas you can use to validate data, from a simple string to a complex nested object." — https://zod.dev/ (fetched text line 8)
|
|
|
|
> [Intro §Features] "Works with TypeScript and plain JS" — https://zod.dev/ (fetched text line 25)
|
|
|
|
> [Basics §Parsing data] "Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input." — https://zod.dev/basics (fetched text line 102)
|
|
|
|
> [Basics §Handling errors] "When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues." — https://zod.dev/basics (fetched text line 108)
|
|
|
|
> [Basics §Handling errors] "To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently." — https://zod.dev/basics (fetched text line 131)
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| ZOD-VALID-C1 | Zod 는 스스로를 "TypeScript-first validation library"로 정의하며, 단순 string 부터 복잡한 nested object 까지 스키마를 먼저 정의(schema-first)한 뒤 그 스키마로 데이터를 검증하는 사용 방식을 공식 소개한다 | [Intro §Introduction] "Zod is a TypeScript-first validation library. Using Zod, you can define schemas you can use to validate data, from a simple string to a complex nested object." | `official-vendor-doc` | zod 를 schema-first 검증 라이브러리로 채택하는 모든 근거 | 이 진술 자체는 "TypeScript-first"가 TypeScript 없이도(plain JS) 동일 가치를 준다는 것까지는 증명 안 함 — 그건 C2 근거 필요 |
|
|
| ZOD-VALID-C2 | Zod 는 공식 Features 목록에 "Works with TypeScript and plain JS"를 명시한다 — TypeScript 컴파일 타입이 없는 환경에서도 라이브러리가 동작함을 공식 문서가 직접 진술 | [Intro §Features] "Works with TypeScript and plain JS" | `official-vendor-doc` | plain-JavaScript(컴파일 타임 타입 없음) 프로젝트에서 zod 를 런타임 검증 라이브러리로 쓰는 기술적 정당성 | plain JS 환경에서의 DX(자동완성·타입추론 부재로 인한 개발 경험 저하) 비교, 또는 Yup/ajv/io-ts 등 대안 대비 우위는 증명 안 함 — 비교 진술 없음 |
|
|
| ZOD-VALID-C3 | `.parse()` 는 스키마로 입력을 검증하고, 유효하면 "strongly-typed deep clone of the input"을 반환한다 — 즉 원본 입력이 아니라 검증을 통과한 복제본을 돌려주는 런타임 강제(enforcement) 지점 | [Basics §Parsing data] "Given any Zod schema, use .parse to validate an input. If it's valid, Zod returns a strongly-typed deep clone of the input." | `official-reference` | API 응답/폼 입력 등 경계에서 `.parse()` 를 단일 검증 관문(gate)으로 쓰는 설계 | "parse, don't validate" 라는 용어 자체는 이 원문에 등장하지 않음 — 이는 이 branch/문서의 해석적 이름 붙이기이며 zod 공식 문서의 직접 주장이 아님. 대량 트래픽에서 deep clone 의 성능 비용도 증명 안 함 |
|
|
| ZOD-VALID-C4 | 검증 실패 시 `.parse()` 는 "validation issues에 대한 세분화된 정보"를 담은 `ZodError` 인스턴스를 throw 한다 (path/code/message 단위) | [Basics §Handling errors] "When validation fails, the .parse() method will throw a ZodError instance with granular information about the validation issues." | `official-reference` | throw-기반 실패 신호로 잘못된 API 응답/폼 입력을 경계에서 즉시 차단(fail-fast)하는 패턴의 근거 | 특정 프레임워크(React error boundary 등)와의 통합 동작은 이 문서 범위 밖 — 별도 확인 필요 |
|
|
| ZOD-VALID-C5 | `.safeParse()` 는 try/catch 없이 `{success, data}` 또는 `{success:false, error}` 형태의 discriminated union 결과 객체를 반환한다 | [Basics §Handling errors] "To avoid a try/catch block, you can use the .safeParse() method to get back a plain result object containing either the successfully parsed data or a ZodError. The result type is a discriminated union, so you can handle both cases conveniently." | `official-reference` | 폼 필드별 검증처럼 예외를 던지지 않고 결과를 분기 처리해야 하는 경계(non-throwing) 검증 패턴의 근거 | `.parse()`(throw) vs `.safeParse()`(non-throw) 중 어느 쪽이 API 응답과 폼 입력 각각에 "권장"되는지는 이 문서가 규정하지 않음 — 프로젝트 자체 결정 사항 |
|
|
|
|
### Strength 참고
|
|
|
|
C1·C2 는 라이브러리의 정체성/기능 목록에 대한 공식 진술이므로 `official-vendor-doc`, C3~C5 는 API 사용법(reference)에 대한 공식 진술이므로 `official-reference` 로 구분. 5개 모두 zod 메인테이너가 운영하는 프로젝트 공식 문서(zod.dev)에서 직접 발췌 — 제3자 해설이 아님.
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `ZOD-VALID-C1`: zod 는 schema-first 검증 라이브러리로 스스로를 정의
|
|
- `ZOD-VALID-C2`: zod 는 공식적으로 "plain JS" 환경 동작을 지원한다고 명시
|
|
- `ZOD-VALID-C3`: `.parse()` 가 검증 통과 시 검증된 복제 데이터를 반환하는 런타임 관문 역할
|
|
- `ZOD-VALID-C4`: `.parse()` 실패 시 세분화된 정보를 담은 `ZodError` throw
|
|
- `ZOD-VALID-C5`: `.safeParse()` 는 non-throwing discriminated union 결과를 반환
|
|
- 이 자료가 증명하지 않는 것:
|
|
- "parse, don't validate" 라는 용어/원칙 자체 — 원문에 이 표현은 등장하지 않음. 이 phrase 를 이 자료의 공식 주장인 것처럼 branch-note 등에 인용하면 안 됨 (UNSUPPORTED — 해당 용어는 별도 출처 필요)
|
|
- zod 가 plain-JS 런타임 검증 라이브러리 중 "최선" 또는 "업계 표준"이라는 비교 우위 — Yup, io-ts, ajv 등과의 비교는 이 문서에 없음
|
|
- API 응답 검증과 폼 입력 검증 각각에 `.parse()` vs `.safeParse()` 중 무엇을 써야 하는지에 대한 공식 권고 — 문서는 두 API 의 존재와 동작만 설명, 사용처별 권장은 안 함
|
|
- React Hook Form 등 특정 폼 라이브러리와의 통합 시 실제 동작 계약(문서는 "Ecosystem" 섹션에서 이름만 언급, 세부 계약 없음)
|
|
- 내 프로젝트(`ca-skeleton-frontend`)에 적용하려면 추가 확인이 필요한 것:
|
|
- 실제 fetch/axios 클라이언트에서 API 응답에 zod 스키마를 어디서(예: 클라이언트 wrapper 레벨 vs 개별 호출 레벨) 적용할지의 아키텍처 결정 — 이 자료는 API 자체 사용법만 제공, wiring 위치는 프로젝트 자체 결정
|
|
- 폼 라이브러리 선택 시 zod 와의 실제 통합 동작(에러 메시지 매핑 등) 로컬 검증 필요
|
|
|
|
## 메모 / Notes
|
|
|
|
- WebFetch 도구는 소스를 요약/paraphrase 하는 경향이 있어(작은 모델 경유), self-grep 검증이 불가능했다. 대신 `curl` 로 원본 HTML(SSR)을 직접 가져와 python 으로 태그 제거 후 verbatim 텍스트를 만들고 그 파일에 대해 self-grep 했다 — 이 과정이 이 자료의 유일한 신뢰 가능한 검증 경로였음을 기록.
|
|
- fetch 한 두 페이지: Intro(`/`)와 Basic usage(`/basics`). Defining schemas(`/api`) 페이지는 이번 dispatch 범위 밖 — 추후 zod 의 세부 타입(`z.string()`, `z.object()` 옵션 등) 근거가 필요하면 별도 raw 문서로 추가 조사 권장.
|
|
- 다음 fetch 후보: `https://zod.dev/error-customization` (에러 메시지 커스터마이징 — 폼 UX 관련 있을 수 있음), `https://zod.dev/api` (Defining schemas 전체 레퍼런스).
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: (미작성 — 이번 조사 기준 vault 내 zod 관련 최초 raw 문서)
|
|
- 인용하는 project: [[raw/project-notes/ca-skeleton-frontend-operational-contract]]
|
|
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|