JSON이 중요한 이유
JSON(JavaScript Object Notation)은 웹 데이터 교환의 표준어가 되었습니다. API 응답이 JSON이고, 설정 파일이 JSON이며, 데이터베이스에도 JSON이 들어갑니다. 소프트웨어와 조금이라도 관련된 일을 한다면 매일 JSON을 접하게 됩니다. 그리고 JSON이 깨지면, 그 뒤에 연결된 모든 것이 함께 깨집니다.
형식 자체는 단순합니다. 키-값 쌍의 객체, 배열, 문자열, 숫자, 불리언, null. 하지만 단순하다고 에러가 안 나는 건 아닙니다. 쉼표 하나, 이스케이프 안 된 따옴표 하나가 유효한 JSON을 알 수 없는 파싱 에러로 바꿔 놓습니다.
흔한 JSON 에러와 해결법
후행 쉼표
가장 빈번한 에러는 후행 쉼표입니다. JavaScript에서는 배열과 객체 끝에 쉼표가 허용되기 때문에, JSON을 직접 작성할 때 이 습관이 자연스럽게 따라옵니다. 하지만 JSON 사양은 후행 쉼표를 엄격히 금지합니다.
```json // 잘못됨 — "blue" 뒤 쉼표 { "colors": ["red", "green", "blue",] }
// 올바름 { "colors": ["red", "green", "blue"] } ```
작은따옴표
JSON은 문자열과 키 모두 큰따옴표만 허용합니다. JavaScript나 Python에서 유효한 작은따옴표는 JSON에서 즉시 파싱 실패를 일으킵니다.
이스케이프 안 된 특수 문자
JSON 문자열 안에서 큰따옴표(`\"`), 백슬래시(`\\`), 줄 바꿈(`\n`), 탭(`\t`) 등은 반드시 이스케이프해야 합니다. 일반 텍스트를 JSON 값에 그대로 붙여 넣으면 에러가 납니다.
주석
JSON은 주석을 지원하지 않습니다. `//`도 `/* */`도 안 됩니다. 설정 파일에 주석이 필요하다면 JSONC나 YAML을 고려하세요.
압축된 JSON 포맷팅
프로덕션 API는 보통 공백을 모두 제거한 압축 JSON을 반환합니다. 기계에게는 효율적이지만 사람이 읽기에는 불가능에 가깝습니다. 500자짜리 한 줄 JSON도 들여쓰기를 적용하면 즉시 구조가 보입니다.
좋은 포맷터는 공백만 추가하는 게 아닙니다. 파싱하면서 구조를 검증하고, 뒤에서 시간 낭비할 에러를 미리 잡아주며, 중첩된 섹션을 접었다 펼 수 있게 해줍니다.
들여쓰기 스타일은 취향 차이입니다. 스페이스 2칸, 4칸, 탭 — 프로젝트 안에서만 일관되면 됩니다.
중첩 JSON 다루기
API 응답에서 5~6단계 깊이의 중첩은 흔합니다. 사용자 객체 안에 주소가 있고, 주소 안에 좌표가 있고, 좌표 안에 위도와 경도가 있는 식입니다. 압축된 상태에서 이걸 탐색하는 건 사실상 불가능합니다.
중첩 JSON을 디버깅할 때는 바깥에서 안쪽으로 진행하세요. 최상위 구조를 먼저 확인하고, 필요한 경로로 파고드는 방식입니다.
JSON 압축(Minification)
포맷팅의 반대가 압축입니다. 불필요한 공백을 모두 제거해서 가능한 가장 작은 형태로 만듭니다. 네트워크로 전송하거나, 크기 제한이 있는 DB 필드에 저장하거나, URL 쿼리 파라미터에 삽입할 때 필요합니다.
잘 구성된 50KB JSON 파일이 압축하면 35KB까지 줄어들 수 있습니다. 수백만 요청을 처리하는 API에서는 이 차이가 상당한 대역폭 절감으로 이어집니다.
JSON 스키마 검증
문법 검증을 넘어, JSON Schema를 사용하면 데이터가 특정 구조 요구 사항을 충족하는지 확인할 수 있습니다. 필수 필드 존재 여부, 값의 범위, 배열 최소 요소 수, 문자열 패턴 매칭 등을 강제할 수 있습니다.
스키마 검증은 문법 검증이 놓치는 에러를 잡습니다. JSON이 문법적으로는 완벽하지만 의미적으로 틀린 경우 — 형식은 맞는데 데이터가 잘못된 경우 — 는 스키마 없이는 감지할 수 없습니다.
맥락별 JSON 활용
API 개발
API를 만들거나 사용할 때, 일관된 JSON 포맷팅은 디버깅을 수월하게 만듭니다. 키 이름 규칙(camelCase vs snake_case), 날짜 형식(ISO 8601), null 처리 방식을 팀 내에서 통일하세요.
설정 파일
JSON 설정 파일은 키를 알파벳순으로 정렬하면 설정을 찾기 쉽고, 버전 관리에서 머지 충돌도 줄어듭니다.
데이터 처리
대용량 JSON 데이터셋은 스트리밍 파서로 메모리에 한꺼번에 올리지 않고 처리할 수 있습니다. 작은 파일이라면 출력을 포맷팅해서 확인하는 게 날것 그대로 스캔하는 것보다 훨씬 빠릅니다.
실용 팁
JSON 포맷터를 브라우저 즐겨찾기에 추가하세요. API가 에러를 반환하면 응답을 먼저 포맷터에 넣어 구조화한 다음 읽으세요. 텍스트 벽을 눈으로 훑는 것보다 항상 빠릅니다.
JSON을 프로그래밍으로 생성할 때는 반드시 직렬화 라이브러리를 사용하세요. 문자열 연결로 JSON을 만들면 이스케이프 에러, 인코딩 문제, 겉보기엔 괜찮지만 엣지 케이스에서 실패하는 잘못된 출력이 나올 수 있습니다.