JSON·YAML·TOML 차이: API 데이터와 설정 파일, 무엇을 골라야 할까

요약: JSON, YAML, TOML은 각각 언제 써야 할까?

• JSON은 API·웹훅처럼 프로그램끼리 데이터를 교환할 때의 기본값이다.
• YAML은 사람이 읽는 선언형 설정에 잘 맞지만, 들여쓰기가 문법이라 검증을 빼면 위험하다.
• TOML은 주석을 남기면서도 비교적 단순한 프로젝트·도구 설정에 잘 맞는다.
• 형식 선택보다 더 중요한 것은 그 형식을 읽는 도구의 스키마와 CI 검증이다.

JSON, YAML, TOML은 모두 객체와 목록 같은 구조를 표현한다. 그래서 파일 확장자만 바꿔도 비슷하게 보인다. 하지만 하나는 데이터 교환, 하나는 사람이 읽는 선언, 하나는 설정 파일을 목표로 설계됐다. 형식을 고를 때는 “더 예쁜 문법”이 아니라 누가, 언제, 어떤 도구로 수정하고 읽는가를 먼저 정해야 한다.

API·웹훅·저장 데이터라면 JSON

JSON은 이름과 값의 묶음, 순서가 있는 배열, 그리고 문자열·숫자·불리언·null이라는 제한된 값만 사용한다. 문자열은 큰따옴표로 감싸고 쉼표와 중괄호로 구조를 드러낸다.

{
  "userId": "u_42",
  "notifications": true,
  "tags": ["beta", "mobile"]
}

이 제약은 불편함보다 장점이 크다. 브라우저와 서버, 서로 다른 언어로 쓴 서비스가 같은 데이터를 해석해야 할 때 애매함을 줄여 준다. JSON은 표준 라이브러리와 HTTP 도구 지원이 넓어서 REST API, 이벤트, 웹훅, 캐시 데이터에 적합하다. 반대로 표준 JSON에는 주석이 없다. 사람이 이유를 길게 적어야 하는 운영 설정이라면 이 단점이 커진다.

길고 선언적인 설정이라면 YAML

YAML은 들여쓰기로 중첩 구조를 보여 주고 주석을 허용한다. 읽는 사람이 항목의 위계를 빠르게 볼 수 있어 CI/CD, Kubernetes처럼 선언이 긴 파일에서 널리 쓰인다.

service:
  name: api
  replicas: 2
  regions:
    - icn
    - nrt

핵심 주의점은 공백이 장식이 아니라 문법이라는 점이다. 한 단계 잘못 들여쓰면 같은 키처럼 보여도 다른 구조가 된다. YAML 1.2는 JSON을 부분집합으로 맞췄지만, 실제 서비스는 서로 다른 파서·버전·스키마를 쓸 수 있다. 복사한 예제를 믿기보다 해당 도구의 공식 예제, formatter, linter를 같이 두는 편이 안전하다.

프로젝트 설정이라면 TOML

TOML은 사람이 읽기 쉬운 최소 설정 형식을 목표로 한다. key = value, [table], 배열, # 주석이라는 규칙이 명확하다. Rust의 Cargo.toml이나 Python의 pyproject.toml처럼 프로젝트 메타데이터와 도구 옵션을 적을 때 자연스럽다.

TOML은 설정 파일에 초점을 둔다. 임의의 데이터를 계속 보내는 API 본문에는 JSON보다 덜 알맞지만, 사람이 검토하는 앱·패키지 설정에는 주석과 표 구조가 큰 이점이 된다.

이렇게 고르면 된다

형식을 고른 뒤에 꼭 할 일

첫째, 허용할 키와 자료형, 기본값을 스키마로 정한다. JSON도 파싱만 된다고 안전하지 않다. 둘째, 포맷·파싱·스키마 검사를 CI에 넣는다. YAML의 들여쓰기, JSON의 쉼표, TOML의 중복 테이블을 배포 전에 잡아야 한다. 셋째, 비밀값을 형식의 문제로 해결하려 하지 않는다. API 키와 비밀번호는 어느 형식이든 저장소에 넣지 말고 배포 환경이나 비밀 관리 도구에서 주입한다.

결론

데이터 교환은 JSON, 사람이 읽는 선언은 YAML, 사람이 유지하는 프로젝트 설정은 TOML이라는 출발점이 실용적이다. 다만 실제 장애를 줄이는 선택은 파일 확장자가 아니라 형식 + 파서 + 스키마 + 검증 절차를 함께 고르는 데서 나온다.

출처

• JSON 데이터 교환 표준
• YAML 1.2.2 명세
• TOML 1.0 명세