JSON에 주석을 넣을 수 있나

핵심부터 말하면, 표준 JSON에는 절대 주석을 넣지 마세요. 사람만 편집하는 로컬 설정에는 JSONC나 JSON5를, 파일이 시스템을 넘을 때는 설명을 JSON Schema description에 넣고, 주석 양이 늘면 YAML이나 TOML로 전환하세요.

아니요.

표준 준수 파서는 다음을 거부합니다:

复制{
  "port": 8080 // local development only
}

Chrome은 SyntaxError: Unexpected token }를 보고합니다. 파서가 JSON 값을 시작할 수 없는 /를 만나 멈췄습니다.

명세가 주석을 의도적으로 뺀 이유

RFC 8259는 여섯 값(객체, 배열, 숫자, 문자열, true/false, null)을 정의합니다. 주석 생성 규칙이 없습니다.

주석은 초기에 제안되었다가 구체적 이유로 거부되었습니다. 주석이 합법이 되는 순간 누군가 조건부 include, 템플릿 변수 같은 지시자를 담는 데 쓰고, 모든 파서가 자체 방언을 키웁니다. 상호 운용성이 첫 홉에서 깨집니다. JSON은 의도적으로 데이터만 담고 내부에 실행 가능한 것이 없습니다.

메모를 남기는 네 가지 방법

1. 상위 집합 사용. JSON5와 JSONC는 두 주석 스타일을 받아들입니다. VS Code의 settings.json과 tsconfig.json이 JSONC입니다. 비용은 실재합니다. JSON.parse는 여전히 거부하고, API, 로그 파이프라인, 메시지 큐는 대개 표준 JSON만 받습니다. 주석이 조용히 버려지거나 하류 어딘가에서 던집니다.

2. 메모를 데이터에 넣기.

复制{
  "_comment": "port assigned by ops, do not change",
  "port": 8080
}

어디서나 동작하지만 모델을 오염시킵니다. 모든 소비자가 무시할 키를 알아야 하고, 타입 정의에 진짜 데이터가 아닌 필드가 늘어납니다.

3. Schema description 사용. description은 사람과 도구를 위한 것입니다. 검증기가 노출하고 에디터가 호버로 보여 주며, 페이로드에는 절대 들어가지 않습니다. 호환성을 깨지 않고 장기 유지 관리에서 살아남는 유일한 선택입니다.

4. 파일 형식 변경. 파일이 손으로 편집되기 위해 존재한다면 YAML이나 TOML이 주석을 네이티브로 지원합니다. 여기서 JSON과 싸우는 것은 헛된 노력입니다.

선택

FAQ

_comment 필드가 왜 모델을 오염시키나?

데이터의 일부가 되기 때문입니다. 모든 소비자가 무시할 키를 알아야 하고, 타입 정의에 진짜 업무 데이터가 아닌 필드가 늘어납니다.

설명이 JSON Schema description에 있어야 하나?

예. description은 페이로드 밖에 남고, 검증기가 노출하며 에디터가 호버로 보여 주므로, 호환성을 깨지 않고 장기 유지 관리에서 살아남는 유일한 선택입니다.

JSONC나 JSON5를 JSON.parse로 파싱할 수 있나?

아니요. JSON.parse는 여전히 주석을 거부하고, API, 로그 파이프라인, 메시지 큐는 대개 표준 JSON만 받으므로 주석이 버려지거나 하류에서 던집니다.

도구

• JSON5 파서 — 주석이 있는 설정을 붙여 넣고 해석된 구조를 확인
• JSON 포매터와 검증기 — 불법 JSON을 행과 열로 보고해 문제 주석이 분명해짐

더 읽을거리

• JSON5와 JSONC: 주석이 있는 JSON
• JSON 파싱 오류 문제 해결
• 설정, 픽스처, 로컬 데이터 관리