JSON 총정리가 필요한 이유는 단순합니다. JSON은 웹 API, 설정 파일, 데이터 저장까지 거의 모든 현대 개발 환경에서 표준 데이터 포맷으로 쓰이기 때문입니다. 문법은 단순해 보이지만 실제로는 따옴표, 자료형, 인코딩에서 사소한 실수가 자주 발생합니다. 이 글에서는 JSON의 구조부터 실무에서 마주치는 문제와 해결법까지 핵심만 정리합니다.
1. JSON이란 무엇인가
JSON은 JavaScript Object Notation의 약자로, 사람이 읽기 쉽고 기계가 파싱하기 좋은 텍스트 기반 데이터 교환 포맷입니다. 이름에 JavaScript가 들어가지만 언어에 종속되지 않으며, Python, Java, Go, PHP 등 거의 모든 언어에서 표준 라이브러리로 지원합니다.
JSON은 두 가지 기본 구조로 이루어집니다. 키와 값을 쌍으로 묶는 객체({})와 순서가 있는 값의 나열인 배열([])입니다. 이 둘을 중첩해 복잡한 데이터를 표현합니다.
2. JSON이 지원하는 6가지 자료형
JSON이 표현할 수 있는 값의 종류는 명확하게 정해져 있습니다. 이 범위를 벗어나는 값은 직렬화 과정에서 변환되거나 오류를 일으킵니다.
- 문자열(string): 큰따옴표로 감싼 텍스트. 예:
"hello" - 숫자(number): 정수와 실수. 따옴표 없이 표기. 예:
42,3.14 - 불리언(boolean):
true또는false - 널(null): 값이 없음을 의미하는
null - 객체(object): 키-값 쌍의 집합
{} - 배열(array): 값의 순서 있는 목록
[]
주의할 점은 JSON에 날짜 타입이 없다는 것입니다. 날짜는 보통 ISO 8601 형식의 문자열(예: "2026-05-19T09:00:00Z")로 표현하고, 파싱하는 쪽에서 다시 날짜 객체로 변환해야 합니다.
3. 자주 발생하는 JSON 오류와 해결법
실무에서 JSON 파싱이 실패하는 원인은 대부분 몇 가지로 압축됩니다. 아래 비교표로 정리했습니다.
| 오류 유형 | 잘못된 예 | 올바른 예 |
|---|---|---|
| 마지막 쉼표 | {"a":1,} | {"a":1} |
| 작은따옴표 사용 | {'a':1} | {"a":1} |
| 따옴표 없는 키 | {a:1} | {"a":1} |
| 주석 포함 | {"a":1 // 설명} | {"a":1} |
| 줄바꿈 미이스케이프 | {"a":"줄1줄2"} | {"a":"줄1\n줄2"} |
특히 JSON에는 주석 문법이 없다는 점을 기억해야 합니다. 설정 파일에 설명을 남기고 싶다면 별도의 설명용 키를 추가하거나 JSON5, JSONC 같은 확장 포맷을 사용해야 합니다. 다만 이들은 표준 JSON 파서에서는 동작하지 않습니다.
4. JSON 검증과 정렬하기
JSON을 다루다 보면 한 줄로 압축된 데이터를 받게 되는 경우가 많습니다. API 응답이나 로그에 찍힌 JSON은 사람이 읽기 어렵게 직렬화되어 있어, 구조를 파악하려면 들여쓰기를 적용해 정렬(pretty print)해야 합니다.
반대로 운영 환경에 데이터를 전송할 때는 공백을 제거한 압축(minify) 형태가 전송량을 줄여 유리합니다. 이렇게 들여쓰기를 적용하거나, 키를 정렬하거나, 문법 오류를 찾아내는 작업을 매번 손으로 하기는 번거롭습니다. 이런 작업을 자동화하려면 JSON 정렬기를 활용하면 구조 파악과 오류 검출을 빠르게 할 수 있습니다.
JSON.stringify(obj, null, 2), Python은 json.dumps(obj, indent=2, ensure_ascii=False)를 사용하면 됩니다. ensure_ascii=False를 빼면 한글이 유니코드 이스케이프로 깨져 보이니 주의하세요.5. 실무에서 지켜야 할 JSON 설계 원칙
JSON을 단순히 데이터를 담는 그릇으로만 보면 유지보수에서 어려움을 겪습니다. API를 설계하거나 설정 파일을 만들 때는 다음 원칙을 지키는 것이 좋습니다.
- 키 이름 규칙을 통일합니다. camelCase 또는 snake_case 중 하나를 정해 프로젝트 전체에서 일관되게 사용합니다.
- 구조를 깊게 중첩하지 않습니다. 3단계 이상 중첩되면 접근이 복잡해지므로 평탄화를 고려합니다.
- 널과 빈 값의 의미를 구분합니다.
null, 빈 문자열, 키 자체의 부재는 각각 다른 의미를 가질 수 있으므로 규칙을 문서화합니다. - 버전 필드를 둡니다. 스키마가 바뀔 가능성이 있다면
"version"같은 필드로 호환성을 관리합니다.
이러한 원칙은 데이터를 주고받는 양쪽 모두의 부담을 줄여 줍니다. JSON은 문법이 단순한 만큼 규칙을 강제하는 장치가 적어, 설계자의 일관성이 곧 데이터 품질로 이어집니다.
지금까지 JSON의 구조, 자료형, 자주 발생하는 오류, 검증과 정렬, 설계 원칙까지 핵심을 정리했습니다. JSON은 배우기 쉽지만 깊이 있게 다루려면 자료형의 한계와 직렬화 동작을 정확히 이해하는 것이 중요합니다. 이 정리가 데이터를 더 안전하게 다루는 기준점이 되기를 바랍니다.