도움말

YAML 검사: 입력하면서 문법 오류 확인

YAML을 붙여넣으면 입력하는 동안 YAML 검사가 실행되고, 문법 오류를 줄과 열 위치와 함께 쉬운 말로 설명해 줘요. 탭 들여쓰기, 중복된 키, 닫히지 않은 따옴표와 괄호, 들여쓰기처럼 보이지만 아닌 보이지 않는 줄바꿈 없는 공백도 찾아요. YAML은 내 브라우저 안에서만 검사하고 업로드하지 않아요.


YAML 검사기 사용 방법

YAML 입력란에 YAML을 붙여넣거나 입력하세요. 검사 버튼은 없어요. 텍스트는 실시간으로 검사돼요.

  1. 붙여넣은 텍스트는 바로 검사돼요. 입력하는 중에는 마지막 키를 누른 뒤 약 0.25초 후에 검사가 실행되고, 아주 큰 텍스트는 조금 더 걸려요. 새 결과가 나올 때까지 이전 결과는 흐리게 남아 있어요.
  2. 편집기 아래의 상자를 읽어 보세요. 초록색 올바른 YAML 상자는 문법이 맞다는 뜻이에요. 빨간색 “올바르지 않은 YAML” 상자(또는 “올바르지 않은 YAML: 문제 N개”)에는 잘못된 부분이 나열돼요.
  3. 각 문제에는 설명 문장, “N번째 줄, M번째 열”, 줄 번호가 붙은 해당 줄의 일부가 나와요. 위 두 줄과 아래 한 줄이 함께 보이고, 열 아래에 ^ 표시가 붙어요.
  4. 편집기에서 보기를 누르면 그 줄이 입력란에서 선택돼요. 고치면 상자가 초록색으로 바뀌어요.

문서마다 첫 번째 문법 오류만 알려줘요. 그다음 오류는 닫히지 않은 따옴표가 아래 줄을 삼키는 것처럼 부수적인 경우가 많기 때문이에요. 중복된 키와 정의되지 않은 별칭은 항상 모두 나열돼요. 문제는 최대 20개까지 보여줘요.

YAML 오류 원인과 해결 방법

오류는 파서의 원문 메시지 대신 한 문장으로 설명해요. 가장 자주 만나는 경우는 이래요.

다른 도구의 오류 메시지는 무슨 뜻일까요

터미널이나 CI 로그의 오류를 보고 오셨나요? 흔한 표현이 이 검사기가 알려주는 내용과 어떻게 대응하는지 정리했어요. 같은 파일을 붙여넣으면 해당 줄을 보여줘요.

표현은 파서(PyYAML, js-yaml, Ruby, Go, Home Assistant와 ESPHome의 로더)마다 다르고, 파서는 실제 실수보다 아래 줄을 알려주는 경우도 많아요. 이 검사기는 보여줄 수 있는 줄을 가리켜요.

탭과 보이지 않는 문자 찾기

YAML에서 가장 찾기 어려운 두 가지 실수는 눈에 보이지 않는 것들이에요. 이 검사기는 그것들을 보이게 해줘요.

예를 들어 server: 아래에 port: 8080이 있는 파일에서 마지막 줄 host: example.com이 공백 두 개 대신 줄바꿈 없는 공백 두 개로 시작한다고 해요. YAML은 이 줄을 별도의 최상위 키로 읽고, host는 server의 자식이 아니에요. 노란색 상자가 그 문자와 줄을 알려줘요.

YAML 포맷과 결과 복사

입력란 위의 YAML 포맷 스위치를 켜세요. 기본값은 꺼져 있어요. 텍스트가 올바르면 포맷된 YAML 블록이 나타나고, 그 위에 복사 버튼이 있어요. 복사하면 복사했어요로 바뀌어요. 포맷 결과는 예측할 수 있어요.

올바른 YAML만 포맷할 수 있어서 망가진 파일은 고치지 못해요. 먼저 오류를 고치세요. 아주 긴 결과는 60만 자에서 잘려서 보이지만, 복사하면 전체가 복사돼요.

YAML 문법 검사기의 사용처와 한계

YAML이 무엇을 위한 것이든 검사는 똑같아요. GitHub Actions 워크플로, docker-compose.yml, Kubernetes 매니페스트와 Helm 값, OpenAPI 파일, Ansible 플레이북, Home Assistant 설정, CloudFormation 템플릿, mkdocs 설정에 쓸 수 있어요. 커밋하거나 푸시하기 전에 파일을 붙여넣으면 CI 실행을 기다리지 않고 문법 오류를 알 수 있어요. ---로 구분된 여러 문서가 든 파일은 문서마다 검사하고, 초록색 상자에 찾은 개수가 나와요. 앵커(&이름)와 별칭(*이름)도 검사하며, 앞에 앵커가 없는 별칭은 알려줘요. CloudFormation의 !Ref, !Sub, !GetAtt나 GitLab의 !reference 같은 사용자 지정 태그는 올바른 것으로 받아들여요.

