대부분의 JSON 파싱 오류를 일으키는 실수와 해결법

대부분의 JSON 파싱 오류는 몇 가지 흔한 실수에서 생겨요. 끝에 붙은 쉼표, 작은따옴표로 감싼 문자열, 주석, 따옴표 없는 키, NaN이나 undefined 같은 값, 문서에서 복사해 온 둥근 따옴표가 대표적이에요. JSON은 비슷하게 생긴 자바스크립트보다 훨씬 엄격해서, 사람 눈에는 멀쩡해 보이는 코드도 파서는 거부할 수 있어요. 오류 메시지에는 줄과 열 위치가 나오고, 대개 그 위치나 바로 앞에서 문제를 찾을 수 있어요.

JSON 포맷터JSON을 읽을 수 없어요무료로 사용하기

JSON이 지키도록 요구하는 규칙

JSON 문서는 값 하나예요. 중괄호로 감싼 객체, 대괄호로 감싼 배열, 문자열, 숫자, true, false, null 중 하나죠. 이 값들 안에서는 다음 규칙을 지켜야 해요.

• 모든 키와 문자열은 "name"처럼 큰따옴표로 감싸야 해요.
• 항목은 쉼표로 구분하고, 객체나 배열의 마지막 항목 뒤에는 쉼표를 붙이면 안 돼요.
• 숫자 앞에 더하기 기호를 쓸 수 없고, NaN, Infinity, undefined는 올바른 숫자나 값이 아니에요.
• 주석은 어떤 형태로도 허용되지 않아요.
• 키는 반드시 문자열이어야 해서, name: 처럼 따옴표 없는 키는 잘못된 형식이에요.

일부 파서는 기본적으로 이 중 몇 가지를 받아들이고, 일부 도구는 편의를 위해 주석이 달린 JSON도 받아줘요. 그런 관대함 때문에 문제가 숨어 있다가, 더 엄격한 프로그램이 파일을 읽을 때 드러나요. 그러니 처음부터 엄격한 형식으로 작성하세요.

오류 메시지 읽기

파서는 더 진행할 수 없었던 첫 지점을 보고해요. 메시지에는 문제가 무엇인지와 위치(보통 줄과 열)가 나와요. 다음은 배열 안과 마지막 속성 뒤에 쉼표가 하나씩 붙은 작은 파일이에요.

{
  "name": "Ada",
  "tags": ["a", "b",],
}

Python은 이 파일에 대해 "Illegal trailing comma before end of array: line 3 column 20"이라고 보고해요. 도구마다 표현은 다르고, 오래된 파서는 "Unexpected token"과 문자 위치만 알려주기도 해요. 보고된 위치로 가서 바로 앞 문자를 확인하세요. 실제 실수는 보고된 자리보다 한두 글자 앞의 쉼표, 따옴표, 중괄호인 경우가 많아요.

Python 파서에서 자주 보이는 메시지와 보통 의미하는 바는 다음과 같아요.

• '{'a': 1}'에서 "Expecting property name enclosed in double quotes"가 나오면 작은따옴표 키나 따옴표 없는 키가 있다는 뜻이에요.
• 숫자나 문자열이 와야 할 자리에서 "Expecting value"가 나오면 스마트 따옴표가 섞였을 가능성이 커요. 파서가 이를 알 수 없는 문자로 보기 때문이에요.
• "Expecting ',' delimiter"는 대개 두 항목 사이에 쉼표가 빠졌거나, 데이터 중간에 주석이 들어 있다는 뜻이에요.

스마트 따옴표와 복사한 텍스트

스마트 따옴표는 직선 따옴표와 거의 똑같아 보여서 가장 헷갈리는 경우예요. 워드 프로세서, 웹 페이지, 채팅 메시지에서 복사한 JSON 파일에는 둥근 큰따옴표가 들어 있을 수 있어요. 눈에는 제대로 보이지만 파서는 “x”를 문자열의 구분 기호가 아니라 알 수 없는 문자로 보기 때문에 파싱에 실패해요.

