빠른 비교

{
  "name": "refdock",
  "enabled": true
}

// JSON5 또는 JSONC 계열에서나 가능한 형태
{
  // comment
  name: "refdock",
  enabled: true,
}

문법 경계

표준 JSON에는 주석 문법이 없다

RFC 8259의 JSON 문법은 object, array, string, number, true, false, null과 여섯 개의 구조 문자만으로 구성됩니다. 공백은 허용되지만, // comment나 /* comment */는 표준 JSON token이 아닙니다.

{
  "name": "app"
}

설정 파일에서 주석을 쓰고 싶다면 그 파일은 더 이상 엄격한 JSON이 아니라 JSONC, JSON5, Hjson 같은 별도 확장 형식으로 봐야 합니다.

trailing comma도 표준 JSON이 아니다

객체 member와 배열 element는 comma로 구분하지만, 마지막 항목 뒤 comma는 표준 JSON에서 허용되지 않습니다. JavaScript object literal이나 JSON5에서는 자연스럽게 보이지만, 엄격한 JSON parser에서는 실패합니다.

{
  "name": "app",
  "enabled": true
}

// 표준 JSON 아님
{
  "name": "app",
  "enabled": true,
}

API payload, 로그 수집, 메시지 큐, 외부 교환 파일은 strict JSON으로 맞추는 편이 안전합니다.

JSON5는 사람이 쓰기 편한 확장 문법이다

JSON5는 comments, trailing comma, unquoted key, single-quoted string 같은 확장 문법을 지원합니다. 개발자가 직접 편집하는 설정 파일에는 편하지만, 표준 JSON을 받는 API나 validator에 그대로 보낼 수는 없습니다.

{
  // development config
  port: 3000,
  features: ["search", "archive",],
}

JSON5를 쓰는 프로젝트라면 파일 확장자, parser, 빌드 변환 단계, 배포 산출물이 무엇인지 명확히 해야 합니다.

외부 경계에서는 strict JSON으로 변환한다

내부 설정 파일은 JSON5나 JSONC로 관리하더라도, HTTP API 요청, 공개 데이터 파일, schema 검증 입력은 strict JSON으로 직렬화해서 내보내는 편이 맞습니다.

developer config
  -> JSON5 / JSONC parser
  -> internal object
  -> strict JSON serializer
  -> API payload

형식을 섞으면 editor에서는 정상처럼 보이는데 서버나 CI에서 parse error가 나는 문제가 생깁니다.

선택 기준

주의할 점

브라우저, 서버, CLI 도구마다 parser 허용 범위가 다를 수 있습니다. package.json, API request body, webhook payload처럼 표준 JSON을 기대하는 곳에는 comments와 trailing comma를 넣지 않아야 합니다.