JSON 포맷팅 완벽 가이드 - 자주 만나는 에러부터 검증까지

JSON이란 무엇인가?

JSON(JavaScript Object Notation)은 데이터를 사람이 읽기 쉽고 기계가 해석하기 쉬운 텍스트 형식으로 표현하는 포맷입니다. 2001년 더글라스 크록포드가 JavaScript의 객체 리터럴 문법에서 가져와 정의했고, 지금은 언어와 무관한 데이터 교환 표준이 되었어요. REST API의 응답, 설정 파일, 로그, 환경변수 저장 등 거의 모든 현대 애플리케이션에서 만나게 됩니다. XML 같은 이전 포맷보다 가볍고, key/value·배열·중첩 객체·기본형 값(문자열·숫자·불리언·null) 정도면 대부분의 데이터를 표현할 수 있어요. 그러나 JSON은 단순한 만큼 한 글자만 어긋나도 파서가 즉시 실패하기 때문에, 손으로 직접 쓸 때는 의외로 잔실수가 많이 납니다.

JSON의 기본 문법 6가지 규칙

JSON 파서가 받아들이는 형식은 매우 엄격합니다. 다음 6가지만 정확히 지키면 대부분의 에러를 예방할 수 있어요.

• 모든 키는 반드시 큰따옴표 로 감싸야 합니다. 작은따옴표나 따옴표 없는 식별자는 허용되지 않아요.
• 문자열 값도 큰따옴표로만 감쌉니다.
• 마지막 요소 뒤에 trailing comma 금지입니다. JavaScript 객체 리터럴은 허용해도 JSON은 안 됩니다.
• 주석은 사용할 수 없습니다. 한 줄 주석이든 블록 주석이든 모두 파싱 에러.
• 숫자는 따옴표 없이 그대로, 16진수·8진수·NaN·Infinity는 사용 불가.
• 진짜 데이터 외에는 어떤 문자도 들어가면 안 됩니다(예: 표시되지 않는 BOM, 트레일링 줄바꿈은 일부 파서에서 허용).

이 규칙은 JSON5나 HJSON 같은 변형 포맷에서는 완화되지만, 표준 JSON을 받는 시스템에서는 예외 없이 적용됩니다.

가장 자주 만나는 JSON 에러

실무에서 가장 자주 만나는 에러는 다음 5가지입니다.

• Unexpected token } / ]: 보통 trailing comma. 마지막 요소 뒤 콤마를 지우면 해결됩니다.
• Unexpected end of JSON input: 닫히지 않은 괄호. 중괄호·대괄호 짝이 맞는지 확인하세요.
• Unexpected token / unquoted key: 따옴표 종류가 잘못됐거나, 키가 따옴표 없이 적힌 경우.
• Bad control character in string: 문자열 안에 줄바꿈이 그대로 들어간 경우. 백슬래시 n으로 escape.
• Duplicate key: 같은 키를 두 번 적은 경우. 표준은 마지막 값을 채택하지만 일부 파서는 에러를 던집니다.

대형 JSON에서 위 에러를 만나면 라인 정보가 도움이 안 되는 경우가 많아요. 이때는 포맷터로 들여쓰기를 정리하면 어디서 깨졌는지 한눈에 보입니다.

JSON 포맷팅이 필요한 순간

API 응답이나 로그를 한 줄로 받으면 사람이 읽기 매우 어렵습니다. 포맷팅(pretty print)은 들여쓰기와 줄바꿈을 추가해 구조를 시각적으로 드러내는 작업이에요. 다음 같은 상황에서 특히 자주 필요합니다.

• 백엔드에서 받은 응답이 한 줄짜리 minified JSON일 때
• 콘솔 로그에 찍힌 JSON을 분석해야 할 때
• Git 커밋·코드 리뷰에서 JSON 변경점 비교할 때(들여쓰기가 일관되어야 diff가 깔끔)
• 설정 파일을 사람이 직접 편집할 때

포맷팅과 함께 minify(공백 제거)도 자주 필요합니다. 네트워크로 보낼 때는 minify해서 용량을 줄이고, 디버깅할 때는 포맷팅해서 읽기 좋게 만드는 식이에요.

안전한 JSON을 만드는 팁

손으로 JSON을 작성하는 일이 적어졌다고 해도, 설정 파일이나 mock 데이터에서는 여전히 자주 마주칩니다.

• 직접 쓰지 말고 언어의 직렬화 함수(JavaScript의 JSON.stringify, Python의 json.dumps)를 활용하세요. 사람이 손으로 쓴 JSON이 거의 항상 더 자주 깨집니다.
• 큰 JSON은 IDE의 JSON 모드에서 편집하면 trailing comma·괄호 짝을 IDE가 잡아줘요.
• 파일 저장 전 포맷터로 한 번 정리해두면 나중에 손으로 수정하다가 깨뜨리는 일이 줄어듭니다.
• 비밀번호·API 키 같은 민감 정보를 JSON에 넣을 때는 외부 시스템에 공유되는지 항상 의식하세요. minified로 줄여둔 채 깃허브에 올리는 사고가 의외로 많아요.

도구로 빠르게 검증하기

툴박스의 JSON 포맷터는 한 줄로 받은 JSON을 들여쓰기된 보기 좋은 형태로 변환하고, 문법 오류가 있으면 어떤 위치에서 깨졌는지 알려줍니다. 반대로 minify 모드로 한 줄로 압축할 수도 있어요. API 응답을 디버깅하거나, 외부에서 받은 JSON을 검증할 때 빠르게 사용할 수 있습니다. 정확한 오류 메시지를 알려주는 것만으로도 트러블슈팅 시간이 절반 이하로 줄어드니, 한 번 즐겨찾기해두면 두고두고 도움이 됩니다.

관련 가이드

kimgoon.kr

kimgoon 생활정보 가이드

tools.kimgoon.kr

개발자 도구 가이드 더 보기

tools.kimgoon.kr

툴박스 도구 모음