"API 응답에 JSON이라는데, 정확히 뭐죠?"

JSON(JavaScript Object Notation)은 데이터를 텍스트로 표현하는 포맷입니다. 1999년 Douglas Crockford가 제안한 이후, XML을 밀어내고 현재는 REST API·설정 파일·로그·DB의 사실상 표준이 됐습니다. 이번 글에서는 JSON의 문법, 흔한 에러, 실무 활용 패턴을 정리합니다.

JSON 문법 기초

JSON은 6가지 타입만 지원합니다. 문자열·숫자·불리언·null·객체·배열. 함수·날짜·undefined·NaN은 없습니다.

{
  "name": "김철수",
  "age": 30,
  "isActive": true,
  "email": null,
  "hobbies": ["책", "러닝", "코딩"],
  "address": {
    "city": "서울",
    "district": "강남구"
  }
}

JSON의 6가지 규칙

1. 문자열은 반드시 큰따옴표 — 작은따옴표 X
2. 키도 큰따옴표로 감싸기 — JavaScript 객체와 다름
3. 마지막 쉼표 금지(trailing comma) — 배열·객체 모두
4. 주석 불가 — // 또는 /* */ 모두 X
5. 16진수·8진수 숫자 불가 — 0x, 0o 금지
6. Infinity·NaN 불가 — 숫자만 허용

흔한 JSON 에러 TOP 10

① Unexpected token 또는 SyntaxError

가장 흔한 에러. 주로 작은따옴표 사용·마지막 쉼표·닫히지 않은 괄호. 에디터에서 JSON 포매터로 열어보면 즉시 찾습니다.

② 키에 따옴표 없음

// 잘못
{ name: "김철수" }
// 올바름
{ "name": "김철수" }

③ 단일 따옴표 사용

// 잘못
{ 'name': '김철수' }
// 올바름
{ "name": "김철수" }

④ Trailing Comma (마지막 쉼표)

// 잘못
{ "a": 1, "b": 2, }
// 올바름
{ "a": 1, "b": 2 }

⑤ 주석 삽입

JSON은 주석 불가. 대안: JSON5 또는 JSONC (VSCode 설정 파일 등). 일반 JSON에서는 주석 필요 시 별도 필드(__comment)를 쓰는 편법도 있음.

⑥ 이스케이프 미처리

// 문자열 안의 따옴표는 백슬래시로 이스케이프
{ "text": "그가 \"안녕\"이라고 말했다" }
// 개행 문자
{ "text": "첫 번째 줄\n두 번째 줄" }

⑦ BOM 또는 인코딩 문제

Windows 메모장이 UTF-8 BOM을 추가하는 경우. UTF-8(BOM 없음)으로 저장 필수.

⑧ 날짜 타입

JSON엔 Date 타입 없음. 관례적으로 ISO 8601 문자열 사용: "2026-04-23T15:00:00+09:00"

⑨ 큰 숫자 정밀도

64비트 정수(2^53 초과)는 손실 가능. 큰 ID는 문자열로 전달. 예: Twitter snowflake ID는 문자열로 직렬화.

⑩ undefined 직렬화

JSON.stringify({ a: undefined }) // '{}' — 키 사라짐
JSON.stringify({ a: null })      // '{"a":null}'

JSON 실무 활용 패턴

① REST API 요청·응답

fetch('/api/user', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: '김철수', age: 30 })
})
.then(res => res.json())
.then(data => console.log(data))

② 환경설정 (package.json, tsconfig.json)

Node·TypeScript 프로젝트의 설정 파일. 대부분 주석 필요 없어 순수 JSON.

③ 로컬스토리지

// 저장
localStorage.setItem('user', JSON.stringify({ name: '김철수' }))
// 읽기
const user = JSON.parse(localStorage.getItem('user') || '{}')

④ 로그·분석 이벤트

구조화 로그(Structured Logging). Elasticsearch·BigQuery에 잘 맞습니다.

⑤ 설정 파일 동기화

Git에서 diff 보기 쉬움. YAML보다 파서 구현이 단순해 보안·성능 유리.

JSON 포매터·검증기 사용 팁

• 미니파이 — 공백 제거로 전송 크기 축소 (네트워크·스토리지 절약)
• 프리티파이 — 들여쓰기 적용으로 가독성 향상 (디버깅)
• 스키마 검증(JSON Schema) — 구조 규칙 정의 및 자동 검증
• 하이라이트 — 색상 구분으로 키·값·타입 시각화
• diff 도구 — 두 JSON 비교 시 트리 기반 비교 도구 사용

JSON vs YAML vs TOML — 언제 무엇을?

용도	추천	이유
API 교환	JSON	표준, 파싱 빠름
설정 파일(복잡)	YAML	주석·가독성
간단 설정	TOML	명확한 문법
대용량 데이터	JSONL / NDJSON	라인별 처리

JSON 무료 포매터

JSON 포매터 사용하기 →

참고
• RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format.
• JSON Schema Specification (draft 2020-12).
• Douglas Crockford. JavaScript: The Good Parts.