JSON 가이드를 찾는 분들이 가장 먼저 부딪히는 벽은 문법 자체가 아니라 "어디까지가 규칙이고 어디부터가 관행인가"입니다. JSON은 배우는 데 10분이면 충분할 만큼 단순하지만, 실무에서는 쉼표 하나 때문에 API 전체가 멈추는 일이 흔합니다. 이 글에서는 JSON의 구조와 자료형, 자주 터지는 오류 유형, 그리고 실제 개발 현장에서 쓰이는 검증 방법까지 순서대로 정리합니다.
JSON이 무엇이고 왜 표준이 되었나
JSON은 JavaScript Object Notation의 약자로, 사람이 읽을 수 있으면서 기계가 파싱하기도 쉬운 텍스트 기반 데이터 교환 형식입니다. 이름에 JavaScript가 들어가지만 특정 언어에 종속되지 않으며, Python, Java, Go, PHP 등 거의 모든 언어가 표준 라이브러리 수준에서 JSON을 지원합니다.
JSON이 사실상의 표준이 된 이유는 세 가지로 요약됩니다.
- 구조가 단순합니다. 객체와 배열, 두 가지 컨테이너만 이해하면 어떤 복잡한 데이터도 표현할 수 있습니다.
- 용량이 작습니다. 같은 데이터를 표현할 때 XML 대비 태그 중복이 없어 전송량이 30퍼센트 이상 줄어드는 경우가 많습니다.
- 파싱 비용이 낮습니다. 브라우저와 서버 모두 네이티브 파서를 내장하고 있어 별도 의존성이 필요 없습니다.
JSON 문법과 6가지 자료형
JSON이 허용하는 값의 종류는 딱 여섯 가지입니다. 이 범위를 벗어나면 파싱 오류가 발생합니다.
| 자료형 | 예시 | 주의사항 |
|---|---|---|
| 문자열 | "홍길동" | 반드시 큰따옴표만 사용합니다 |
| 숫자 | 42, -3.14, 1.2e5 | NaN, Infinity는 사용할 수 없습니다 |
| 불리언 | true, false | 소문자로만 작성합니다 |
| null | null | NULL, None은 인식되지 않습니다 |
| 객체 | {"key": "value"} | 키는 항상 문자열이어야 합니다 |
| 배열 | [1, 2, 3] | 서로 다른 자료형을 섞어도 됩니다 |
실제 데이터를 조합하면 다음과 같은 형태가 됩니다. 객체 안에 배열이 들어가고 배열 안에 다시 객체가 들어가는 중첩 구조가 JSON의 표현력을 만들어냅니다.
구조를 설계할 때는 깊이를 3단계 이내로 유지하는 것이 좋습니다. 중첩이 깊어질수록 클라이언트 쪽 접근 코드가 길어지고, 중간 단계 값이 null일 때 처리해야 할 분기가 기하급수적으로 늘어나기 때문입니다.
실무에서 자주 터지는 오류 5가지
JSON 관련 장애의 대부분은 아래 다섯 가지 패턴 안에 들어갑니다.
- 후행 쉼표(trailing comma): 배열이나 객체의 마지막 요소 뒤에 쉼표를 남기는 실수입니다. JavaScript 객체 리터럴에서는 허용되지만 JSON에서는 명백한 오류입니다.
- 작은따옴표 사용: Python 딕셔너리를 그대로 출력해 붙여넣을 때 흔히 발생합니다. JSON은 큰따옴표만 인정합니다.
- 주석 삽입: 표준 JSON에는 주석 문법이 없습니다. 설정 파일에 설명을 남기고 싶다면 JSON5나 JSONC 같은 확장 포맷을 쓰거나 _comment 키를 활용해야 합니다.
- 이스케이프 누락: 문자열 안에 큰따옴표나 역슬래시, 줄바꿈이 들어갈 때 백슬래시로 이스케이프하지 않으면 구조가 깨집니다.
- 숫자 정밀도 손실: 64비트를 넘는 정수 ID를 숫자로 보내면 JavaScript에서 값이 변형됩니다. 큰 ID는 문자열로 전달하는 것이 안전합니다.
이런 오류는 눈으로 찾기보다 도구로 잡는 편이 훨씬 빠릅니다. 응답 데이터가 한 줄로 압축되어 왔을 때는 JSON 정렬기로 들여쓰기를 복원한 뒤 구조를 확인하면 문제 지점이 바로 드러납니다.
JSON과 XML, YAML의 차이점
데이터 포맷 선택은 용도에 따라 갈립니다. 세 포맷의 성격을 비교하면 다음과 같습니다.
| 구분 | JSON | XML | YAML |
|---|---|---|---|
| 가독성 | 보통 | 낮음 | 높음 |
| 주석 지원 | 없음 | 있음 | 있음 |
| 파싱 속도 | 빠름 | 느림 | 보통 |
| 주 사용처 | API 통신 | 레거시 시스템, 문서 | 설정 파일 |
정리하면 네트워크로 오가는 데이터는 JSON, 사람이 자주 손으로 수정하는 설정 파일은 YAML, 스키마 검증과 네임스페이스가 필수인 엔터프라이즈 환경은 XML이 여전히 유효합니다.
실무 적용을 위한 체크리스트
마지막으로 JSON을 다룰 때 반복적으로 확인하면 좋은 항목들을 정리합니다.
- API 응답은 항상 동일한 최상위 구조를 유지합니다. 성공과 실패 응답의 형태가 다르면 클라이언트 코드가 복잡해집니다.
- 날짜와 시간은 ISO 8601 형식(2026-07-20T09:30:00Z)으로 통일합니다.
- 인코딩은 UTF-8을 사용하고, 한글이 포함된 경우 유니코드 이스케이프 대신 원문 그대로 전송해도 무방합니다.
- 운영 환경에서는 공백 없이 압축해 전송하고, 디버깅 시에만 들여쓰기를 적용합니다.
- 배열 응답은 최상위에 두지 말고 객체로 한 번 감싸는 편이 확장에 유리합니다.
JSON은 규칙이 적은 만큼 규칙을 어겼을 때의 대가가 분명합니다. 문법 여섯 가지와 오류 패턴 다섯 가지만 몸에 익혀두면 데이터 관련 삽질 시간의 상당 부분을 줄일 수 있습니다.