같은 설정이라도 API는 JSON, K8s는 YAML, CI에서는 상호 변환——형식을 잘못 고르면 파싱 실패, 주석 손실, 잘못된 환경 배포로 이어집니다.
이 글은 풀스택·DevOps 엔지니어를 대상으로 JSON과 YAML의 구문 차이, 선택 원칙, 5단계 안전 상호 변환 흐름, 앵커·불리언 등 흔한 함정을 설명합니다. 읽은 후 JSON Toolbox의 JSON ↔ YAML 변환 기능으로 브라우저에서 로컬로 변환과 검증을 할 수 있습니다.
JSON과 YAML을 이해해야 하는 이유
JSON은 사실상의 API 표준이고 YAML은 사실상의 운영 설정 언어입니다. 팀이 둘 사이를 자주 전환할 때 차이를 모르면 '로컬 YAML은 되는데 JSON 변환 후 키 타입이 바뀐다'는 문제가 생기기 쉽습니다.
예: Docker Compose의 ports: "8080:8080"과 JSON 숫자 포트 혼용, K8s 매니페스트의 yes/no가 YAML에서 불리언으로 파싱되어 JSON 변환 후 클라이언트 동작이 달라지는 경우 등.
JSON과 YAML이란
JSON(JavaScript Object Notation)은 엄격한 텍스트 기반 데이터 교환 형식: 키 이름은 큰따옴표 필수, 주석 미지원, 프로그램 파싱에 적합합니다. YAML(YAML Ain't Markup Language)은 들여쓰기로 계층을 표현하고 주석과 다양한 스칼라 표기를 지원——대규모 수동 설정에 적합합니다.
둘의 관계
YAML 1.2 사양에서 JSON은 그 부분집합——대부분의 유효 JSON은 그대로 YAML로 파싱됩니다. 다만 YAML 고유 기능(앵커 &, 별칭 *, 여러 줄 문자열 |)은 JSON 변환 시 손실되거나 펼쳐져야 합니다.
핵심 차이 비교
| 비교 차원 | JSON | YAML |
|---|---|---|
| 주석 | ❌ 미지원 | ✅ # 줄 주석 |
| 키 이름 따옴표 | ✅ 큰따옴표 필수 | ⚠️ 대부분 생략 가능 |
| 계층 표현 | 중괄호 / 대괄호 | 들여쓰기(공백) |
| API 전송 적합 | ✅ 권장 | ⚠️ 드묾 |
| 대규모 수동 설정 | ⚠️ 괄호 많음 | ✅ 권장 |
| 엄격성 | 높음, 파싱 실패 즉시 오류 | 비교적 느슨, 암시적 타입 함정 |
누구에게 어떤 형식이 적합한가
| 역할 / 시나리오 | 권장 형식 | 이유 |
|---|---|---|
| REST / GraphQL API | JSON | 생태계 통일, 모호함 없음 |
| Kubernetes / Helm | YAML | 커뮤니티 관습, 주석 가능 |
| Docker Compose | YAML | 공식 예제와 문서 |
| package.json / tsconfig | JSON | 툴체인 네이티브 지원 |
| 메시지 큐 Payload | JSON | 부피 작음, 파싱 빠름 |
전형적 시나리오 선택 가이드
- 프론트엔드/백엔드 API 계약: JSON
- GitHub Actions / GitLab CI 일부 단계: YAML
- 환경 변수 주입 전 정적 설정: 팀 습관에 따라, YAML은 주석에 유리
- 기계적으로 엄격 검증이 필요한 구조: JSON + JSON Schema
실전: 5단계 안전 상호 변환
- 방향 명확화: JSON → YAML(읽기 쉽게 편집) 또는 YAML → JSON(API/프로그램용)
- 원본 백업: 변환 전 롤백 가능한 사본 보관
- JSON Toolbox 변환 페이지에 소스 붙여넣고 해당 방향 선택
- 결과 검증: JSON 측은 검증 도구, YAML 측은 들여쓰기와 타입 주의
- 대상 환경 스모크 테스트: 한 번 배포 또는 호출, 변환 전과 동일 동작 확인
예: 같은 설정의 두 가지 표기
JSON:
{
"service": "api-gateway",
"replicas": 3,
"debug": false,
"ports": [8080, 8443]
}YAML:
service: api-gateway
replicas: 3
debug: false
ports:
- 8080
- 8443상호 변환 흔한 함정
YAML 암시적 타입
- yes / no / on / off가 불리언으로 파싱될 수 있음
- 순수 숫자 문자열은 따옴표 권장, 예: version: "01"
- null과 ~는 YAML에서 빈 값, JSON 변환 후 null
JSON → YAML 후 크기
YAML은 읽기 쉽지만 반드시 짧지는 않습니다. 전송만 목적이면 프로덕션도 JSON + 압축을 권장합니다.
앵커와 별칭
YAML의 &anchor와 *alias는 JSON 변환 시 중복 객체로 펼쳐집니다——의도대로인지 확인하세요.
JSON vs YAML 도구 체인
| 니즈 | JSON 도구 체인 | YAML 도구 체인 |
|---|---|---|
| 브라우저 내 상호 변환 | JSON Toolbox | JSON Toolbox |
| CLI 검증 | jq | yamllint / yq |
| K8s 적용 | 먼저 YAML 변환 또는 CRD JSON | kubectl apply -f |
| Schema 제약 | JSON Schema 성숙 | 통일 표준 적음 |
자주 묻는 질문 (FAQ)
모든 JSON을 YAML로 변환할 수 있나요?
표준 JSON은 모두 동등한 YAML로 변환할 수 있습니다. 변환 후 키 순서와 들여쓰기 스타일은 손으로 쓴 YAML과 다를 수 있지만 의미에는 영향이 없습니다.
YAML 주석이 JSON에 남나요?
아니요. JSON은 주석을 지원하지 않아 변환 시 주석이 버려집니다. 중요한 설명은 문서나 README에 기록하세요.
K8s 리소스에 JSON을 쓸 수 있나요?
예. kubectl은 JSON 매니페스트를 지원하지만 커뮤니티 예제와 Helm 템플릿은 주로 YAML입니다. 팀 협업에서는 형식을 통일하는 것을 권장합니다.
변환 실패의 가장 흔한 원인은?
JSON 측: 후행 쉼표, 작은따옴표. YAML 측: Tab과 공백 혼용, 콜론 뒤 공백 부족.
데이터가 서버에 업로드되나요?
아니요. JSON Toolbox는 브라우저에서 로컬 변환합니다. 민감 설정이 포함된 내부 파일에도 적합합니다(여전히 마스킹 권장).
변환 후 다시 검증해야 하나요?
권장합니다. 최소 한 번 JSON 구문 검증을 하고 staging 환경에서 설정이 적용되는지 확인하세요.
정리 및 다음 단계
JSON은 엄격성과 상호 운용성, YAML은 가독성과 운영 친화성을 중시합니다. 선택 원칙: 대외 API와 프로그램 간 통신은 JSON; 수동 유지 대규모 정적 설정은 YAML 우선; 상호 변환 시 항상 검증과 스모크 테스트.
저장소에서 '어떤 파일에 어떤 형식이 필수인지'를 약속하고 CI에 형식 검증을 추가해 YAML 암시적 타입으로 인한 프로덕션 사고를 방지하세요.