숨은 문자도 같은 종류의 실패를 일으켜요. 두 값 사이의 줄바꿈 없는 공백(non-breaking space)은 파서에게 공백이 아니에요. 손으로 구조를 고치기 전에 숨은 문자 제거를 먼저 실행하고, 그다음 따옴표를 고치세요. 둥근 따옴표 가이드에서 안전하게 직선 따옴표로 바꾸는 방법을 확인할 수 있어요.

작은따옴표, 주석, 따옴표 없는 키

여러 개발자는 더 많은 것을 허용하는 언어에서 JSON 비슷한 데이터를 작성해요.

• 작은따옴표는 자바스크립트와 파이썬 리터럴에서는 유효하지만, JSON은 큰따옴표를 요구해요. {'a': 1}은 {"a": 1}로 바꾸세요.
• //나 /* */ 같은 주석은 모두 지워야 해요. 메모가 필요하다면 별도의 필드에 넣거나, 설정 파일용으로 설계된 형식을 사용하세요.
• 따옴표 없는 키는 자바스크립트 객체 리터럴에서 흔해요. 따옴표를 붙이세요.
• NaN과 undefined는 JSON에 없어요. 값이 없으면 null을 쓰고, 값이 글자라면 문자열을 쓰세요.

일괄 찾아 바꾸기는 조심하세요. 작은따옴표를 모두 큰따옴표로 바꾸면 "Ada's notes"처럼 아포스트로피가 들어 있는 문자열이 깨져요. 먼저 찾아 바꾸기에서 일치하는 항목을 모두 미리 보고, 어떤 따옴표가 바뀌는지 확인하세요.

구조를 단계별로 고치기

1. 파일을 JSON 포맷터에 붙여 넣으세요. 포맷하면 구조가 보이고, 오류에 줄과 열이 함께 표시돼요. 그다음 Repair를 누르면 주석과 끝에 붙은 쉼표가 제거돼요. 다만 작은따옴표와 둥근 따옴표는 바꾸지 않으니 직접 고쳐야 해요.
2. 첫 번째 오류만 고친 뒤 다시 확인하세요. 실수 하나가 아래쪽에서 여러 오류를 만들 수 있어요.
3. 여는 중괄호와 대괄호마다 닫는 짝이 있는지, 그리고 중첩 구조가 의도한 대로인지 확인하세요.
4. 마지막으로 웹 도구뿐 아니라 애플리케이션이 쓰는 파서로도 파일을 검증하세요. 파서마다 조금씩 다르게 동작해요.

파싱이 된다고 해서 원래 의도한 파일이라는 보장은 없어요. 누락된 필드나 잘못된 자료형의 값을 찾으려면 JSON 스키마로 검증하고, 버전 사이에서 무엇이 바뀌었는지 보려면 두 JSON 문서를 비교하세요.

예외 상황

• 생성된 파일의 끝 쉼표. 일부 도구는 끝에 쉼표를 붙여 저장해요. 문자열을 직접 조립해 JSON을 만든다면, 언어의 직렬화 기능을 사용하세요. 올바른 출력을 만들어 줘요.
• 중복된 키. JSON은 중복 키를 허용하지만, 대부분의 파서는 마지막 값만 남겨요. 중복 키는 나중에 문제가 될 버그의 씨앗이에요.
• 큰 숫자. 아주 큰 정수는 일부 파서에서 정밀도를 잃을 수 있어요. 따라서 파서가 정확히 표현할 수 있는 범위를 넘는 식별자는 문자열로 저장하세요. CSV를 JSON으로 변환하는 가이드에서도 ID에 대해 같은 내용을 다뤄요.

빠른 답변

JSON이 맞아 보이는데 왜 실패하나요?

흔한 원인은 끝에 붙은 쉼표, 작은따옴표, 주석, 또는 문서에서 복사해 온 둥근 따옴표예요. 오류 메시지의 위치와 그 바로 앞 문자를 확인하세요.

JSON에 주석을 넣을 수 있나요?

아니요. JSON 표준은 주석을 허용하지 않아요. 주석을 지우거나, 메모를 별도의 필드로 옮기세요. 포맷터의 Repair 버튼이 주석을 대신 지워 줘요.

JSON에서 undefined 대신 무엇을 써야 하나요?

값이 일부러 비어 있다면 null을 쓰거나, 해당 키 자체를 빼세요. undefined는 자바스크립트의 값이라서 JSON으로 표현할 수 없어요.