JSON 포맷터
1. 데이터는 있는데, 읽을 수가 없어요
개발이나 테스트 환경에서 API 호출 응답을 확인하다 보면 종종 아래와 같은 형식의 데이터를 마주하게 됩니다.
{"user":{"id":10482,"name":"홍길동","roles":["admin","editor"],"settings":{"theme":"dark","notifications":{"email":true,"push":false},"language":"ko"}}}
분명 데이터는 다 들어있는데, 사람이 눈으로 읽기에는 너무나도 불편합니다. 어디서부터가 user 객체의 끝인지, roles는 배열인지 단순 문자열인지, settings 안에는 어떤 세부 항목들이 있는지 파악하려면 텍스트를 한참 동안 뚫어져라 쳐다봐야 합니다.
답답한 마음에 에디터에 복사해 두고 수동으로 엔터와 스페이스바를 쳐가며 들여쓰기를 하다가, 실수로 쉼표(,) 하나를 잘못 건드리거나 지워서 파싱 오류를 만들어본 경험은 개발자라면 누구나 한 번쯤 있을 것입니다.
이러한 피로도와 비효율성 때문에 개발자들에게 JSON 포맷터는 선택이 아닌 거의 필수적인 도구로 자리 잡았습니다. 저희는 수많은 포맷터 중에서도 "가장 직관적이고 사용성이 좋은 도구"가 되기 위해 화면 구성과 실시간 반영 속도에 많은 노력을 기울였습니다.
2. 도구 사용법 및 가이드
이 도구는 입력된 JSON의 문법을 실시간으로 검사하며 사용자가 원하는 들여쓰기 깊이에 맞춰 데이터를 재구성합니다.
a. JSON 데이터 입력 및 샘플 확인
화면 왼쪽의 '입력 패널'에 변환하고 싶은 JSON 텍스트를 붙여넣으세요. 직접 입력하거나 다른 곳에서 복사한 데이터를 넣는 즉시 오른쪽 결과 창에 정렬된 코드가 나타납니다. 만약 도구의 성능을 미리 테스트해보고 싶다면 상단의 Sample 버튼을 클릭합니다. 복잡한 중첩 구조와 배열이 포함된 예시 데이터가 자동으로 입력되어 어떻게 변환되는지 즉시 확인할 수 있습니다.
b. 들여쓰기 설정 및 스타일 조정
사용자의 취향이나 프로젝트 가이드라인에 맞춰 들여쓰기 너비를 조정할 수 있습니다. 결과 창 하단에 있는 옵션 버튼을 통해 설정합니다. 2칸 설정은 가장 대중적으로 사용되는 스타일로 화면 공간을 효율적으로 활용합니다. 4칸 설정은 가독성이 매우 뛰어나며 구조가 깊지 않은 데이터를 검토할 때 추천합니다. 탭(8칸) 방식은 엄격한 탭 구분이 필요한 환경에서 사용하기 좋습니다. 설정을 변경하는 즉시 우측의 결과 화면이 실시간으로 반영되어 최적의 시각적 편의를 제공합니다.
c. 복사 버튼으로 사용
원하는 스타일로 정렬이 완료되었다면, 결과 창 상단의 복사 버튼을 클릭해 보세요. 복잡하게 드래그할 필요 없이 단 한 번의 클릭만으로 깔끔하게 포맷팅된 전체 JSON 데이터가 클립보드에 복사됩니다. 사용자가 설정한 들여쓰기(2칸, 4칸 등)가 그대로 유지되므로, 코드 에디터나 API 문서, 슬랙 같은 메신저에 바로 붙여넣어 팀원들과 원활하게 공유할 수 있습니다.
3. JSON의 기본 구조와 데이터 타입
JSON(JavaScript Object Notation)은 2001년 더글러스 크록포드(Douglas Crockford)가 제안한 경량 데이터 교환 형식입니다. 이름에 JavaScript가 들어있지만 언어에 독립적인 텍스트 기반 형식으로, 오늘날 웹 API의 사실상 표준이 되었습니다.
JSON이 XML을 대체하게 된 가장 큰 이유는 가독성과 파싱 비용입니다. 동일한 데이터를 XML로 표현하면 태그 중복으로 인해 용량이 2~3배 커지고, 파서 구현도 훨씬 복잡합니다.
a. 6가지 기본 타입
JSON은 딱 6가지 타입만 허용합니다. 이 단순함이 JSON의 강점이자 제약이기도 합니다.
| 타입 | 설명 | 예시 |
|---|---|---|
string | 큰따옴표로 감싼 유니코드 문자열 | "hello", "한글" |
number | 정수 또는 부동소수점 (64비트 IEEE 754) | 42, 3.14, -7 |
boolean | 참/거짓 리터럴 | true, false |
null | 값 없음을 명시적으로 표현 | null |
object | 키-값 쌍의 집합 | {"key": "value"} |
array | 순서 있는 값의 목록 | [1, "a", true] |
b. JSON과 JavaScript 객체 리터럴의 차이
JSON은 JavaScript 객체 리터럴보다 훨씬 엄격합니다. 이 차이를 모르면 직접 작성한 JSON이 계속 파싱 오류를 일으킵니다.
| 규칙 | JSON | JavaScript 객체 리터럴 |
|---|---|---|
| 키 따옴표 | 반드시 큰따옴표 " 필수 | 따옴표 없이 작성 가능 |
| 문자열 따옴표 | 반드시 큰따옴표 " 필수 | 작은따옴표 ' 허용 |
| 후행 쉼표 | 허용 안 됨 | 허용 |
| 주석 | 허용 안 됨 | //, /* */ 허용 |
undefined 값 | 없음 | 존재 |
| 함수 값 | 불가 | 가능 |
Note
JSON5, JSONC(JSON with Comments)는 주석과 후행 쉼표를 허용하는 JSON 확장 형식입니다. VS Code의 settings.json이나 TypeScript의 tsconfig.json은 실제로 JSONC 형식을 사용합니다. 표준 JSON 파서로는 이 파일들을 직접 파싱할 수 없습니다.
c. JSON의 한계와 떠오르는 대안, YAML
JSON은 데이터 교환 형식으로는 훌륭하지만, 사람이 직접 작성하고 관리해야 하는 '설정 파일(Configuration)'로 사용할 때는 몇 가지 뚜렷한 한계가 있습니다. 가장 큰 단점은 주석을 달 수 없다는 것입니다. 설정의 의미나 변경 이력을 파일 내에 기록할 수 없죠. 또한 무조건 큰따옴표를 써야 하고 후행 쉼표가 불가능하다는 엄격한 문법도 번거로움을 유발합니다.
이러한 JSON의 한계를 극복하며 클라우드 네이티브 시대에 급부상한 포맷이 바로 YAML(YAML Ain't Markup Language)입니다.
- 뛰어난 가독성: 중괄호
{}나 쉼표 없이 들여쓰기만으로 데이터 계층 구조를 직관적으로 표현합니다. - 주석 지원:
#기호를 사용해 코드에 상세한 설명을 덧붙일 수 있습니다. - 유연한 문법: 여러 줄의 문자열을 표현하기 쉽고 덜 엄격한 규칙을 가집니다.
이런 장점 덕분에 Docker, Kubernetes, GitHub Actions 등 대부분의 최신 인프라 및 CI/CD 환경에서는 설정 파일로 JSON 대신 YAML을 표준처럼 사용합니다. (물론 서버 간 통신이나 브라우저 응답에서는 여전히 파싱 속도가 빠른 JSON이 압도적으로 쓰입니다.)
4. 실무에서 JSON을 다루는 상황들
단순한 문법적 특징을 넘어 실제 현업에서는 어떤 상황에 JSON이 적극적으로 활용될까요?
- 서버와 클라이언트 간의 데이터 송수신 (RESTful API, GraphQL)
웹이나 모바일 앱에서 서버에 데이터를 요청할 때, 서버는 데이터베이스에서 조회한 결과를 주로 JSON 형태로 묶어서 내려줍니다. 데이터 용량이 가볍고, 거의 모든 프로그래밍 언어에서 기본적으로 JSON 파싱 라이브러리를 지원하기 때문입니다. - 데이터 형식 변환 및 시각화 (CSV to JSON)
기획자나 마케터가 엑셀로 작업한 방대한 CSV 데이터를 웹 페이지의 차트나 그래프로 그려야 할 때가 있습니다. 이때 프론트엔드 환경에서 쉽게 다룰 수 있도록 백엔드에서 CSV 파일을 읽어 들여 JSON 배열 객체로 변환하는 파이프라인을 구축하곤 합니다. - 비정형 문서의 규격화 (PDF, HWP 파일 처리)
사용자가 업로드한 PDF, HWP 문서나 이미지(OCR)에서 텍스트를 추출해 시스템에서 활용해야 하는 경우가 있습니다. 추출된 파편화된 데이터들을{ "title": "문서제목", "date": "2024-05-07", "content": "..." }와 같은 JSON 포맷으로 규격화해버리면, 이후 데이터베이스에 저장하거나 다른 외부 API 서비스로 전달하고 가공하는 과정이 훨씬 단순하고 매끄러워집니다.
5. 이럴 때 JSON 파싱이 왜 안 될까
"분명히 맞는 것 같은데" 파싱 오류가 나는 상황들은 대부분 패턴이 정해져 있습니다. 이를 간략하게 정리해두었습니다.
a. 후행 쉼표(Trailing Comma)
JavaScript에서는 허용되지만 JSON 표준에서는 엄격히 금지됩니다.
// ❌ 파싱 오류 — 마지막 항목 뒤 쉼표
{
"name": "홍길동",
"role": "admin",
}
// ✅ 올바른 형태
{
"name": "홍길동",
"role": "admin"
}
b. 작은따옴표 사용
JSON 문자열과 키는 반드시 큰따옴표만 사용해야 합니다.
// ❌ 파싱 오류 — 작은따옴표 사용
{'name': '홍길동'}
// ✅ 올바른 형태
{"name": "홍길동"}
c. 주석 포함
JSON은 주석을 지원하지 않습니다. 주석이 포함된 파일은 .jsonc 확장자를 사용하거나 파싱 전에 제거해야 합니다.
// ❌ 파싱 오류 — 주석 포함
{
// 사용자 정보
"name": "홍길동"
}
// ✅ 올바른 형태
{
"name": "홍길동"
}
d. undefined 값 직렬화 누락
JavaScript의 JSON.stringify()는 undefined 값을 가진 키를 자동으로 제거합니다. 이로 인해 예상치 못하게 데이터가 누락될 수 있습니다.
// ❌ 의도치 않은 키 누락
JSON.stringify({ name: '홍길동', role: undefined })
// → '{"name":"홍길동"}' ← role 키가 사라짐
// ✅ 명시적으로 null 사용
JSON.stringify({ name: '홍길동', role: null })
// → '{"name":"홍길동","role":null}'
e. 오류의 공통점
위 모든 오류의 공통점은 JavaScript에서 허용하는 관대한 문법을 JSON에서도 쓸 수 있다고 착각하는 것입니다. JSON은 의도적으로 단순하고 엄격하게 설계되었습니다. 직접 작성한 JSON은 반드시 포맷터로 검증하는 습관을 들이면 이런 실수를 사전에 차단할 수 있습니다.
6. 생각해볼 거리
JSON이 XML을 밀어낸 진짜 이유는 무엇일까요?
단순히 가독성만의 문제는 아닙니다. 2000년대 초 AJAX의 부상으로 웹 브라우저에서 비동기 데이터를 처리하는 수요가 폭발했고, JavaScript 엔진에서 XML을 파싱하는 비용이 JSON보다 훨씬 컸습니다. 또한 JavaScript 객체와 1:1 대응되는 JSON 구조는 별도의 매핑 로직 없이 바로 사용할 수 있었습니다. 기술적 우위와 생태계의 타이밍이 맞아떨어진 결과입니다.
JSON에는 날짜/시간 타입이 없습니다. 어떻게 처리하는 것이 좋을까요?
JSON 표준 자체에는 날짜 타입이 없어서 문자열이나 숫자(Unix 타임스탬프)로 표현합니다. 업계 사실상 표준은 ISO 8601 형식의 문자열(예: "2024-01-15T09:30:00Z")입니다. JavaScript의 JSON.stringify()도 Date 객체를 이 형식으로 자동 변환합니다. 단, 역직렬화 시에는 자동으로 Date 객체로 변환되지 않으므로 명시적 처리가 필요합니다.
JSON이 항상 최선의 선택일까요? 다른 형식은 언제 써야 할까요?
대용량 데이터나 네트워크 비용이 중요한 환경에서는 Protocol Buffers(protobuf)나 MessagePack 같은 이진 직렬화 형식이 훨씬 효율적입니다. 설정 파일에는 주석을 지원하는 YAML이나 TOML이 더 적합한 경우도 있습니다. JSON은 사람이 읽고 쓰기 쉬운 범용 교환 형식으로서의 가치가 있지만, 성능이 중요한 내부 시스템에서는 목적에 맞는 형식을 선택하는 것이 좋습니다.
브라우저 탭 하나로 압축된 JSON을 사람이 읽을 수 있는 구조로 즉시 변환하고 문법 오류까지 바로 잡아낼 수 있습니다. API 디버깅부터 설정 파일 검토까지, 복사-붙여넣기 한 번으로 줄어드는 마찰은 작지 않습니다. 그것만으로도 이 도구의 역할은 충분하다고 생각합니다.