YAML 검사: 입력하면서 문법 오류 확인
YAML을 붙여넣으면 입력하는 동안 YAML 검사가 실행되고, 문법 오류를 줄과 열 위치와 함께 쉬운 말로 설명해 줘요. 탭 들여쓰기, 중복된 키, 닫히지 않은 따옴표와 괄호, 들여쓰기처럼 보이지만 아닌 보이지 않는 줄바꿈 없는 공백도 찾아요. YAML은 내 브라우저 안에서만 검사하고 업로드하지 않아요.
YAML 검사기 사용 방법
YAML 입력란에 YAML을 붙여넣거나 입력하세요. 검사 버튼은 없어요. 텍스트는 실시간으로 검사돼요.
- 붙여넣은 텍스트는 바로 검사돼요. 입력하는 중에는 마지막 키를 누른 뒤 약 0.25초 후에 검사가 실행되고, 아주 큰 텍스트는 조금 더 걸려요. 새 결과가 나올 때까지 이전 결과는 흐리게 남아 있어요.
- 편집기 아래의 상자를 읽어 보세요. 초록색 올바른 YAML 상자는 문법이 맞다는 뜻이에요. 빨간색 “올바르지 않은 YAML” 상자(또는 “올바르지 않은 YAML: 문제 N개”)에는 잘못된 부분이 나열돼요.
- 각 문제에는 설명 문장, “N번째 줄, M번째 열”, 줄 번호가 붙은 해당 줄의 일부가 나와요. 위 두 줄과 아래 한 줄이 함께 보이고, 열 아래에 ^ 표시가 붙어요.
- 편집기에서 보기를 누르면 그 줄이 입력란에서 선택돼요. 고치면 상자가 초록색으로 바뀌어요.
문서마다 첫 번째 문법 오류만 알려줘요. 그다음 오류는 닫히지 않은 따옴표가 아래 줄을 삼키는 것처럼 부수적인 경우가 많기 때문이에요. 중복된 키와 정의되지 않은 별칭은 항상 모두 나열돼요. 문제는 최대 20개까지 보여줘요.
YAML 오류 원인과 해결 방법
오류는 파서의 원문 메시지 대신 한 문장으로 설명해요. 가장 자주 만나는 경우는 이래요.
- 줄이 탭으로 들여쓰기되어 있어요. 편집기가 탭을 넣었거나 붙여넣은 텍스트에 탭이 들어 있었어요. 탭을 공백으로 바꾸세요.
- 줄이 같은 매핑의 다른 키와 맞지 않아요. 키 하나가 옆 키보다 공백이 하나 많거나 적어요. 같은 단계의 키는 들여쓰기를 똑같이 맞추세요.
- 들여쓰기가 잘못됐어요. 중첩된 블록이 부모보다 깊게 들여쓰이지 않았어요. 자식을 부모 키보다 더 깊게 들여쓰세요.
- 같은 매핑에 키가 여러 번 나와요. 복사한 블록이 키를 중복으로 남긴 경우가 많아요. 합치거나 중복을 지우세요.
- 줄이 키: 값 쌍이 아니에요. 콜론이 없거나, 줄바꿈된 줄이 들여쓰기되지 않았어요. 키 뒤에
:를 넣거나 이어지는 줄을 들여쓰세요. - 같은 줄에서 한 쌍 안에 다른 쌍이 들어 있어요. 따옴표 없는 값에 두 번째 콜론이 있는 경우가 많고,
a: b: c가 그 예예요. 값을 따옴표로 묶거나 들여쓴 새 줄로 옮기세요. - 괄호가 닫히지 않았거나 따옴표가 끝나지 않았어요. 메시지는 열린 줄을 가리켜요. 닫는 문자를 추가하세요.
[ ]나{ }안의 항목 사이에 쉼표가 없어요. 두 항목이 붙어 있어요. 쉼표를 추가하세요.- 값이
@나 백틱으로 시작해요. 값을 따옴표로 묶으세요. #이 앞 단어에 붙어 있어요. 앞에 공백이 있을 때만 주석이 시작돼요. 공백을 넣거나 텍스트를 따옴표로 묶으세요.\q는 큰따옴표 안에서 올바른 이스케이프가 아니에요. Windows 경로에서 자주 생겨요.\\로 쓰거나 작은따옴표를 쓰세요.- 별칭이 위쪽에 정의되지 않은 앵커를 가리켜요. 파일 앞쪽에서
&이름을 정의하세요. - 이 부분이 여기에 맞지 않아요.
-목록과키: 값줄이 같은 단계에 섞여 있거나 윗줄이 끝나지 않은 경우가 많아요. 목록을 자기만의 키 아래에 두고 윗줄을 확인하세요. - 문서 맨 위의
%지시문이 올바르지 않거나 지원되지 않아요. 지우거나%YAML,%TAG를 올바르게 쓰세요.
다른 도구의 오류 메시지는 무슨 뜻일까요
터미널이나 CI 로그의 오류를 보고 오셨나요? 흔한 표현이 이 검사기가 알려주는 내용과 어떻게 대응하는지 정리했어요. 같은 파일을 붙여넣으면 해당 줄을 보여줘요.
found character that cannot start any token while scanning for the next token: 줄 맨 앞의 탭이거나@나 백틱으로 시작하는 값이에요.tabs are not allowed for indent: 들여쓰기에 탭을 썼어요.mapping values are not allowed here:a: b: c처럼 한 줄에 두 번째 콜론이 있거나, 따옴표 없는 값에:가 들어 있거나, 이미 값이 있는 키 아래에 줄이 들여쓰기되어 있어요.did not find expected key: 같은 매핑의 다른 키와 맞지 않는 줄이에요.bad indentation of a mapping entry: 깊이가 잘못된 키예요.could not find expected ':': 키 뒤에 콜론이 없는 줄이에요.
표현은 파서(PyYAML, js-yaml, Ruby, Go, Home Assistant와 ESPHome의 로더)마다 다르고, 파서는 실제 실수보다 아래 줄을 알려주는 경우도 많아요. 이 검사기는 보여줄 수 있는 줄을 가리켜요.
탭과 보이지 않는 문자 찾기
YAML에서 가장 찾기 어려운 두 가지 실수는 눈에 보이지 않는 것들이에요. 이 검사기는 그것들을 보이게 해줘요.
- 일부 안의 탭은 화살표로, 줄바꿈 없는 공백이나 너비가 없는 공백은 점으로 그려져요.
- 오류가 있는 줄에 보이지 않는 문자가 있으면 코드 포인트(예:
U+00A0)와 열을 알려주는 줄이 추가돼요. 줄바꿈 없는 공백, 너비가 없는 문자, 바이트 순서 표시, 전각 공백이 대상이에요. - 파일은 올바른데 어떤 줄이 보이지 않는 공백으로 시작하면, 초록색 상자 아래에 노란색 올바르지만 확인이 필요한 줄이 있어요 상자가 나타나요. YAML이 그 문자를 키의 일부로 읽기 때문에 그 줄은 실제로 들여쓰기된 게 아니에요. 웹 페이지나 위키, 채팅 앱에서 복사한 텍스트가 흔한 원인이에요.
예를 들어 server: 아래에 port: 8080이 있는 파일에서 마지막 줄 host: example.com이 공백 두 개 대신 줄바꿈 없는 공백 두 개로 시작한다고 해요. YAML은 이 줄을 별도의 최상위 키로 읽고, host는 server의 자식이 아니에요. 노란색 상자가 그 문자와 줄을 알려줘요.
YAML 포맷과 결과 복사
입력란 위의 YAML 포맷 스위치를 켜세요. 기본값은 꺼져 있어요. 텍스트가 올바르면 포맷된 YAML 블록이 나타나고, 그 위에 복사 버튼이 있어요. 복사하면 복사했어요로 바뀌어요. 포맷 결과는 예측할 수 있어요.
- 들여쓰기는 공백 2칸이에요. 다른 너비는 없고, 키 아래의 목록도 들여쓰기돼요.
- 주석, 앵커, 별칭, 따옴표 스타일, 키 순서는 그대로 유지돼요.
- 긴 줄은 줄바꿈하지 않아요.
- 여러 문서는
---구분선을 유지해요.
올바른 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만 자예요. 일반적인 설정 파일은 순식간에 검사되고, 한도에 가까운 텍스트는 몇 초가 걸리고 메모리를 많이 써요. 한도를 넘으면 더 작은 부분을 붙여넣으라고 안내해요.