JSON5에서 JSONC까지: 더 관대한 JSON 포매팅 경험 만나기
엄격한 JSON이 쉼표 하나 때문에 한밤중에 디버깅을 하게 만든다면, 이제는 조금 더 관대한 사촌 격인 JSON5와 **JSON with Comments (JSONC)**를 만나볼 때입니다.
JSON5란 무엇인가요?
JSON5(ES5 호환 JSON 확장)는 ECMAScript 5.1의 기능을 도입한 JSON 확장으로, 따옴표 없는 키, 후행 쉼표, 홑따옴표 문자열, 주석, 16진수 숫자를 지원합니다. 커뮤니티가 관리하며, 손으로 작성하는 설정 파일을 엄격한 JSON보다 읽기 쉽고 관대하게 만드는 것을 목표로 합니다.
JSONC란 무엇인가요?
JSONC(주석이 포함된 JSON)는 표준 JSON에 한 줄 주석(//)과 여러 줄 주석(/* */), 그리고 후행 쉼표 지원을 더한 최소한의 확장입니다. Microsoft가 관리하며, VS Code 설정 파일과 tsconfig.json을 비롯한 TypeScript 설정 파일의 기본 형식입니다.
”관대한” JSON이 필요한 이유
- 가독성의 병목: 표준 JSON은 주석, 후행 쉼표, 홑따옴표 등을 금지하기 때문에 설정 파일이나 예제 코드에서 의도를 전달하기 어렵습니다.
- 팀 협업의 고통: 설명 주석이 전혀 없는 거대한 JSON 파일은 유지보수가 어렵고, 작은 수정 하나가 파일 전체를 망가뜨릴 수 있습니다.
- DevOps 현실: Kubernetes와 CI/CD 파이프라인은 JSON을 실시간으로 병합하거나 생성하는 일이 잦습니다. 관대한 문법은 수동 수정 작업을 크게 줄여 줍니다.
JSON5와 JSONC 한눈에 비교
| 기능 | JSON(엄격) | JSON5 | JSONC |
|---|---|---|---|
// 한 줄 주석 | 불가 | 지원 | 지원 |
/* */ 여러 줄 주석 | 불가 | 지원 | 지원 |
| 후행 쉼표 | 불가 | 지원 | 지원 |
| 홑따옴표 문자열 | 불가 | 지원 | 불가 |
| 따옴표 없는 키 | 불가 | 지원 | 불가 |
숫자 부호 + / - | 불가 | 지원 | 불가 |
| 16진수 / 2진수 숫자 | 불가 | 지원 | 불가 |
| 명세 관리 주체 | ECMA | 커뮤니티(A. Rauschmayer) | Microsoft / VS Code |
한 문장으로 요약하면: JSON5는 JavaScript 객체 리터럴처럼 느껴지는 반면, JSONC는 표준 JSON에 주석을 더한 것일 뿐입니다.
문법 예제
일반 JSON(엄격)
{
"name": "Go Tools",
"features": ["Base64", "JSON Formatter"]
}JSON5 예제
// 프로젝트 설정
{
name: 'Go Tools', // 홑따옴표와 따옴표 없는 키
features: [
'Base64',
'JSON Formatter', // 후행 쉼표
],
version: 1.0, // 문자열이 아닌 숫자 허용
}JSONC 예제
{
// 프로젝트 이름
"name": "Go Tools",
// 기능 목록
"features": [
"Base64",
"JSON Formatter", // 후행 쉼표
]
}포매팅 및 파싱 지원
| 시나리오 | JSON5 | JSONC | 권장 라이브러리 / 도구 |
|---|---|---|---|
| 브라우저 | JSON5.parse() 폴리필, Prettier 내장 json5 파서(v1.13 이상) | VS Code settings.json 기본 지원 | — |
| Node.js | json5 npm 패키지 | comment-json, jsonc-parser | CLI 포매팅 및 AST 파싱 지원 |
| IDE | VS Code, WebStorm 확장 프로그램 | VS Code 기본 지원, WebStorm 플러그인 | Prettier로 포매팅 통일 가능 |
| CI / 린트 | eslint-plugin-json5 | eslint-plugin-jsonc | Husky, lint-staged와 연동 |
| 온라인 도구 | Go Tools JSON 포맷터(JSON5/JSONC 정렬 및 유효성 검사) | 동일 | JSON 포맷터 |
VS Code 빠른 포매팅
settings.json에 다음을 추가합니다.
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}그다음 Alt + Shift + F를 누르면 어떤 JSONC 파일이든 예쁘게 정렬됩니다.
실전 설정 파일
JSON5와 JSONC는 이미 일상적으로 마주치는 설정 파일에서 폭넓게 쓰이고 있습니다. 구체적인 예시를 살펴보겠습니다.
TypeScript (tsconfig.json — JSONC)
{
// 엄격 모드는 컴파일 시점에 더 많은 버그를 잡아 줍니다
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "ESNext",
"outDir": "./dist",
// import 경로를 깔끔하게 만드는 경로 별칭
"paths": {
"@/*": ["./src/*"],
"@tests/*": ["./tests/*"],
},
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"],
}TypeScript의 tsconfig.json은 JSONC를 기본으로 사용합니다. 주석과 후행 쉼표가 별다른 설정 없이 바로 동작합니다. 모든 JavaScript/TypeScript 프로젝트에서 가장 흔하게 볼 수 있는 JSONC 파일 중 하나입니다.
ESLint Flat Config (eslint.config.json — JSONC)
{
"rules": {
// console.log는 경고하되, console.error는 허용
"no-console": ["warn", { "allow": ["error", "warn"] }],
"semi": ["error", "always"],
"quotes": ["error", "double"],
}
}Babel (babel.config.json5 — JSON5)
{
// 홑따옴표와 따옴표 없는 키로 가독성이 올라갑니다
presets: [
['@babel/preset-env', {
targets: '> 0.25%, not dead',
modules: false, // 모듈 처리는 번들러에 맡김
}],
],
plugins: [
'@babel/plugin-transform-runtime',
],
}VS Code 워크스페이스 설정 (.vscode/settings.json — JSONC)
{
// 에디터 환경 설정
"editor.fontSize": 14,
"editor.tabSize": 2,
"editor.formatOnSave": true,
// 언어별 개별 설정
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
}실무 팁과 주의사항
1. 배포 전에 변환하기
브라우저의 JSON.parse는 여전히 엄격한 JSON을 요구합니다. 빌드 단계 도구로 주석과 후행 쉼표를 제거하시기 바랍니다.
// Node.js 빌드 스크립트: JSON5 설정을 엄격한 JSON으로 변환
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';
const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));번들러 환경이라면 rollup-plugin-json5나 vite-plugin-json5를 사용해 빌드 과정에서 변환을 자동으로 처리할 수 있습니다.
2. 보안과 신뢰성
관대한 문법은 의도하지 않은 필드를 감출 수 있습니다. 설정을 사용하기 전에 반드시 JSON Schema나 zod로 유효성 검사를 수행하시기 바랍니다.
// 파싱 후 zod로 설정 형태의 유효성 검사
import { z } from 'zod';
import JSON5 from 'json5';
const ConfigSchema = z.object({
port: z.number().min(1).max(65535),
host: z.string(),
debug: z.boolean().default(false),
});
const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // 유효하지 않으면 예외 발생3. 팀 규칙
- README에
*.json5는 설정 용도로만 사용하고, 배포 패키지는 엄격한.json으로 제공한다고 명시합니다. - Prettier 규칙을 표준화해 불필요한 diff 잡음을 줄입니다.
.editorconfig로 JSON, JSON5, JSONC 파일 전반의 들여쓰기를 일관되게 유지합니다.
4. 성능
JSON5/JSONC 파싱은 의존성과 약간의 오버헤드를 추가합니다. CLI나 개발 도구에서는 문제가 없지만, 운영 환경에서는 실제 측정을 권장합니다. json5 npm 패키지는 최소화(minify) 기준 약 8 KB이며, 파싱 속도는 네이티브 JSON.parse보다 약 2~5배 느립니다. 시작 시점에 한 번 로드되는 설정 파일에는 무시할 수 있는 수준입니다. 초당 수천 개의 객체를 파싱하는 핫 패스라면 엄격한 JSON을 사용하시기 바랍니다.
자주 묻는 질문
JSON5와 JSONC의 차이는 무엇인가요?
JSON5는 JavaScript와 유사한 문법으로 JSON을 확장합니다. 따옴표 없는 키, 후행 쉼표, 한 줄 주석과 블록 주석, 16진수, 여러 줄 문자열을 지원합니다. JSONC는 더 단순합니다. 표준 JSON에 한 줄 주석(//)과 블록 주석(/* */)만 추가합니다. 주석만으로 충분한 설정 파일에는 JSONC를, 더 풍부한 문법이 필요할 때는 JSON5를 선택하시기 바랍니다.
JSON5나 JSONC를 운영 API에서 사용해도 되나요?
아닙니다. JSON5와 JSONC는 설정 파일을 위한 형식이며, 데이터 교환 용도가 아닙니다. API는 최대한의 상호운용성을 위해 표준 JSON(RFC 8259)을 사용해야 합니다. JSON5/JSONC는 tsconfig.json, .vscode/settings.json, 환경 설정 파일처럼 기계 파싱보다 사람의 가독성이 더 중요한 로컬 설정 파일에만 사용하시기 바랍니다.
VS Code는 JSON5를 기본으로 지원하나요?
VS Code는 JSONC를 기본으로 지원하지만(자체 설정 파일도 JSONC를 사용합니다), JSON5는 기본 지원하지 않습니다. JSON5를 사용하려면 VS Code 마켓플레이스에서 “JSON5 syntax” 같은 전용 확장 프로그램을 설치하시기 바랍니다. 설정에서 .json5 파일을 JSON5 언어 모드와 연결할 수도 있습니다.
JSON5를 표준 JSON으로 어떻게 변환하나요?
json5 npm 패키지를 사용합니다. JSON5.parse()로 JSON5를 읽은 뒤 JSON.stringify()로 표준 JSON을 출력합니다. CLI에서는 npx json5 < input.json5 > output.json 명령을 실행합니다. JSON 포맷터 같은 온라인 도구로 변환 결과의 유효성을 검사해 정확성을 확인할 수도 있습니다.
JSONC는 JSON with Comments와 같은 것인가요?
그렇습니다. JSONC는 “JSON with Comments”의 약자이며, VS Code, TypeScript(tsconfig.json), 그 외 Microsoft 도구에서 사용하는 형식입니다. 표준 JSON 명세를 그대로 따르면서 //과 /* */ 주석만 추가합니다. 파서가 처리 전에 주석을 제거하므로, 결과 데이터 구조는 표준 JSON과 완전히 동일합니다.
Base64 인코딩, 해시 생성, 타임스탬프 변환 등 브라우저 기반 개발자 도구 모음은 홈페이지의 도구 카테고리에서 함께 살펴볼 수 있습니다.
마무리
가독성과 엄격함 사이의 균형은 개발자에게 오래된 과제입니다. JSON5와 JSONC는 작성 경험을 개선해 주고, 올바른 빌드 및 유효성 검사 파이프라인만 갖추면 “관대한 JSON”의 장점을 안전하게 누릴 수 있습니다.