TOML을 YAML로 변환하는 가장 빠른 방법은 yq -oy '.' file.toml을 사용하는 것입니다. 수동 변환 시 TOML [table] 헤더를 YAML 들여쓰기 블록으로, TOML 배열을 대시 접두사 목록으로 매핑하고, 애매한 문자열에는 항상 따옴표를 사용하여 “노르웨이 문제”를 피하세요.
빠른 변환: yq CLI 사용
TOML(Tom’s Obvious, Minimal Language)이 2025년 12월에 v1.1.0을 릴리스했지만, YAML은 여전히 CI/CD 파이프라인과 Kubernetes 매니페스트의 표준입니다. yq 도구는 단일 명령으로 변환을 처리합니다.
yq 설치
| 플랫폼 | 명령어 |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python(pip) | pip install yq |
속도가 빠른 Mike Farah의 Go 기반 버전이 권장됩니다. Mike Farah의 yq 문서에 명시된 대로, 이 도구는 TOML 구조를 디코딩하고 깔끔한 YAML로 재인코딩합니다.
변환 실행
터미널에 표시:
yq -oy '.' your-config.toml
파일로 저장:
yq -oy '.' your-config.toml > your-config.yaml
-oy 플래그는 출력 형식을 YAML로 설정합니다. 키-값 쌍, 중첩 테이블, 배열을 모두 처리합니다.
구문 변환 맵: TOML 구조에서 YAML로
개발자 Drew DeVault는 TOML이 인기 있지만 YAML이 깊은 중첩을 더 깔끔하게 처리한다고 지적했습니다. 정확한 매핑은 다음과 같습니다:
테이블을 들여쓰기 키로 변환
TOML은 대괄호 헤더를 사용하고 YAML은 들여쓰기를 사용합니다.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
핵심 차이점: TOML에서 들여쓰기는 장식일 뿐입니다. YAML에서 들여쓰기는 구조적입니다 — 잘못된 공백 하나가 전체 설정 파일을 망가뜨립니다.
배열을 대시 접두사 목록으로 변환
TOML: ports = [ 8000, 8001 ]
YAML:
ports:
- 8000
- 8001
Knightli.com에서 설명하듯, YAML의 “블록 스타일”은 수직 정렬이 일관되다면 목록을 읽기 쉽게 만들어 줍니다.
인라인 테이블과 점 표기법 키
| TOML 구문 | YAML 동등 표현 |
|---|---|
[a.b.c](점 헤더) |
a: → b: → c:(중첩 들여쓰기) |
point = { x = 1, y = 2 }(인라인 테이블) |
point: → x: 1 → y: 2 |
실제 사용 사례
Hugo 정적 사이트 설정
Hugo는 hugo.toml, hugo.yaml 또는 hugo.json을 지원합니다. 대부분의 프로젝트는 TOML(기본값)로 시작했다가, 설정을 Netlify나 GitHub Actions 같은 배포 플랫폼에 맞춰야 할 때 YAML로 마이그레이션합니다. Hammer Europe에 따르면 hugo 명령어는 이 파일들을 읽어 Markdown을 라이브 사이트로 변환하는 방법을 결정합니다.
Python 패키징: pyproject.toml에서 CI/CD YAML로
Python 커뮤니티는 PEP 518을 통해 pyproject.toml을 표준화했습니다. 이 설정들은 종종 GitHub Actions CI/CD 워크플로를 위해 YAML로 변환해야 합니다. AI 에이전트 워크플로의 경우, CocoIndex는 최적화된 YAML 설정이 토큰 사용량을 최대 70% 줄일 수 있다고 보고합니다.
노르웨이 문제 및 기타 변환 주의사항
NO 국가 코드 버그
YAML 1.1에서는 NO, OFF, YES 같은 따옴표 없는 문자열이 자동으로 불리언 false 또는 true로 강제 변환됩니다. TOML은 모든 문자열에 따옴표를 요구하여 이 문제를 피합니다. 변환 시 YAML에서 애매한 값에는 항상 따옴표를 사용하세요:
| 값 | YAML 1.1 해석 | 해결 방법 |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
YAML 1.2(현재 사양)는 이러한 강제 변환의 대부분을 수정했지만, 많은 파서가 여전히 기본적으로 1.1 동작을 사용합니다.
들여쓰기 오류
YAML 파서는 들여쓰기가 일관되지 않은 파일을 거부합니다. 흔한 실수:
- 탭과 공백 혼용(YAML은 탭을 금지합니다)
- 한 블록에서는 3칸, 다른 블록에서는 2칸 사용
- 목록 항목 정렬이 맞지 않음
AI 보조 생성
AgentBuilder 같은 도구를 사용하면 자연어로 설정을 설명하고 검증된 YAML을 출력할 수 있습니다. 이 “설명 → 생성 → 검증” 주기는 들여쓰기 오류와 노르웨이 문제를 모두 방지하는 데 도움이 됩니다.
결론
자동 변환에는 yq -oy '.' file.toml을 사용하세요. 수동 작업 시 TOML 테이블을 YAML 들여쓰기로, 배열을 대시 접두사 목록으로 매핑하고, 불리언으로 오인될 수 있는 문자열에는 항상 따옴표를 사용하세요. 변환 후에는 배포 전에 YAML 출력을 반드시 검증하세요 — 잘못 정렬된 공백 하나나 따옴표 없는 NO 하나가 전체 파이프라인을 중단시킬 수 있습니다.
자주 묻는 질문
YAML은 TOML처럼 주석을 지원하나요?
네. 둘 다 한 줄 주석에 #를 사용합니다. YAML 주석은 여러 줄 문자열 파싱에 영향을 줄 수 있으므로, 확신이 없으면 주석을 별도의 줄에 배치하세요.
YAML에서 ‘노르웨이 문제’란 무엇인가요?
YAML 1.1에서는 NO(노르웨이의 국가 코드) 같은 따옴표 없는 문자열이 자동으로 불리언 false로 변환됩니다. TOML은 모든 문자열 값에 따옴표를 요구하여 이 문제를 피합니다. TOML을 YAML로 변환할 때, 애매할 수 있는 모든 문자열을 따옴표로 감싸세요.
깊은 중첩을 더 잘 처리하는 형식은 무엇인가요?
YAML입니다. TOML은 각 수준마다 [table.subtable.subsubtable] 같은 긴 헤더를 반복해야 하므로 장황해집니다. YAML은 동일한 계층 구조를 들여쓰기로 표현하여 깊은 중첩에서 더 간결하고 읽기 쉽습니다.
답글 남기기