LIT-hujson-jwcc-overview

요약

HuJSON (Human JSON)은 Tailscale이 구현한 JWCC (JSON With Commas and Comments) 포맷의 Go 라이브러리이다. JWCC는 표준 JSON에 주석과 후행 쉼표 두 가지만 추가한 최소 확장 포맷으로, 사람이 직접 편집하는 설정 파일 용도로 설계되었다.

핵심 포인트

JWCC가 JSON에 추가하는 것 (딱 두 가지)

주석: // 라인 주석과 /* 블록 주석 */ — JSON에서 공백이 허용되는 모든 위치에 삽입 가능
후행 쉼표: [1, 2, 3,]처럼 마지막 요소 뒤에 쉼표 허용

이 두 가지는 설정 파일에서 가장 빈번하게 요청되는 기능이면서, JSON의 객체 모델을 변경하지 않는다. 모든 유효한 JSON은 유효한 JWCC이므로 하위 호환성이 완벽하다.

왜 JSON5/YAML/TOML이 아닌가

JWCC의 핵심 설계 원칙은 "clarity, not terseness" (간결함보다 명확함)이다.

거부된 기능	이유
따옴표 없는 키/값 (JSON5, HJSON)	미래 키워드 추가를 차단, 파싱 모호성
`NaN`/`Inf` (JSON5)	JSON과 다른 객체 모델 → 호환성 파괴
들여쓰기 기반 구조 (YAML)	공백 민감성으로 인한 파싱 사고
복합 데이터 타입 (TOML, CUE)	설정 파일에 비해 과잉 설계

JSONC(VS Code가 사용하는 형식)와 가장 유사하지만, JSONC는 후행 쉼표 지원 여부가 문서마다 다르고 이름이 모호하다는 문제가 있다. JWCC는 이를 명시적으로 정의한다.

HuJSON 라이브러리 (Go)

Tailscale의 github.com/tailscale/hujson 패키지가 JWCC의 참조 구현체 역할을 한다. 주요 워크플로우:

HuJSON 입력을 AST로 파싱 (Parse)
주석/후행 쉼표 제거하여 표준 JSON으로 변환 (Minimize / Standardize)
표준 JSON을 encoding/json 등 기존 JSON 라이브러리로 처리

이 접근 방식 덕분에 기존 JSON 파서를 수정하지 않고도 HuJSON을 지원할 수 있다.

실제 사용처

Tailscale ACL: tailnet 정책 파일이 HuJSON 형식으로 작성됨
Headscale ACL: Tailscale 오픈소스 대안인 Headscale도 HuJSON 정책 파일 지원

나의 생각

JSON 설정 파일의 가장 큰 불편함은 주석을 쓸 수 없다는 것과, diff 충돌을 줄이려고 마지막 요소에 쉼표를 붙이지 못한다는 것이다. JWCC는 이 두 가지만 정확히 해결하고 나머지는 건드리지 않는다는 점에서 실용적이다.

JSON5처럼 따옴표 없는 키를 허용하면 편리해 보이지만, 파서 복잡도가 올라가고 미래 확장과 충돌할 수 있다. "필요한 최소한만 추가"라는 JWCC의 접근은 UNIX 철학과 일맥상통한다.

Headscale ACL 정책 파일에서 실제로 사용하고 있으므로, HuJSON 파서/포맷터 도구를 알아두면 디버깅에 유용할 것이다.

gonnux.com