Toolvil 가이드
JSON 포맷·검증 제대로 하는 법
JSON이 한 줄로 길게 붙어 읽기 어렵거나, 'Unexpected token' 오류로 파싱이 막혀 본 적 있으신가요? JSON 문법의 핵심 규칙 몇 가지만 알면 오류 원인을 스스로 찾고, 포맷·검증까지 직접 할 수 있습니다.
JSON이란 무엇이고, 왜 문법이 엄격한가
JSON(JavaScript Object Notation)은 데이터를 사람이 읽을 수 있는 텍스트로 주고받기 위한 형식입니다. API 응답, 설정 파일, 웹훅 payload, 로그 등 거의 모든 곳에서 쓰입니다. 그런데 JSON은 문법이 매우 엄격해서, 쉼표 하나·따옴표 하나만 어긋나도 전체 파싱이 실패합니다. '대충 비슷하면 된다'가 통하지 않는다는 점이 처음 다루는 사람을 가장 많이 당황하게 합니다.
핵심은 이렇습니다. JSON은 자바스크립트 객체와 '닮았지만 같지 않습니다'. 자바스크립트 코드에서는 허용되는 표기가 JSON에서는 오류가 되는 경우가 많습니다. 그래서 콘솔에서 객체를 복사해 그대로 JSON으로 쓰면 십중팔구 막힙니다. 이 차이를 이해하는 것이 곧 'JSON 오류를 스스로 고치는 법'의 출발점입니다.
꼭 지켜야 할 JSON 문법 핵심 규칙
JSON에서 값으로 쓸 수 있는 타입은 객체({}), 배열([]), 문자열, 숫자, 불리언(true/false), null 여섯 가지뿐입니다. 이 위에서 반드시 지켜야 할 규칙을 표로 정리했습니다.
| 규칙 | 올바른 예 | 잘못된 예 |
|---|---|---|
| 키는 큰따옴표(" ")로 감싼다 | "name": "철수" | name: "철수" |
| 문자열도 큰따옴표만 허용 | "city": "서울" | 'city': '서울' (작은따옴표) |
| 마지막 항목 뒤 쉼표 금지 | ["a", "b"] | ["a", "b",] (후행 쉼표) |
| 주석을 넣을 수 없다 | (주석 없음) | // 설명, /* ... */ |
| undefined·함수는 값이 될 수 없다 | null 사용 | undefined, NaN |
표에서 보듯 가장 흔한 실수는 모두 '자바스크립트에서는 되는데 JSON에서는 안 되는' 것들입니다. 정리하면, 키와 문자열은 무조건 큰따옴표, 마지막 쉼표는 빼기, 주석은 쓰지 않기 — 이 세 가지만 몸에 익혀도 오류의 대부분이 사라집니다.
작은따옴표와 큰따옴표
자바스크립트에서는 '서울'과 "서울"이 모두 문자열이지만, JSON은 큰따옴표만 인정합니다. 작은따옴표로 감싼 값은 전부 오류입니다. 한글 문서나 엑셀에서 복사한 따옴표가 '둥근 따옴표(" ")'로 바뀌어 있는 경우에도 같은 오류가 나니, 보이는 모양이 비슷해도 일반 큰따옴표(")인지 확인해야 합니다.
후행 쉼표(trailing comma)
배열이나 객체의 마지막 항목 뒤에 붙은 쉼표는 JSON에서 허용되지 않습니다. 최신 자바스크립트는 후행 쉼표를 허용하기 때문에 습관적으로 붙이기 쉽지만, JSON으로 옮기면 그 자리에서 파싱이 실패합니다. 항목을 지우다가 쉼표만 남는 경우도 흔한 원인입니다.
자주 나는 오류와 원인 진단법
JSON 파서는 보통 Unexpected token ... in JSON at position N 형태로 오류를 알려 줍니다. 여기서 position N은 문제가 시작된 대략적인 글자 위치라서, 그 주변을 살피면 원인을 빠르게 좁힐 수 있습니다. 자주 만나는 패턴은 다음과 같습니다.
- 후행 쉼표 —
}나 ] 바로 앞에 쉼표가 남아 있는지 확인하세요. 가장 흔한 원인입니다. - 키 따옴표 누락 —
{ name: "값" }처럼 키에 큰따옴표가 없으면 오류입니다. { "name": "값" }으로 바꿔야 합니다. - 작은따옴표 사용 —
'를 모두 "로 바꿔야 합니다. - 괄호 짝 안 맞음 — 여는
{·[와 닫는 }·] 개수가 맞는지 봅니다. 들여쓰기를 입히면 한눈에 보입니다. - 주석 포함 — 설명을 위해 넣은
//나 /* */가 남아 있으면 제거해야 합니다.
오류 위치를 사람이 일일이 세기는 번거롭기 때문에, 보통은 들여쓰기를 먼저 입혀(포맷) 구조를 펼쳐 놓고 보는 편이 빠릅니다. 한 줄로 붙어 있던 JSON을 줄 단위로 펼치면 어느 줄의 쉼표·따옴표가 어긋났는지 눈으로 바로 잡힙니다. JSON 포맷터 & 뷰어에 붙여 넣으면 포맷과 동시에 오류 위치를 표시해 주고, 위에서 말한 흔한 실수는 한 번에 자동 수정할 수도 있습니다.
포맷(정렬)과 압축(minify)을 구분해 쓰기
JSON을 다룰 때 자주 쓰는 두 가지 변환이 '포맷'과 '압축'입니다. 둘은 데이터 내용은 그대로 두고 공백만 다르게 만드는 작업이라, 용도에 맞게 골라 쓰면 됩니다.
구분 하는 일 언제 쓰나 포맷(beautify) 들여쓰기·줄바꿈을 넣어 읽기 좋게 펼침 사람이 읽고 디버깅할 때, 코드 리뷰 압축(minify) 공백·줄바꿈을 모두 제거해 한 줄로 만듦 전송·저장 용량을 줄일 때, URL 파라미터
들여쓰기는 보통 2칸 또는 4칸을 씁니다. 여기에 '키 정렬'을 더하면 객체의 키가 알파벳 순으로 정돈돼, 두 JSON을 비교하거나 변경점을 찾을 때 편합니다. 다만 키 정렬은 객체의 키 순서만 바꾸고 배열 항목 순서는 그대로 둡니다 — 배열은 순서 자체가 의미를 갖는 경우가 많기 때문입니다.
깊은 중첩 구조 다루기
중첩이 깊은 JSON에서 원하는 값이 어디 있는지 찾기 어려울 때는 '트리 뷰'가 유용합니다. 객체와 배열을 접었다 펼 수 있어 전체 구조를 먼저 훑은 뒤 필요한 부분만 펼쳐 볼 수 있습니다. 특정 값의 위치는 data.users[0].email처럼 '접근 경로'로 표현하는데, 이 경로를 알면 코드에서 그 값을 바로 꺼내 쓸 수 있습니다.
안전하게 다루기 — 어디서 처리되는지 확인
JSON에는 API 키, 토큰, 개인정보 같은 민감한 값이 들어 있는 경우가 많습니다. 그래서 온라인 도구로 JSON을 다룰 때는 입력한 데이터가 서버로 전송되는지, 브라우저 안에서만 처리되는지를 반드시 확인하는 것이 좋습니다. 브라우저에서만 처리되는(로컬 처리) 도구라면 입력값이 외부로 나가지 않으므로, 민감한 JSON도 비교적 안심하고 다룰 수 있습니다.
그래도 공유 목적이라면 토큰·비밀번호 같은 값은 미리 지우거나 더미 값으로 바꾸는 습관을 들이세요. 포맷·검증은 어디까지나 '문법과 표시 형식'을 돕는 작업이지, 데이터 보안이나 스키마(필드 구조) 검증을 대신해 주지는 않습니다.
자주 막히는 부분
'Unexpected token' 오류는 무슨 뜻인가요?
파서가 그 위치에서 '여기 올 수 없는 글자'를 만났다는 뜻입니다. 보통 그 직전에 빠진 쉼표·따옴표, 또는 남아 있는 후행 쉼표가 원인입니다. 메시지의 position 숫자가 가리키는 부근을 먼저 살펴보세요. 들여쓰기를 입혀 구조를 펼치면 원인 줄이 훨씬 잘 보입니다.
자바스크립트 객체를 그대로 JSON으로 써도 되나요?
대부분 안 됩니다. 자바스크립트 객체는 키에 따옴표가 없어도 되고, 작은따옴표·후행 쉼표·주석·undefined를 허용하지만 JSON은 모두 금지합니다. 키와 문자열을 큰따옴표로 바꾸고, 후행 쉼표와 주석을 제거하고, undefined는 null로 바꿔야 유효한 JSON이 됩니다.
한글이 깨져 보이는데 JSON이 잘못된 건가요?
대개 문법 문제가 아니라 인코딩(글자 표시) 문제입니다. JSON 자체는 유니코드를 그대로 담을 수 있으므로, 파일을 UTF-8로 저장하고 같은 인코딩으로 여는지 확인하세요. 따옴표가 일반 큰따옴표(")가 아니라 둥근 따옴표(" ")로 바뀌어 있으면 그건 문법 오류이니 일반 따옴표로 교체해야 합니다.