API JSON 검증 체크리스트: 문법 통과 후 확인할 것

JSON.parse가 성공했다는 것은 텍스트가 JSON 문법을 따른다는 뜻일 뿐입니다. API 계약을 만족한다는 뜻은 아닙니다. 응답은 유효한 JSON일 수 있지만 필수 필드가 빠졌거나, 타입이 틀렸거나, 오래된 enum을 사용하거나, 금액을 안전하지 않은 부동소수점으로 만들 수 있습니다.

1. HTTP 계층부터 확인하기

본문을 보기 전에 상태 코드, Content-Type, 문자셋, 요청 ID를 기록하세요. JSON API는 일반적으로 application/json 또는 명확한 호환 미디어 타입을 반환해야 합니다. 204 응답을 강제로 JSON으로 파싱해서는 안 되며, 오류 응답도 가끔 HTML을 반환하는 대신 안정적인 JSON 구조를 가져야 합니다.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: req_123

프록시나 WAF가 로그인 페이지를 200으로 감싸면 파서 오류가 원인을 제대로 보여 주지 않습니다. 헤더와 본문 앞부분을 먼저 확인하면 더 빨리 문제를 찾을 수 있습니다.

2. 문법과 인코딩 검증하기

응답을 JSON 검증기에 넣어 괄호, 쉼표, 따옴표, 이스케이프 문자를 확인하세요. 한국어, 이모지, 줄바꿈, 백슬래시, Unicode 이스케이프가 포함된 샘플도 테스트해야 합니다. 서버와 클라이언트는 UTF-8을 동일하게 사용해야 합니다.

3. 루트 구조와 필수 필드 확인하기

계약은 루트가 객체인지, 배열인지, 스칼라인지 명확히 해야 합니다. 페이지네이션 API는 {items, page, total} 같은 형태를 약속하고, 데이터가 없을 때만 빈 배열로 바뀌어서는 안 됩니다. 각 필드는 누락, 명시적 null, 유효값 존재를 구분해야 합니다.

4. 필드 타입을 엄격하게 검사하기

JSON에는 문자열, 숫자, boolean, null, 객체, 배열만 있습니다. 날짜, UUID, 금액, 식별자는 추가 규칙이 필요합니다. 숫자를 문자열로 반환하거나, 배열이 필요한 곳에 단일 객체를 반환하거나, false를 누락처럼 처리하는 오류가 자주 발생합니다.

큰 식별자는 JavaScript 정밀도 손실을 피하기 위해 문자열로 두는 것이 안전합니다.

{
  "userId": "9007199254740993",
  "enabled": false,
  "createdAt": "2026-07-17T08:30:00Z"
}

5. JSON Schema로 계약 고정하기

JSON Schema는 필수 필드, 타입, 길이, 형식, enum, 중첩 규칙을 실행 가능한 계약으로 만들 수 있습니다. 백엔드 입력 검증, 계약 테스트, 클라이언트 생성 과정에서 재사용하고 버전 관리에 포함하세요.

정리

API JSON 검증은 HTTP, 문법, 구조, 타입, 비즈니스 규칙, 호환성 순서로 진행해야 합니다. 파싱 성공은 첫 관문일 뿐입니다. Schema, 실패 샘플, 계약 테스트, 일관된 오류 응답이 있어야 안전하게 사용할 수 있습니다.