JSON 포매터 가이드 — 읽기, 검증, 디버깅
JSON은 모던 웹 API의 공통어입니다. 모든 설정 파일, fetch 응답, 웹훅 페이로드가 JSON으로 오갑니다. 이 가이드는 JSON의 정확한 문법, 사람들이 자주 걸려 넘어지는 규칙, 그리고 실제로 마주칠 에러들을 디버깅하는 방법을 정리합니다.
JSON(JavaScript Object Notation)은 2001년 더글러스 크록포드가 XML의 가벼운 대안으로 제안했습니다. 의도적으로 미니멀합니다 — 6가지 데이터 타입, 2개의 구조 문자, 주석 없음, 스키마 없음. 그 단순함 덕분에 모든 프로그래밍 언어가 수백 줄짜리 파서로 구현할 수 있고, 그래서 표준이 됐습니다.
기술적으로는 단순하지만, JSON은 숙련된 개발자도 자주 걸리는 규칙들이 있습니다. 마지막 콤마 금지. 키는 반드시 큰따옴표. 숫자에 leading zero 금지. 주석 금지. 포매터는 이런 실수를 가장 빨리 잡는 도구입니다 — 의심스러운 JSON을 붙여넣고 포맷하면, 에러 메시지가 정확한 문자 위치를 알려줍니다.
JSON의 6가지 데이터 타입
- string
- 큰따옴표로 감싼 유니코드 문자열. 특수 문자는 백슬래시로 이스케이프: \" \\ \n \u00A0 등.
- number
- 정수 또는 부동소수점. 표준 수학 표기. leading zero, NaN, Infinity, 16진수 모두 불허.
- boolean
- 소문자 true 또는 false. True/TRUE 같은 대문자 변형은 불허.
- null
- 소문자 null. 값의 부재를 표현.
- array
- 대괄호로 감싼 순서 있는 리스트. 다른 타입 혼합 가능. 마지막 콤마 금지.
- object
- 중괄호로 감싼 키-값 쌍. 키는 반드시 큰따옴표 문자열. {"name": "ada"} 가능, {name: "ada"} 불가.
흔한 JSON 파싱 에러와 해결
| 에러 | 원인 | 해결 |
|---|---|---|
| Unexpected token } in JSON | 배열/객체 마지막에 콤마 | 콤마 제거 |
| Unexpected token a in JSON | 키에 큰따옴표 누락 | "key": ... 형태로 감싸기 |
| Unexpected end of JSON input | 잘린 페이로드 | 닫는 괄호/따옴표 누락 — API 응답이 잘렸을 가능성 |
| Unexpected token ' in JSON | 작은따옴표 사용 | 큰따옴표로 변경 |
| Unexpected number | leading zero, hex, NaN/Infinity | leading zero 제거, hex는 10진수로, NaN은 null로 |
| Bad escaped character | 지원되지 않는 백슬래시 이스케이프 | 허용: \" \\ \/ \b \f \n \r \t \uXXXX. 이외엔 \\로 두 번 써야 |
프리티 프린트 vs 미니파이
프리티 프린트된 JSON은 들여쓰기와 줄바꿈을 넣어 사람이 읽기 쉽게 만듭니다. 미니파이된 JSON은 모든 선택적 공백을 제거해 페이로드를 20~60% 작게 만듭니다. 둘 다 정확히 같은 데이터 구조로 파싱되므로, 선택은 대상에 따라 다릅니다 — 통신 시에는 미니파이, 디버깅과 설정 파일은 프리티.
흔한 워크플로우: API 응답은 브라우저 콘솔에서 프리티로 보면서 디버깅하고, 운영 환경에서는 미니파이로 저장·전송. 대부분의 빌드 도구가 미니파이를 자동 처리합니다.
JSON처럼 보이지만 JSON이 아닌 것들
- •JSON5 — 주석·작은따옴표·trailing comma·hex 허용. 설정 파일에 편하지만 표준 JSON 파서는 거부합니다.
- •JSONC — 주석이 들어간 JSON. VS Code, TypeScript 내부에서 사용. 표준 파서는 못 읽음.
- •JavaScript 객체 리터럴 — 비슷해 보이지만 키 따옴표 없고 trailing comma 허용, undefined·함수 가능. JSON 파서로 못 보냅니다.
- •YAML — 비슷한 모양의 다른 포맷. 주석·여러 줄 문자열 지원, 들여쓰기에 민감.
- •JSONL / NDJSON — 한 줄에 한 JSON 객체. 파일 전체는 JSON이 아니지만 각 줄은 JSON. 로그 스트림에 자주 사용.
잘못된 페이로드 디버깅
- 1
전체를 그대로 붙여넣기
잘라서 넣지 마세요 — 자른 위치에 진짜 에러가 숨어 있을 수 있습니다. 모던 포매터는 에러 위치를 정확히 짚어줍니다.
- 2
에러 메시지의 줄·열 번호 확인
라인 번호 표시되는 에디터에서 그 위치로 이동하세요.
- 3
에러 위치 한 글자 앞을 확인
많은 JSON 에러는 실제 실수 다음 위치에서 보고됩니다. 닫는 괄호에서 에러가 났다면, 진짜 문제는 그 직전의 trailing comma인 경우가 많습니다.
- 4
전체 구조의 균형 확인
괄호 짝이 맞지 않으면 연쇄 에러가 발생합니다. 긴 페이로드 끝에서 에러가 나면, 실제 원인은 한참 위의 닫는 괄호 누락일 수 있습니다.
- 5
페이로드가 깨끗해 보이면 출처를 의심
일부 서버는 보안 가드 )]}',이나 UTF-8 BOM, HTML 에러 페이지로 JSON을 감싸서 보냅니다. 모두 파서를 혼란시킵니다.
자주 묻는 질문
JSON은 대소문자를 구별하나요?
구별합니다. true, false, null과 모든 키 이름이 대소문자 민감입니다. {"id": 1, "ID": 2}는 서로 다른 두 항목입니다.
왜 JSON은 주석을 지원하지 않나요?
의도적인 결정입니다. 크록포드는 사람들이 주석에 파싱 지시문을 넣는 걸 막기 위해 일부러 뺐습니다(XML에서 그게 문제였습니다). 주석이 필요하면 JSON5를 쓰거나, 파서가 무시할 별도 'comment' 필드를 두세요.
날짜는 어떻게 표현하나요?
JSON에는 날짜 타입이 없습니다. 관행은 ISO 8601 문자열: "2026-05-07T14:30:00Z". 양쪽 통신 당사자가 이 약속을 공유해야 합니다.
JSON 문서의 최대 크기는?
이론적 한도는 없지만, 파서마다 실용적 한도가 있습니다. 브라우저는 수백 MB까지 처리하고, 모바일은 보통 10~20MB에서 막힙니다. 매우 큰 데이터는 스트리밍 가능한 JSONL이 낫습니다.
여기에 붙여넣은 JSON이 어디로 전송되나요?
전송되지 않습니다. EllyTools 포매터는 브라우저 안에서만 파싱하고 재포맷합니다. 페이로드는 서버로 가지 않고 저장되지도 않습니다.