YAML & TOML 설정 완전 가이드

둘 다 사람이 읽는 설정 형식이지만 YAML은 들여쓰기와 유연한 문법을, TOML은 명시적 자료형과 섹션을 중시합니다. 도구의 요구사항과 편집 안정성을 기준으로 선택하세요.

Kubernetes YAML 규칙

YAML은 매핑, 시퀀스, 스칼라를 표현합니다. 일반 블록 문법에서는 들여쓰기가 계층을 정하며 Kubernetes와 Docker Compose 설정에 사용됩니다. 들여쓰기에는 탭 대신 공백을 쓰세요. 단계당 두 칸은 관례이고 필요한 깊이는 구조가 결정합니다.

key: value에서는 콜론 다음 공백이 키와 값을 구분합니다. key:value는 문자열로 해석될 수 있습니다. 특수 문자나 숫자·불리언 해석을 피해야 하는 값에는 따옴표를 사용하세요.

YAML 1.1은 yes, no, on, off도 불리언으로 읽지만 YAML 1.2와 실제 파서는 다를 수 있습니다. ---는 여러 Kubernetes 리소스 같은 문서를 구분합니다. YAML 포매터와 대상 시스템에서 모두 확인하세요.

YAML 오류 예방

보이지 않는 탭과 어긋난 형제 요소는 구문 오류나 구조 변경을 일으킬 수 있습니다. 편집기에서 공백 표시를 켜세요. 들여쓰기 깊이가 다른 것 자체가 금지는 아니며 의도한 계층인지가 중요합니다.

암묵적 자료형은 버전과 스키마에 달려 있습니다. 선행 0에 주의하세요. YAML 1.1에서는 0644가 8진수로 해석될 수 있습니다. 식별자나 버전 번호를 문자열로 남기려면 따옴표를 쓰고 다른 파서의 동작을 가정하지 마세요.

앵커 &name과 별칭 *name은 값을 재사용하지만 대상마다 지원이 다릅니다. YAML→JSON에서 확장 결과를 확인하세요. JSON에는 주석과 별칭 문법이 없으므로 원래 표현 일부는 사라집니다.

TOML 구조

TOML은 사람이 편집하는 설정용으로 만들어졌으며 키-값과 [package], [dependencies], [dev-dependencies] 같은 섹션을 사용합니다. Rust Cargo와 Python pyproject.toml이 대표적입니다. PEP 518은 2016년에 Python 빌드 요구사항에 TOML을 채택했습니다.

[[table]]은 테이블 배열 항목을 시작합니다. 문자열, 정수, 부동소수점, 불리언, 날짜·시간, 배열, 인라인 테이블에는 정해진 문법이 있습니다. port = 8080은 숫자이고 port = "8080"은 문자열입니다. null 자료형은 없습니다.

문자열 밖의 #부터 주석이 시작됩니다. 여러 줄 문자열과 날짜에 대해 파서 버전과 지원 기능을 확인하세요. TOML 포매터로 점검한 후 대상 프로그램도 파일을 받아들이는지 검증합니다.

YAML, TOML, JSON 선택

Kubernetes, Helm, Ansible처럼 플랫폼이 요구할 때 YAML을 사용하세요. 주석과 별칭은 유용하지만 자료형과 구조를 점검해야 합니다. TOML은 사람이 자주 편집하는 체계적인 설정에 적합합니다.

JSON은 API나 package.json에 널리 지원되며 규칙이 엄격합니다. 표준 JSON은 주석을 허용하지 않습니다. 특정 애플리케이션이 주석 있는 JSON을 읽어도 규격이 바뀌지는 않습니다.

JSON→YAML, JSON→TOML, YAML→JSON, TOML→JSON은 로컬에서 변환합니다. null, 날짜, 숫자, 중첩 배열을 확인하세요. 주석, 서식, 모든 특수 자료형 정보가 자동으로 보존되지는 않습니다.

자주 묻는 질문