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으로 변환하고 zod 같은 스키마로 검증만 해 두면 안전하게 쓸 수 있습니다.

참고 자료

• JSON5 GitHub
• JSONC 명세 (VS Code)
• Prettier 파서 문서
• comment-json