검사는 브라우저의 Web Worker에서 실행돼요. 일반적인 설정, CI, Kubernetes 파일은 순식간에 검사돼요. 한도는 500만 자이고, 한도에 가까운 텍스트는 몇 초가 걸리고 메모리를 많이 써요. 한도를 넘으면 더 작은 부분을 붙여넣으라고 안내해요.

검사하는 것은 YAML 문법뿐이에요. 특정 도구가 무엇을 기대하는지는 알지 못해서 Kubernetes 필드, GitHub Actions나 Docker Compose의 키, JSON Schema 규칙은 검사하지 않고, 키 이름의 철자가 틀려도 통과해요. YAML 1.2를 따르므로 YAML 1.1의 단어 yes, no, on, off는 일반 텍스트이고 판단하지 않아요. 아무것도 실행하거나 가져오거나 불러오지 않으며, 혼자 있는 옛 Mac 캐리지 리턴은 줄바꿈으로 취급하지 않아요.

다른 형식을 다루고 있나요? JSON은 JSON 포맷터로 정리하고 확인하고, 스키마와 대조할 때는 JSON 스키마 검증기를, 마크업을 확인할 때는 XML 유효성 검사기를 쓰세요. 설정에서 패턴을 찾고 있다면 정규식 테스터에서 시험해 보세요.


자주 묻는 질문

YAML 검사는 어떻게 하나요?

“YAML” 입력란에 YAML을 붙여넣으세요. 붙여넣거나 입력할 때마다 검사되므로 누를 버튼은 없어요. 초록색 “올바른 YAML” 상자는 문법이 맞다는 뜻이에요. 빨간색 “올바르지 않은 YAML” 상자에는 각 문제가 쉬운 말과 “N번째 줄, M번째 열”, 해당 줄의 일부와 함께 나와요.

YAML에서 들여쓰기에 탭을 쓸 수 없다고 나오는 이유는 무엇인가요?

YAML은 들여쓰기에 공백만 허용하고, 줄 맨 앞의 탭은 문법 오류예요. 편집기는 Tab 키를 누르면 탭을 넣는 경우가 많고, 붙여넣은 텍스트에 탭이 섞여 있기도 해요. 검사기가 그 줄이 탭으로 들여쓰기되었다고 알려줘요. 탭을 공백으로 바꾸세요.

YAML의 mapping values are not allowed here는 무슨 뜻인가요?

대개 “a: b: c”처럼 한 줄에 두 번째 콜론이 있거나, 따옴표 없는 값에 콜론이 들어 있어요. 이미 값이 있는 키 아래에 줄이 들여쓰기된 경우도 있어요. 값을 따옴표로 묶거나 안쪽 쌍을 들여쓴 별도의 줄에 쓰세요.

YAML의 did not find expected key는 무슨 뜻인가요?

어떤 줄이 같은 매핑의 다른 키와 맞지 않아요. 대개 키 하나가 옆 키보다 공백이 하나 많거나 적어요. 같은 단계의 모든 키를 똑같이 들여쓰세요. 검사기는 그 줄이 다른 키와 맞지 않는다고 알려줘요.

YAML에서 중복된 키는 어떻게 찾나요?

텍스트를 붙여넣으세요. 같은 매핑 안의 중복된 키는 항상 모두 줄과 열 위치와 함께 나열돼요. 복사한 블록이 키를 중복으로 남긴 경우가 많아요. 합치거나 중복을 지우세요.

올바른 YAML인데 왜 “올바르지만 확인이 필요한 줄이 있어요”라고 나오나요?

어떤 줄이 줄바꿈 없는 공백 같은 보이지 않는 공백으로 시작해요. YAML은 그것을 키의 일부로 읽기 때문에 파일이 올바르더라도 그 줄은 실제로 들여쓰기된 게 아니에요. 노란색 상자가 그 문자와 줄을 알려줘요. 지우고 일반 공백을 입력하세요.

GitHub Actions, Docker Compose, Kubernetes YAML도 여기서 확인할 수 있나요?

네, 문법 검사는 어떤 YAML이든 똑같아요. 워크플로, docker-compose.yml, Kubernetes 매니페스트 등 많은 파일에 쓸 수 있어요. 검사하는 것은 문법뿐이고 각 도구가 어떤 키를 기대하는지는 알지 못해서 키 이름의 철자가 틀려도 통과해요.

얼마나 큰 YAML 파일까지 검사할 수 있나요?

한도는 500만 자예요. 일반적인 설정 파일은 순식간에 검사되고, 한도에 가까운 텍스트는 몇 초가 걸리고 메모리를 많이 써요. 한도를 넘으면 더 작은 부분을 붙여넣으라고 안내해요.