데이터 검증(validation) 라이브러리 Zod

#None

Zod란?

Zod는 TypeScript를 중심으로 설계된 데이터 검증(validation) 라이브러리입니다.
스키마를 한 번 정의하면 런타임 데이터 검증과 정적 타입 추론을 동시에 제공하는 것이 가장 큰 특징입니다.

즉, 외부에서 들어오는 신뢰할 수 없는 데이터(API 응답, 사용자 입력 등)를
실행 시점에 안전하게 검증하면서,
그 결과를 TypeScript 타입으로 그대로 활용할 수 있습니다.

블로그 메타데이터 스키마 정의

아래는 블로그 글의 메타데이터(title, description, category 등)를
Zod 스키마로 정의한 예시입니다.

import { z } from "zod";

export const BlogMetaSchema = z
  .object({
    title: z
      .string()
      .min(5, "제목은 최소 5자 이상이어야 합니다.")
      .max(100, "제목은 최대 100자까지 가능합니다."),

    description: z
      .string()
      .min(10, "설명은 최소 10자 이상이어야 합니다.")
      .max(200, "설명은 최대 200자까지 가능합니다."),

    category: z.enum(["tech", "life", "design", "etc"], {
      errorMap: () => ({ message: "유효하지 않은 카테고리입니다." }),
    }),

    tags: z.array(z.string()).optional(),

    published: z.boolean(),

    publishedAt: z.string().datetime().optional(),
  })
  .refine(
    (data) => {
      // 게시된 글이라면 publishedAt은 필수
      if (data.published) {
        return !!data.publishedAt;
      }
      return true;
    },
    {
      message: "게시된 글은 publishedAt이 필요합니다.",
      path: ["publishedAt"],
    }
  );

스키마 기반 데이터 검증

정의한 스키마를 사용해 데이터를 파싱하면,
검증에 성공한 경우 타입이 보장된 결과를 얻을 수 있습니다.

const input = {
  title: "Zod로 블로그 메타데이터 검증하기",
  description: "Zod를 사용해 블로그 메타데이터를 안전하게 검증하는 방법입니다.",
  category: "tech",
  tags: ["zod", "typescript", "validation"],
  published: true,
  publishedAt: "2026-01-01T10:00:00Z",
};

// result는 검증된 데이터이며, 타입이 보장됨
const result = BlogMetaSchema.parse(input);

만약 스키마 조건을 만족하지 못하면 parse 단계에서 즉시 오류가 발생해,
잘못된 데이터가 애플리케이션 내부로 들어오는 것을 방지할 수 있습니다.

z.infer와 TypeScript의 infer

Zod의 강력한 점은 스키마로부터 TypeScript 타입을 자동으로 추론할 수 있다는 점입니다.

export type BlogMeta = z.infer<typeof BlogMetaSchema>;

여기서 사용된 infer는 TypeScript의 **조건부 타입(Conditional Type)**에서
특정 타입을 추론하기 위해 사용되는 키워드입니다.

Zod는 내부적으로 이 infer 메커니즘을 활용해,
스키마 구조를 분석하고 그에 대응하는 TypeScript 타입을 자동으로 생성합니다.

그 결과:

  • 스키마와 타입을 중복 정의할 필요가 없고
  • 검증 로직과 타입 정의가 항상 동일하게 유지됩니다

즉, **“단일 진실의 원천(Single Source of Truth)”**을 스키마 하나로 유지할 수 있습니다.

정리

  • Zod는 런타임 검증 + 타입 추론을 동시에 제공하는 TypeScript 중심 라이브러리
  • 스키마 정의만으로 데이터 검증과 타입 안정성을 모두 확보 가능
  • z.infer를 통해 스키마와 타입을 완전히 동기화
  • API, 폼 검증, MDX frontmatter 등 다양한 실무 환경에 적합

참조