본문으로 건너뛰기
스키마 변환

JSON Schema ⇄ Zod 변환

JSON Schema에서 Zod 스키마를 생성하고 반대로 Zod 코드에서 JSON Schema를 내보내는 양방향 변환 도구입니다. required와 .optional(), enum, union(oneOf / anyOf), 중첩된 객체, ["string", "null"]과 .nullable(), additionalProperties: false와 .strict(), 문자열 format(email·uri·uuid·date-time)과 길이·패턴·숫자 범위 제약을 양방향으로 대응시킵니다. 같은 파일 안의 $ref(재귀 포함)는 이름 붙은 정의로, allOf는 .and()로 바뀌고, 튜플·default·description도 대응합니다. 외부 파일로의 $ref나 if/then처럼 변환할 수 없는 곳은 any로 취급하고 경고로 표시합니다. Zod 코드는 실행하지 않고 읽기만 합니다. 모든 처리는 브라우저 안에서 이루어지며 입력한 스키마는 전송되지 않습니다.

JSON 샘플로 JSON Schema 만들기

샘플 JSON을 붙여 넣으면 이를 설명하는 JSON Schema(2020-12)를 만듭니다. 타입, 필수 키, null 허용, format을 추정하며, 배열의 일부 요소에만 있는 키는 선택으로 처리합니다.

가이드

사용 방법 및 특징

  • "JSON Schema → Zod"를 선택하고 스키마를 붙여 넣으면 `z.object({ ... })` 형태의 Zod 스키마와 `z.infer` 타입 별칭이 생성됩니다.
  • "Zod → JSON Schema"를 선택하면 반대 방향으로 변환합니다. `import` 줄이나 `export const user =` 가 붙어 있어도 `z.` 로 시작하는 식을 찾아 해석합니다.
  • `required` 에 없는 프로퍼티에는 `.optional()` 이 붙고, 반대 방향에서는 `.optional()` 이 없는 프로퍼티가 `required` 에 들어갑니다.
  • 문자열의 세부 사항도 양방향으로 대응됩니다. `format: "email"` 은 `.email()`, `minLength` 는 `.min()` 이 됩니다.
  • `$ref` 나 `allOf` 처럼 변환할 수 없는 부분은 결과 아래에 경고로 표시됩니다. 조용히 깨진 결과를 내놓지 않습니다.
FAQ

자주 묻는 질문

  • JSON 샘플에서 Zod를 만드는 "JSON to Zod"와 무엇이 다른가요?

    입력이 다릅니다. JSON to Zod는 API 응답 같은 "값 샘플"에서 타입을 추론하므로 어떤 필드가 필수인지, 문자열 format이 무엇인지는 알 수 없습니다. 이 도구는 JSON Schema 자체를 입력으로 받기 때문에 required, enum, minLength, format:email 같은 제약이 그대로 Zod 체인(.optional() / .enum() / .min() / .email())에 반영됩니다. OpenAPI나 JSON Schema 정의가 이미 있다면 이쪽이 정확합니다.
  • required와 .optional()은 어떻게 대응되나요?

    기본값이 서로 반대입니다. JSON Schema는 required 배열에 나열되어야 필수이고, Zod는 .optional()이 없으면 필수입니다. 변환기는 이 차이를 흡수해, JSON Schema→Zod에서는 required에 없는 프로퍼티에 .optional()을 붙이고, 반대 방향에서는 .optional()이 없는 프로퍼티를 required 배열로 모읍니다.
  • $ref를 쓰는 스키마도 변환할 수 있나요?

    같은 파일 안의 참조($defs나 definitions, 재귀 포함)는 이름 붙은 정의로 펼칩니다. 외부 파일로의 참조나 없는 경로는 그 자리가 z.any()가 되고 경고가 나오므로, 공통 정의를 다른 파일로 나눴다면 하나의 파일로 합친 뒤 붙여 넣으세요.
  • 생성한 Zod를 그대로 운영 환경 검증에 써도 되나요?

    뼈대로는 쓸 수 있지만, 원래 JSON Schema에 없던 업무 규칙(허용 이메일 도메인, 필드 간 정합성 등)은 생성되지 않습니다. 또한 pattern은 z.string().regex()로 변환되는데, 원래 정규식이 ECMAScript 호환이 아니면 동작이 달라질 수 있습니다. 생성 후 반드시 내용을 확인하세요.
활용

주요 활용 사례

  • OpenAPI 정의에서 프런트엔드 타입과 검증 만들기

    OpenAPI의 components.schemas는 JSON Schema이므로 그대로 붙여 넣으면 Zod 스키마와 z.infer 타입을 한 번에 얻을 수 있습니다. 서버 정의와 프런트 검증이 어긋나는 것을 막아 줍니다.
  • 기존 Zod 스키마를 API 명세로 내보내기

    코드에서 Zod 스키마를 먼저 작성했다면 반대 방향 변환으로 JSON Schema를 만들어 OpenAPI의 components나 문서에 붙여 넣을 수 있습니다.
  • 손으로 쓴 검증을 스키마 기반으로 옮기기

    if 문으로 흩어진 검증을 교체할 때, JSON Schema가 있으면 출발점이 되는 Zod 스키마를 한 번에 생성할 수 있어 required나 enum을 빠뜨릴 일이 줄어듭니다.
  • AI가 만든 JSON Schema를 실제로 쓸 수 있는 형태로

    LLM에 작성시킨 JSON Schema를 그대로 붙여 넣어 TypeScript에서 동작하는 Zod 스키마로 바꾸고, 타입과 런타임 검증을 동시에 얻을 수 있습니다.
주의

주의 사항 및 제한

  • 같은 파일 안의 $ref는 펼치지만, 외부 참조와 조건 분기는 지원하지 않습니다

    같은 파일 안의 $ref($defs·definitions·재귀)는 이름 붙은 정의로 펼치고, allOf는 .and() 교차 타입이 됩니다. 외부 파일로의 $ref, if/then/else, not, patternProperties는 지원하지 않으며 변환 결과 아래에 경고로 표시되므로 해당 부분은 직접 보완하세요.
  • Zod→JSON Schema는 코드를 문자열로 해석합니다

    브라우저 안에서 처리하기 위해 코드를 실행하지 않고 텍스트로 파싱합니다. z.object / z.array / z.union / z.enum / z.literal / z.record와 주요 메서드 체인은 지원하지만, 변수로 분리한 스키마 참조나 .refine() 같은 임의 함수는 JSON Schema로 표현할 수 없어 무시됩니다.
  • pattern의 정규식은 그대로 옮겨집니다

    JSON Schema의 pattern은 z.string().regex()가 되고, 반대 방향에서는 그 내용이 pattern에 들어갑니다. JSON Schema는 ECMAScript 호환이 아닌 정규식도 허용하므로 그대로 옮기면 동작이 달라질 수 있습니다.
  • 생성 결과는 반드시 검토하세요

    이 도구는 마이그레이션의 출발점을 만들기 위한 것입니다. 업무 규칙이나 필드 간 정합성 검사는 원래 스키마에 없으면 생성되지 않으므로, 운영에 쓰기 전에 내용을 확인해 주세요.

이 도구의 관련 기사

최신 아티클