JSON 오류 고치는 법: 자주 나는 문법 실수 7가지
API 응답이나 설정 파일을 붙여 넣었는데 "Unexpected token"이나 "JSON parse error"가 뜨면서 정확히 어디가 문제인지 알려 주지 않아 막막한 경험, 개발자라면 한 번쯤 있을 거예요. JSON은 JavaScript 객체와 생김새가 비슷해서 쓰다 보면 자바스크립트 방식으로 쓰게 되는데, JSON은 훨씬 엄격한 규칙을 가진 데이터 형식이에요. 이 글에서는 오류의 대부분을 차지하는 일곱 가지 실수와 고치는 법을 정리했어요.
1. 오류 한눈에 보기
| 번호 | 실수 | 잘못된 예 | 올바른 예 |
|---|---|---|---|
| 1 | 마지막 쉼표 | {"a": 1, "b": 2,} | {"a": 1, "b": 2} |
| 2 | 작은따옴표 | {'a': 'x'} | {"a": "x"} |
| 3 | 따옴표 없는 키 | {a: 1} | {"a": 1} |
| 4 | 주석 | {"a": 1 // 설명} | 주석 없이 {"a": 1} |
| 5 | 숫자 표기 | {"n": 007, "m": NaN} | {"n": 7, "m": null} |
| 6 | 문자열 안 줄바꿈·따옴표 | 문자열 안에 실제 줄바꿈 | "줄1\n줄2" 처럼 이스케이프 |
| 7 | 괄호·쉼표 짝 | {"a": [1, 2} | {"a": [1, 2]} |
2. 마지막 쉼표 (trailing comma)
가장 흔한 오류예요. 자바스크립트나 파이썬에서는 마지막 항목 뒤의 쉼표를 허용하는데, JSON은 허용하지 않아요. 항목 사이에만 쉼표가 있어야 해요.
{
"name": "피쿠",
"tools": 77,
} ← 77 뒤의 쉼표가 오류3. 작은따옴표와 따옴표 없는 키
JSON의 문자열과 키는 반드시 큰따옴표(")로 감싸야 해요. 작은따옴표나 따옴표 없는 키는 JavaScript에서는 되지만 JSON에서는 오류예요. 다른 언어에서 만든 데이터를 복사했다면 이 오류가 많아요.
{ 'name': '피쿠' } ← 작은따옴표 오류
{ name: "피쿠" } ← 키에 따옴표 없음4. 주석은 쓸 수 없어요
JSON 문법에는 주석이 없어요. // 한 줄 주석이나 /* */ 블록 주석을 넣으면 파싱 오류가 나요. 설정 파일에 주석이 꼭 필요하다면 JSON5나 JSONC처럼 주석을 허용하는 확장 형식을 쓰거나, "_comment" 같은 키에 설명을 문자열로 넣는 방법이 있어요.
JSON을 붙여 넣으면 문법 오류가 몇 번째 줄 몇 번째 칸인지, 원인이 무엇인지 한국어로 알려 줘요. 주석·작은따옴표가 섞인 글은 느슨하게 읽기로 표준 JSON으로 바꿔요.
JSON 포맷터·검증 열기 →5. 숫자와 특수 값 표기
- 앞자리 0은 안 돼요:
007은 오류예요. 숫자는7로 쓰거나 문자열"007"로 써요. - NaN, Infinity는 없어요: JSON에는 사용할 수 없는 값이에요. 값이 없다는 뜻은
null을 써요. - undefined도 없어요: JSON에 쓸 수 있는 값은 문자열, 숫자, 객체, 배열, true, false, null이에요. true, false, null은 반드시 소문자예요.
- 소수점은 앞뒤에 숫자가 필요해요:
.5나5.은 오류이고0.5로 써야 해요.
또 큰 숫자는 주의해야 해요. 자바스크립트 숫자는 9007199254740991(2⁵³−1)까지만 정확해서, 주문번호나 ID처럼 긴 숫자는 끝자리가 달라질 수 있어요. 이런 값은 문자열로 주고받는 것이 안전해요.
6. 문자열 안의 특수 문자는 이스케이프
문자열 안에 큰따옴표, 역슬래시, 줄바꿈을 그대로 넣으면 오류예요. 아래처럼 역슬래시로 시작하는 이스케이프로 써야 해요.
| 넣고 싶은 문자 | 쓰는 방법 |
|---|---|
| 큰따옴표 " | \" |
| 역슬래시 \ | \\ |
| 줄바꿈 | \n |
| 탭 | \t |
| 유니코드 문자 | \uAC00 같은 \u 표기 |
윈도우 경로(C:\Users\name)를 넣을 때가 특히 위험해요. 역슬래시를 두 번(C:\\Users\\name) 써야 해요.
7. 괄호와 쉼표의 짝이 안 맞을 때
중괄호 {}, 대괄호 []의 열고 닫음이 맞지 않거나, 항목 사이 쉼표가 빠진 경우예요. 긴 JSON에서는 눈으로 찾기 어려워요. 줄 번호와 칸 번호로 오류 위치를 알려 주는 검증 도구를 쓰면 몇 초 만에 찾을 수 있어요. 오류 위치는 문제의 "바로 뒤"를 가리킬 때가 많아서, 알려 준 위치의 앞쪽도 함께 살펴보세요.
8. 오류를 줄이는 습관
- 손으로 JSON을 쓰기보다 코드에서 직렬화 함수(
JSON.stringify등)로 만들어요. - 설정 파일은 편집기에서 JSON 문법 검사를 켜 두세요.
- 가져온 데이터를 붙여 넣기 전에 검증 도구로 확인하세요.
- 사람이 자주 고치는 설정 파일이라면 YAML처럼 주석을 쓸 수 있는 형식도 고려해 보세요. 두 형식은 JSON YAML 변환으로 서로 바꿀 수 있어요.
자주 묻는 질문
JSON과 JavaScript 객체는 어떻게 다른가요?
JavaScript 객체는 키에 따옴표를 생략하고 작은따옴표를 쓰고 마지막 쉼표와 주석도 허용돼요. JSON은 키와 문자열에 큰따옴표만 쓰고, 마지막 쉼표·주석·undefined·NaN을 허용하지 않아요.
"Unexpected token < in JSON at position 0"은 무슨 오류인가요?
보통 JSON을 기대했는데 HTML 페이지(<html>...)를 받았다는 뜻이에요. 주소가 틀렸거나 서버가 오류 페이지를 돌려준 경우가 많아요. 응답 원문을 먼저 확인하세요.
JSON 파일의 인코딩은 무엇이어야 하나요?
시스템 사이에 주고받는 JSON은 UTF-8이어야 한다고 표준에서 정하고 있어요. 한글이 깨진다면 파일을 UTF-8로 저장했는지 확인하세요.
들여쓰기나 공백은 상관없나요?
네. 토큰 사이의 공백과 줄바꿈은 자유로워서 보기 좋게 들여쓰거나 한 줄로 압축해도 같은 데이터예요. 다만 문자열 안의 공백은 값의 일부예요.
출처
이 글의 설명은 게시일 기준이에요. 도구와 규격은 업데이트될 수 있으니 중요한 작업 전에는 공식 문서를 확인하세요.