YAML 검증 도구 활용법 - 들여쓰기 오류 없이 설정 파일 작성하는 완벽 가이드

Docker Compose 파일을 저장하고 컨테이너를 띄우려는 순간 mapping values are not allowed here라는 빨간 에러를 만난 적이 있을 겁니다. 어디가 틀렸는지 한참 들여다봐도 보이지 않습니다. 알고 보면 탭과 스페이스가 섞였거나, 콜론 뒤에 공백이 빠진 사소한 문제인 경우가 대부분입니다. YAML은 사람이 읽기 쉽도록 설계됐지만, 그만큼 들여쓰기 한 칸에 민감합니다.

이런 실수를 배포 전에 미리 걸러주는 것이 YAML 검증 도구입니다. 어떤 도구가 있고 상황별로 무엇을 써야 하는지 정리했습니다.

YAML에서 자주 발생하는 오류

YAML 검증 도구가 필요한 이유는, 사람 눈으로는 잘 안 보이는 오류가 많기 때문입니다. 가장 흔한 실수는 다음과 같습니다.

• 탭과 스페이스 혼용 - YAML은 들여쓰기에 탭을 허용하지 않습니다. 에디터가 탭을 자동 삽입하면 바로 파싱 오류가 납니다.
• 콜론 뒤 공백 누락 - key:value는 틀리고 key: value가 맞습니다.
• 들여쓰기 깊이 불일치 - 같은 레벨인데 2칸과 4칸이 섞이면 구조가 깨집니다.
• 특수문자 처리 - 콜론, 따옴표, 백슬래시가 값에 들어가면 인용부호로 감싸야 합니다.

YAML 오류의 80퍼센트 이상은 들여쓰기와 공백 문제입니다. 즉 문법을 깊이 몰라도, 검증 도구 하나만 잘 쓰면 대부분의 사고를 막을 수 있습니다.

YAML 검증 도구 종류와 비교

YAML 검증 도구는 크게 세 갈래입니다. 브라우저에서 바로 쓰는 온라인 도구, 터미널에서 돌리는 명령줄 도구, 그리고 에디터에 내장된 실시간 검사 기능입니다. 각각 장단점이 분명합니다.

온라인 YAML 검증 도구 사용법

가장 손쉬운 방법입니다. 검증할 YAML 내용을 입력창에 붙여넣고 버튼을 누르면, 문법 오류가 있는 줄 번호와 원인을 알려줍니다. 유효한 경우 JSON으로 변환한 결과를 함께 보여주는 도구도 많아, 구조가 의도대로 잡혔는지 한눈에 확인할 수 있습니다.

온라인 도구를 쓸 때 체크할 점

• 줄 번호와 함께 오류 메시지를 보여주는지
• 변환된 JSON 결과를 같이 표시하는지
• 입력 내용을 서버에 저장하지 않는지

이런 단일 기능 웹 도구는 개발 외에도 곳곳에서 쓰입니다. 설정 값으로 고유 식별자가 필요할 때 쓰는 UUID 생성기처럼, 한 가지 일만 깔끔하게 처리하는 도구를 즐겨찾기에 두면 작업 흐름이 훨씬 빨라집니다.

명령줄 도구 yamllint 활용

파일이 수십 개로 늘어나면 일일이 복사해 붙여넣는 방식은 비효율적입니다. 이때 yamllint가 강력합니다. 파이썬 기반 도구로, 설치 후 폴더 전체를 한 번에 검사할 수 있습니다.

설치는 간단합니다.

• pip install yamllint 로 설치
• yamllint config.yml 으로 단일 파일 검사
• yamllint . 으로 현재 폴더 전체 검사

yamllint는 단순 문법 오류뿐 아니라 줄 끝 공백, 빈 줄 개수, 들여쓰기 규칙 같은 스타일까지 잡아줍니다. 규칙이 너무 엄격하다면 .yamllint 설정 파일로 팀에 맞게 조정할 수 있습니다.

스키마 검증으로 한 단계 더

문법이 맞다고 해서 설정이 올바른 것은 아닙니다. 필수 항목이 빠졌거나, 숫자가 들어갈 자리에 문자열이 들어가도 YAML 문법상으로는 통과합니다. 이런 의미 단위의 오류는 스키마 검증으로 잡습니다.

JSON Schema를 활용하면 각 필드의 타입, 필수 여부, 허용 값 범위를 미리 정의해 두고 그에 맞는지 검사할 수 있습니다. VS Code의 YAML 확장은 쿠버네티스나 GitHub Actions 같은 잘 알려진 포맷의 스키마를 자동으로 인식해, 잘못된 키를 입력하면 즉시 빨간 밑줄로 알려줍니다.

문법 검증이 맞춤법 검사라면, 스키마 검증은 문장이 말이 되는지 확인하는 단계입니다. 운영 환경에 올라가는 설정일수록 두 단계를 모두 거쳐야 합니다.

실무 워크플로우에 통합하기

가장 이상적인 방식은 검증을 사람의 기억이 아니라 자동화에 맡기는 것입니다. 세 지점에 검증을 걸어 두면 실수가 운영까지 흘러가지 않습니다.

• 작성 단계 - 에디터 확장으로 실시간 오류 표시
• 커밋 단계 - pre-commit 훅에 yamllint 연결
• 배포 단계 - CI 파이프라인에서 검증 실패 시 중단

이렇게 세 겹의 안전망을 두면, YAML 한 줄 때문에 배포가 멈추거나 서비스가 죽는 사고를 거의 없앨 수 있습니다. 처음 환경을 갖추는 데 30분이면 충분하고, 그 효과는 프로젝트 내내 이어집니다. 온라인 단일 기능 도구를 평소 활용하던 분이라면 학점 계산기 같은 일상 도구를 찾듯, 검증 도구도 자신의 작업 환경에 맞는 것을 하나 정해 두면 됩니다.

지금 바로 두 가지만 시작해 보세요. 첫째, 에디터에 YAML 확장을 설치해 작성 중 오류를 실시간으로 확인하기. 둘째, 자주 다루는 프로젝트에 yamllint를 붙여 커밋 전에 자동 검사하기. 이 두 가지만으로도 들여쓰기 오류로 시간을 날리는 일이 크게 줄어듭니다.