JSON에 주석을 쓸 수 있나요? — 결론부터
쓸 수 없습니다. 표준 JSON(RFC 8259)은 문서 어디에도 주석을 허용하지 않습니다. .json 파일 안에 //나 /* ... */를 적으면 엄격한 파서는 "Unexpected token" 오류로 즉시 실패합니다. 이것은 사소한 제약이 아니라 사양 구조 자체의 한계입니다. RFC 8259 2절의 문법에는 주석을 받아들이는 규칙이 아예 존재하지 않습니다. 반면 9절은 "파서가 JSON이 아닌 형식이나 확장을 허용해도 된다(MAY accept non-JSON forms or extensions)"고 명시하는데, 바로 이 한 문장이 JSONC와 JSON5가 사양 위반 없이 존재할 수 있는 근거입니다.
그래도 설정값을 잠깐 꺼 두고 싶거나, 필드 옆에 설명을 남기고 싶다면 실무에서 쓸 수 있는 방법이 네 가지 있습니다.
- JSONC — VS Code가 채택한 "주석 있는 JSON"
- JSON5 — 주석과 후행 쉼표, 느슨한 문법을 포함한 사양화된 JSON 확장판
- 표준 JSON 안에
"_comment": "..."같은 더미 필드를 두는 방법 - 파싱 전에 주석을 제거하는 방법
이 글에서는 각 방법을 언제 쓰면 좋은지, 그리고 주석이 섞인 JSON을 표준 JSON으로 바꾸는 구체적인 절차를 다룹니다.
바로 결론만 필요하다면 용도별로 이렇게 고르면 됩니다.
- VS Code나 Microsoft 계열 설정 파일을 편집 중이라면 JSONC를 그대로 씁니다
- 새 프로젝트의 설정 포맷을 고르는 중이라면 JSON5가 다루기 편합니다
- 파서를 바꿀 수 없는 상황이라면
_comment필드나 주석 제거로 대응합니다
주석이 있는 JSON은 미리 지우고 붙여넣을 필요가 없습니다. 그대로 JSON 포맷터에 붙여넣으면 파싱 오류 옆에 "Auto-fix" 버튼이 나타납니다. 누르면 적용될 규칙 목록이 표시되고 "Apply"를 누르면 //와 /* */가 제거된 JSON으로 바뀝니다. 처리는 모두 브라우저 안에서 끝나고 데이터는 어디로도 전송되지 않습니다.
JSON이 주석을 지원하지 않는 이유
JSON을 설계한 더글러스 크락포드(Douglas Crockford)는 주석을 사양에서 의도적으로 뺐다고 밝힌 적이 있습니다. 이유는 주석 안에 파싱용 지시어를 몰래 넣는 사례가 실제로 있었고, 이것이 서로 다른 파서 사이의 호환성을 깨뜨렸기 때문입니다. 그 결과 JSON은 다음과 같은 특성을 갖게 되었습니다.
- 작다 — 문법이 한 페이지에 들어갈 정도로 간결하다
- 모호하지 않다 — 값의 해석이 항상 한 가지로 정해진다
- 이식성이 높다 — 어떤 언어의 내장 파서로 읽어도 같은 결과가 나온다
대신 "왜 이 설정값을 썼는지"를 JSON 파일 자체에 남길 방법이 없습니다. 이것이 트레이드오프이고, 많은 도구가 JSONC나 JSON5 같은 확장판을 쓰는 이유이기도 합니다.
방법 1: JSONC — 주석이 있는 JSON
JSONC는 Microsoft가 VS Code에서 채택한 비공식 확장으로, 표준 JSON에 다음 두 가지를 추가한 것입니다.
// 줄 끝까지 이어지는 주석/* 여러 줄에 걸친 주석 */
그 외에는 일반 JSON과 동일합니다. 전형적인 JSONC 파일은 이런 모습입니다.
{
// VS Code 실행 시 사용할 테마
"workbench.colorTheme": "Default Dark Modern",
/* 에디터 전역 설정
모든 언어에 적용됨 */
"editor.tabSize": 2,
"editor.formatOnSave": true
}
VS Code의 settings.json, tsconfig.json, launch.json을 비롯해 Microsoft 계열 도구 대부분이 JSONC를 전제로 합니다. Deno의 설정 파일(deno.json)에서도 채택되어 있습니다.
JSONC 파싱하기
JSONC는 내장 JSON.parse로 읽을 수 없으므로 전용 라이브러리가 필요합니다.
Node.js:
// npm install jsonc-parser
import { parse } from "jsonc-parser";
const data = parse(sourceText);
Python:
# pip install jstyleson
import jstyleson
data = jstyleson.loads(source_text)
VS Code 본체는 자체 JSONC 파서를 갖고 있어서 settings.json에 주석을 적어도 문제가 없습니다.
줄 주석(//)만 쓰고 싶을 때 — 최소 구성
실무에서 주석으로 쓰이는 건 거의 줄 주석 //뿐입니다. 블록 주석 /* */까지 필요한 경우는 드물고, "설정 의도를 한 줄로 남기고 싶다"는 목적이라면 다음 최소 구성으로 충분합니다.
VS Code에서는 파일 전체를 JSONC로 옮기지 않아도, 해당 파일만 언어 모드를 "JSON with Comments"로 바꾸면 // 줄 주석에 빨간 밑줄이 뜨지 않습니다. 화면 오른쪽 아래 언어 표시("JSON")를 클릭하고 "JSON with Comments"를 선택하면 됩니다.
다만 언어 모드 변경은 에디터 화면의 오류 표시를 없애는 것일 뿐입니다. 그 파일을 실제로 읽는 프로그램 쪽 파서가 JSONC를 지원하지 않으면 실행 시점의 "Unexpected token" 오류는 그대로 남습니다. 주석이 섞인 .json을 JSON.parse나 json.loads에 넘긴다면, 앞서 소개한 JSONC 전용 라이브러리를 거치거나 뒤에서 설명할 주석 제거 방식으로 표준 JSON으로 바꾼 다음 넘기세요.
방법 2: JSON5 — 사양화된 확장판
JSON5(json5.org새 탭에서 열립니다)는 정식 사양을 갖춘 JSON 확장판으로, ECMAScript 5에서 가져온 여러 편의 기능을 추가했습니다.
- 줄 주석과 여러 줄 주석
- 객체와 배열의 후행 쉼표
- 유효한 식별자라면 따옴표를 생략할 수 있는 키
- 작은따옴표 문자열
- 줄 연속을 이용한 여러 줄 문자열
- 16진수, 앞뒤 소수점 생략,
Infinity·NaN
JSON5 파일은 꽤 느슨한 모습을 하고 있습니다.
{
// 스테이징 환경 기능 플래그
features: {
newDashboard: true,
legacyNotifications: false,
rateLimitRps: 0xff,
},
welcomeMessage: 'Hello, world',
/* 후행 쉼표도 허용 */
}
JSON5는 사양이 문서화되어 있어서 대부분의 언어에 라이브러리가 있습니다. Node.js의 json5새 탭에서 열립니다, Python의 pyjson5, Ruby의 json5 등이 널리 쓰입니다.
JSONC와 JSON5, 무엇을 써야 할까
비슷해 보이지만 특성이 다릅니다.
| JSONC | JSON5 | |
|---|---|---|
| 공식 사양 | 없음 | 있음(spec.json5.org새 탭에서 열립니다) |
| 주석 | 지원 | 지원 |
| 후행 쉼표 | 일부 지원 | 지원 |
| 키 따옴표 생략 | 미지원 | 지원 |
| 작은따옴표 문자열 | 미지원 | 지원 |
| 생태계 | Microsoft / VS Code | npm 등 독립적 |
선택 기준은 다음과 같습니다.
- Microsoft / VS Code 설정 파일을 편집 중이라면 이미 JSONC이므로 그대로 씁니다
- 새 프로젝트에서 설정 포맷을 고르는 중이라면, 사양 문서를 도구 쪽에 근거로 제시할 수 있는 JSON5가 다루기 편합니다
- 표준 JSON 파서와의 상호운용이 최우선이라면 순수 JSON을 유지하고 뒤에서 설명할 대응 패턴을 씁니다
구현별 지원 현황
다음 표는 흔히 쓰이는 "비표준" 기능 다섯 가지를 엄격한 표준과 두 확장판에서 비교한 것입니다. RFC 8259 열은 RFC 8259새 탭에서 열립니다 2절의 문법(ECMA-404새 탭에서 열립니다에 성문화된 것과 동일)을 반영합니다. JSON5 열은 공개된 JSON5 사양새 탭에서 열립니다을, JSONC 열은 VS Code용으로 문서화된 Microsoft의 비공식 확장을 반영합니다.
| 기능 | RFC 8259에서 허용? | JSONC | JSON5 |
|---|---|---|---|
줄 주석 // | 불가 | 지원 | 지원 |
블록 주석 /* */ | 불가 | 지원 | 지원 |
| 후행 쉼표 | 불가 | 임의 | 지원 |
| 키 따옴표 생략 | 불가 | 미지원 | 지원 |
| 작은따옴표 문자열 | 불가 | 미지원 | 지원 |
RFC 8259 열이 전부 "불가"인 이유는 2절 문법에 이 기능들을 받아들이는 production rule이 존재하지 않기 때문입니다. 문자열은 큰따옴표로 감싸야 하고, 키도 문자열이어야 하며, 객체나 배열의 마지막 값 뒤에 요소를 둘 수도 없습니다. JSON5는 ECMAScript 5 문법을 사양에 명시적으로 추가했기 때문에 다섯 가지 모두를 지원합니다. JSONC는 두 종류의 주석을 항상 추가하면서도 엄격한 JSON의 큰따옴표 키와 문자열은 그대로 유지합니다. 후행 쉼표 지원이 파서마다 다른 이유는 JSONC 사양 자체가 파서에게 받아들여도 된다(MAY)는 선택지만 주기 때문이며, 기준 구현인 jsonc-parser는 allowTrailingComma 옵션을 기본값 비활성화로 두고 있습니다. 표에서 이 칸이 "지원"이 아니라 "임의"로 표시된 것은 그래서입니다.
표준 JSON을 유지하면서 주석을 남기는 방법
서드파티 서비스가 표준 JSON만 받는 상황이라면, 파서를 바꾸지 않고 문자열 필드로 메모를 남기는 방법이 있습니다.
패턴 1: _comment 필드
{
"_comment": "상류 타임아웃에 걸리기 전에 재시도 횟수를 늘림",
"retries": 3,
"timeout_ms": 5000
}
밑줄로 시작하는 키는 관례적으로 소비 측에서 무시되는 경우가 많고, 대부분의 코드에서 일반 데이터처럼 취급해도 문제가 없습니다. 가장 단순한 대응 방법입니다.
패턴 2: 필드마다 옆에 주석 키를 두는 방법
{
"retries": 3,
"retries_comment": "이 이상 늘리면 상류 타임아웃을 넘김",
"timeout_ms": 5000,
"timeout_ms_comment": "로드밸런서 타임아웃에 맞춘 값"
}
파일이 장황해지지만 어떤 주석이 어떤 필드에 대응하는지 명확해집니다.
패턴 3: 메타데이터용 바깥 블록
{
"$meta": {
"generated_by": "deploy.sh",
"purpose": "스테이징 환경용 서비스 설정"
},
"service": {
"port": 8080,
"retries": 3
}
}
최상위에 메타데이터 전용 객체를 두면 본문 페이로드를 건드리지 않고 맥락을 남길 수 있습니다.
세 패턴 모두 실제 데이터로 파일에 기록되므로 엄격한 파서도 그대로 받아들입니다. 단점은 추가 필드가 스키마의 일부가 되어, 소비 측에도 존재 이유를 설명해야 한다는 점입니다.
package.json에 주석 달기
package.json은 npm이 읽는 표준 JSON 파일이므로 //나 /* */ 주석을 쓸 수 없습니다. 적으면 npm install이 JSON.parse 단계에서 실패합니다. 다만 npm은 알지 못하는 최상위 키를 무시하므로, 앞서 소개한 대응 패턴을 그대로 응용할 수 있습니다.
가장 많이 쓰이는 방식은 관례적인 "//" 키에 메모를 넣는 것입니다.
{
"//": "private 레지스트리를 쓰는 설정. 사내 CI에서만 유효",
"name": "my-app",
"version": "1.0.0",
"scripts": {
"build": "tsc -p ."
}
}
같은 키는 한 객체 안에서 한 번만 쓸 수 있으므로, 여러 설명을 남기고 싶다면 배열을 씁니다.
{
"__comments": [
"배포용 스크립트는 이 파일에서 관리하지 않음",
"engines는 CI의 Node 버전과 맞출 것"
],
"name": "my-app",
"engines": { "node": ">=20" }
}
npm 자체는 이런 키를 무시하지만, npm publish로 배포하는 패키지에는 메모도 함께 실립니다. 사내 도구나 프라이빗 저장소용 package.json에 적합한 방법입니다. 설정 의도를 확실히 남기고 싶다면, 뒤에서 설명하는 주석 제거 패턴으로 JSONC로 작성한 뒤 배포용으로 변환하는 편이 더 안전합니다.
주석을 제거하고 표준 파서에 전달하기
JSONC나 JSON5 파일을 표준 JSON 파서에 넘겨야 한다면 선택지는 두 가지입니다. JSONC/JSON5 라이브러리로 파싱한 뒤 JSON으로 다시 써내거나, 정규식으로 주석을 제거하는 방법입니다.
Node.js에서 json5 패키지를 쓰는 예시입니다.
// npm install json5
import JSON5 from "json5";
import fs from "node:fs";
const source = fs.readFileSync("config.json5", "utf8");
const data = JSON5.parse(source);
fs.writeFileSync("config.json", JSON.stringify(data, null, 2));
최소한의 정규식으로도 제거할 수 있습니다. 다만 문자열 리터럴 안에 //가 들어 있으면 잘못 잘려나가므로, 직접 관리하는 파일이 아니라면 권하지 않습니다.
const stripped = source
.replace(/\/\/[^\n\r]*/g, "")
.replace(/\/\*[\s\S]*?\*\//g, "");
const data = JSON.parse(stripped);
안전하게 처리하려면 항상 전용 파서를 거치는 편이 무난합니다.
Python에서 JSONC·JSON5 다루기
Python 표준 라이브러리 json은 엄격한 JSON만 읽을 수 있어서, JSONC나 JSON5를 그대로 json.loads에 넘기면 주석이 있는 줄에서 실패합니다. 대응 방법은 두 가지입니다.
가볍게 처리하고 싶다면 표준 라이브러리 re로 주석을 제거한 뒤 json.loads에 넘깁니다.
import json, re
def load_jsonc(text):
text = re.sub(r"//[^\n]*", "", text) # 줄 주석
text = re.sub(r"/\*.*?\*/", "", text, flags=re.S) # 블록 주석
return json.loads(text)
with open("tsconfig.json", encoding="utf-8") as f:
config = load_jsonc(f.read())
이 정규식은 문자열 리터럴 안의 //도 함께 지워 버릴 수 있으므로, 직접 관리하는 파일이 아니라면 쓰지 마세요.
후행 쉼표나 따옴표 생략까지 포함해서 정확하게 읽고 싶다면 전용 라이브러리를 씁니다. JSONC라면 jstyleson, JSON5라면 json5나 pyjson5가 대표적입니다.
# pip install jstyleson json5
import jstyleson
import json5
config = jstyleson.load(open("settings.json", encoding="utf-8")) # JSONC
data = json5.load(open("config.json5", encoding="utf-8")) # JSON5
설정을 읽기만 한다면 정규식으로도 충분하지만, 입력을 신뢰할 수 없거나 후행 쉼표·작은따옴표가 섞일 가능성이 있다면 전용 라이브러리 쪽이 안전합니다.
FormatArc로 정리하고 결과 확인하기
표준 JSON으로 바꾼 뒤에는 JSON 포맷터에 붙여넣어 정렬된 결과를 확인할 수 있습니다. 그런데도 파서가 여전히 오류(전형적으로는 Unexpected token /)를 낸다면 주석이 아직 남아 있을 가능성이 높습니다. 원인 목록은 JSON 파싱 오류 해결 - unexpected token 에러의 원인과 수정 방법에 정리되어 있습니다.
FormatArc 자체는 브라우저 내장 JSON.parse를 사용하지만, 파싱에 실패했을 때는 자동 수정 기능을 거칠 수 있습니다. 절차는 다음과 같습니다.
- 주석이 있는 상태 그대로 JSON 포맷터에 붙여넣는다
- 오류 표시 옆에 나오는 "Auto-fix" 버튼을 누른다
- 적용될 규칙 목록을 확인하고 "Apply"를 누른다
- 정리된 JSON을 읽고 검증하고 복사한다
자동 수정이 다루는 것은 // 줄 주석, /* */ 블록 주석, 후행 쉼표, 연속 쉼표 네 가지입니다. 문자열 안에 들어 있는 //(예: "https://example.com")는 대상이 아니므로 URL이 깨질 일은 없습니다. JSON5의 작은따옴표나 따옴표 없는 키는 지원 대상이 아니므로, 그런 파일은 JSON5 라이브러리로 먼저 파싱한 뒤 붙여넣으세요. 처리는 모두 브라우저 안에서 끝나고 데이터는 어디로도 전송되지 않습니다.
자주 묻는 질문
RFC 8259는 JSON 주석에 대해 뭐라고 정의하나요?
RFC 8259는 "주석(comment)"이라는 단어를 한 번도 쓰지 않습니다. 2절의 JSON 문법(ABNF)은 "토큰 사이에 둘 수 있는 공백은 space·tab·line feed·carriage return 네 가지뿐"이라고 정의하며(ws = *( %x20 / %x09 / %x0A / %x0D )), //나 /* */를 받아들이는 production rule이 존재하지 않으므로 엄격한 파서는 "Unexpected token" 오류로 거부합니다. 한편 9절은 "JSON 파서가 JSON이 아닌 형식이나 확장을 허용해도 된다(MAY)"고 명시하는데, 이것이 JSONC와 JSON5가 사양 위반이 되지 않는 근거입니다.
.json 파일에 //나 /* 주석을 쓸 수 있나요?
엄격한 파서(JSON.parse, json.loads, encoding/json)로 읽을 경우에는 쓸 수 없습니다. 첫 번째 주석에서 "Unexpected token" 오류가 발생합니다. 확장자를 .jsonc로 바꾸고 JSONC 대응 로더를 쓰거나, JSON5로 옮겨야 합니다.
.json 파일에서 한 줄만 주석 처리할 수 있나요?
할 수 없습니다. JSON에는 줄 주석 문법 자체가 존재하지 않으므로, 값을 잠깐 비활성화하려고 줄 앞에 //를 붙이면 그 줄이 구문 오류가 됩니다. 한 줄만 비활성화하고 싶을 때 쓸 수 있는 방법은 세 가지입니다. 키 자체를 지우고 버전 관리 이력에 남기거나, 비활성화하려는 키를 _disabled_ 같은 접두사가 붙은 키로 이름을 바꿔 대피시키거나, 파일을 JSONC 대응 환경으로 옮겨 정식으로 주석 처리하는 것 중 하나를 고르면 됩니다.
VS Code는 왜 settings.json에 주석을 써도 깨지지 않나요?
VS Code가 settings.json 같은 파일을 엄격한 JSON이 아니라 JSONC로 취급하기 때문입니다. 내장 파서가 //와 /* */를 받아들입니다. 같은 파일을 JSON.parse로 읽는 다른 에디터는 JSONC를 이해하지 못하면 실패합니다.
JSON5는 표준 사양인가요?
JSON5는 spec.json5.org새 탭에서 열립니다에 공개된 사양을 갖고 있지만, IETF나 ECMA의 공식 표준은 아닙니다. 개발 도구 생태계에서는 폭넓게 지원되지만, API나 통신 프로토콜에서 쓰이는 RFC 8259 JSON을 대체하지는 못합니다.
FormatArc는 JSONC나 JSON5를 지원하나요?
JSONC는 자동 수정으로 처리할 수 있습니다. 주석이 있는 상태 그대로 JSON 포맷터에 붙여넣고 "Auto-fix"에서 "Apply"까지 진행하면 //와 /* */가 제거된 JSON이 됩니다. 후행 쉼표와 연속 쉼표도 동시에 고쳐집니다. JSON5의 작은따옴표나 따옴표 없는 키는 자동 수정 대상이 아니므로, 그런 경우에는 JSON5 라이브러리로 먼저 파싱한 뒤 붙여넣으세요.
주석이 꼭 필요하다면 YAML을 써야 하나요?
YAML은 #로 표준적으로 주석을 지원합니다. 목적이 주석이고 포맷 자체를 바꿀 수 있는 상황이라면 YAML이 설정 파일에 더 잘 맞는 경우도 많습니다. YAML JSON 변환기로 두 형식을 오갈 수 있습니다.
정리
- 표준 JSON은 주석을 지원하지 않습니다. 사양이 의도적으로 둔 제약입니다
- JSONC는
//와/* */를 허용하며 VS Code에서 널리 쓰입니다 - JSON5는 사양화된 확장판으로, 주석과 후행 쉼표, 느슨한 문법을 갖고 있습니다
- 파서를 바꿀 수 없다면
_comment필드나 바깥 메타데이터 블록으로 대응할 수 있습니다 - 주석이 있는 JSON은 JSON 포맷터에 그대로 붙여넣고 자동 수정으로 주석과 후행 쉼표를 제거한 뒤 정리·검증할 수 있습니다