JSON → TypeScript 변환이란?
JSON to TypeScript는 JSON 데이터를 TypeScript 인터페이스와 타입 정의로 변환합니다. 문자열, 숫자, 불리언, 배열, 중첩 객체를 인식하고 nullable 필드를 유니온 타입으로 옵셔널 처리합니다. API 응답 타입을 직접 작성하는 번거로움을 줄여줍니다.
배열 안의 객체들이 형태가 조금씩 다르면 제너레이터가 이를 병합합니다. 일부 레코드에서 빠진 키는 '?'가 붙어 선택 속성이 됩니다. 중첩 객체는 각각 이름 붙은 인터페이스(User, UserAddress, UserAddressGeo)로 만들어지고, 혼합 배열은 (string | number)[] 같은 유니온 타입이 됩니다. ISO 8601 형식의 날짜 문자열은 JSDoc 힌트와 함께 표시되며, 여러 샘플에서 소수의 고정 값만 갖는 문자열 필드는 일반 string 대신 문자열 리터럴 유니온으로 추론됩니다. TypeScript 출력 외에도 같은 입력에서 세 개의 탭이 더 생깁니다: 짝이 맞는 Zod 스키마, 현실적인 예시 값을 채운 목 데이터, 그리고 draft-07 JSON 스키마입니다. 인터페이스와 타입 별칭을 바꾸고, export 키워드를 켜고, 키를 A→Z로 정렬하며, camelCase를 켜면 snake_case나 kebab-case 키를 TypeScript다운 이름으로 정규화할 수 있습니다.
사용 방법
- 1단계 — JSON 객체 또는 배열을 붙여 넣거나, .json 파일을 입력 영역에 끌어다 놓거나, URL을 입력해 라이브 JSON을 바로 가져옵니다. 도구가 구조를 분석하여 모든 필드의 TypeScript 타입을 추론합니다.
- 2단계 — 출력을 커스터마이즈합니다: 루트 인터페이스 이름을 설정하고, 인터페이스와 타입 별칭 중 선택하며, null이 될 수 있는 필드에 선택적 속성을 표시할지 결정합니다.
- 3단계 — 출력을 복사하거나 다운로드하세요. 네 개의 탭이 같은 설정을 공유합니다: TypeScript 타입, 런타임 검증을 위한 짝이 맞는 Zod 스키마, 테스트와 Storybook에 바로 쓰는 목 데이터, 그리고 OpenAPI나 폼 라이브러리용 draft-07 JSON 스키마입니다. 중첩된 모든 객체는 자동으로 각자의 명명된 인터페이스를 가집니다.
사용 시기
- OpenAPI/Swagger 스펙이 없는 API 응답에 타입을 입힐 때.
- 스크립트에서 읽어들이는 JSON 설정 파일(tsconfig.json, package.json) 타입을 빠르게 만들 때.
- 타사 SDK 응답에 몇 초 안에 타입을 입힌 래퍼를 만들 때.
결과
API가 중첩된 주소와 설정이 포함된 사용자 객체를 반환합니다. JSON 응답을 붙여 넣고 루트 이름을 User로 설정하면 User, UserAddress, UserPreferences 인터페이스가 생성되며, 선택적 필드에는 string | null 같은 정확한 타입이 지정됩니다.
자주 묻는 질문
- 어떤 필드를 선택 속성으로 표시할지 어떻게 결정하나요?
- 입력이 단일 객체이고 'null 가능 필드를 선택 속성으로 표시'를 켜면 값이 null인 필드에 ?가 붙습니다. 객체 배열의 경우 모든 레코드의 키를 합집합으로 만들고, 한 레코드라도 누락된 키는 선택 속성이 됩니다.
- 배열 안의 요소들이 서로 다른 모양일 때는 어떻게 되나요?
- 동일한 로직입니다. 모든 요소에 있는 키는 필수, 일부 요소에만 있는 키는 선택, 원시 타입이 섞인 값은 string | number 같은 유니온이 됩니다. 결과는 배열 전체를 묘사하는 하나의 인터페이스입니다.
- 인터페이스와 타입 별칭 중 무엇을 골라야 하나요?
- 인터페이스는 선언 병합으로 확장하기 쉽고 API 형태에 흔히 씁니다. 타입 별칭은 이후 유니온, 인터섹션, 매핑 타입과 결합할 때 더 유연합니다. 런타임 차이는 없으니 프로젝트 관례에 맞추세요.
- 왜 일부 속성 키가 따옴표로 감싸여 있나요?
- 키에 TypeScript 식별자로 쓸 수 없는 문자(하이픈, 공백, 숫자로 시작, 점)가 포함되면 제너레이터가 따옴표로 감쌉니다. 타입은 유효하게 유지되고, 코드에서는 obj["weird-key"] 형식으로 접근합니다.
- API 응답 모양이 바뀌면 생성한 타입이 그것을 잡아내나요?
- 다시 생성해야 반영됩니다. 타입은 붙여넣은 JSON의 스냅샷이므로 스스로 갱신되지 않습니다. API 버전이 바뀔 때 타입을 재생성하고 코드 리뷰에서 diff를 확인하는 흐름이 일반적입니다.