데이터 형식·구조화 데이터
읽히지 않는 YAML 설정의 문법 확인하기
사용할 도구
설정을 복사해 몇 줄 추가했더니 한 서비스만 설정이 먹지 않습니다. 탭을 공백으로 고쳐 오류는 없어졌지만 동작은 그대로입니다. YAML 문제는 문법 오류만이 아닙니다. 유효한 텍스트로 의도와 다른 계층을 만들 수도 있습니다.
실제 서비스에 적용하지 않고 가상의 server와 worker로 읽는 방법을 확인합니다. YAML 정렬·검증으로 문법을 보고 필요하면 JSON–YAML 변환으로 구조와 자료형을 확인하세요. 정렬 성공만으로 운영 설정을 덮어쓰는 대신 각 필드의 부모를 설명할 수 있게 하는 것이 목표입니다.
수정 전에 문제를 작게 분리하기
수백 줄 설정에서 오류가 나면 작업 사본을 만들고 관련 부모와 자식만 분리하세요. 자식만 복사하면 들여쓰기 문맥이 바뀌어 재현이 안 될 수 있습니다. 부모 줄을 남기고 편집기에서 공백을 표시하며 탭과 공백을 구분하세요. 전체 치환보다 원인과 수정의 관계를 확인하기 쉽습니다.
공백 두 칸이 설정의 소속을 바꿉니다
server:
host: example.invalid
timeout: 30
worker:
enabled: true
server:
host: example.invalid
timeout: 30
worker:
enabled: true
두 예제를 각각 YAML 정렬·검증에 넣습니다. 둘 다 읽히지만 A는 timeout이 server 안에, B는 server와 같은 계층에 있습니다. 오류 확인 다음에는 어느 부모 아래 있는지 보세요. 줄 앞 공백은 장식이 아닙니다.
차이가 잘 안 보이면 JSON–YAML 변환으로 중괄호 범위를 비교하세요. A는 server.timeout, B는 최상위 timeout입니다. 변환은 관계 확인용이지 JSON으로 이전하라는 뜻이 아닙니다. 올바른 위치는 대상 서비스 규격으로 판단합니다.
하이픈 하나가 새 목록 항목을 만듭니다
services:
- name: api
port: 8080
- name: worker
port: 8081
하이픈 두 개에 목록 항목도 두 개입니다. 각 port는 앞의 name과 같은 항목입니다. port 앞에도 하이픈을 넣으면 포트만 가진 별도 항목이 되어 겉보기 비슷한 네 항목이 될 수 있습니다. 개수와 이름·포트의 묶음을 함께 확인하세요.
정렬기는 두 항목을 원했는지 네 항목을 원했는지 모릅니다. 읽힌 구조를 정렬할 뿐입니다. 다른 계층으로 옮길 때는 한 줄만 움직이지 말고 속한 자식 전체를 확인하세요. 예상 항목 수를 먼저 적어 두면 의도치 않은 재묶음을 찾기 쉽습니다.
false와 "false"는 다른 값입니다
enabled: false
label: "false"
count: 3
code: "003"
note: null
empty: ""
JSON으로 바꾸면 enabled는 불리언, label은 문자열, count는 숫자, code는 앞의 0을 가진 문자열입니다. note는 null, empty는 빈 문자열입니다. 비슷하게 보여도 프로그램이 같게 처리하지 않습니다. 번호를 숫자로 읽어 앞의 0이 사라지면 나중에 정렬해도 복원할 수 없습니다.
모든 값에 따옴표를 붙이는 것도 정답은 아닙니다. true나 30을 문자열로 바꾸면 요구 자료형과 달라질 수 있습니다. 따옴표는 오류 숨기기가 아니라 문자열 의도를 나타내는 데 쓰세요. YAML 버전과 판독기 차이도 있어 다른 도구에서 읽혔다고 실제 수신 측 검증을 생략해서는 안 됩니다.
키를 두 번 쓰면 뒤의 값이 이길까요?
timeout: 30
timeout: 60
SheepDev는 이를 중복 키 오류로 거부합니다. 뒤의 값이 우선한다고 가정하지 말고 남길 값을 결정하세요. 별도 설정 파일을 겹치는 것과 한 매핑에 같은 키를 반복하는 것은 다릅니다. 프레임워크의 파일 병합 규칙을 문서 내부 중복에 적용하지 마세요.
반면 server.timeout과 worker.timeout은 부모가 달라 별도 설정입니다. timeout이 두 번 검색된다고 하나를 지우면 안 됩니다. 중복 수정도 부모 관계부터 확인하세요. 일반 중복 줄 제거기는 계층을 이해하지 못해 필요한 설정을 지울 수 있습니다.
두 줄 문장이 한 줄이 되는 이유
literal: |
first line
second line
folded: >
first line
second line
JSON으로 바꾸면 literal은 중간 줄바꿈을 유지하고 folded는 두 줄을 공백으로 연결합니다. 두 예제 모두 끝의 줄바꿈은 남습니다. 두 줄로 썼다고 읽은 문자열도 같지는 않습니다. 알림, 서명 대상 문장, 명령에 넘길 문자열에 영향을 줍니다.
이 실험은 같은 들여쓰기의 평범한 두 줄입니다. 빈 줄이나 추가 들여쓰기가 있는 글까지 '>는 전부 한 줄로 만든다'고 일반화하지 마세요. 실제 대표 문장을 잘라 변환 후 개행을 확인하세요. 보기 좋은 소스뿐 아니라 읽힌 문장이 의도와 맞는지 봐야 합니다.
복사할 때 주석과 값의 경계도 확인하기
color: "#4F46E5"
message: "status: ready"
retries: 3 # calculation example
색상의 #나 문장 속 콜론을 문법이 아닌 내용으로 읽히게 하려면 문자열임을 명확히 하세요. retries 뒤 주석은 숫자 3의 일부가 아닙니다. 글의 예제를 복사할 때도 입력과 설명을 구별하세요. 수상해 보인다고 기호를 지우면 색상이나 문장을 망칠 수 있습니다.
JSON 변환 시 주석은 일반 데이터로 남지 않습니다. YAML 정렬과 다른 형식 변환은 보존 정보가 다릅니다. 주석에 운영 판단 근거가 있다면 변환 결과로 원본을 대체하지 마세요. 확인용 사본과 팀이 관리하는 정본을 구분하면 혼란을 막습니다.
읽히는 설정에서 의도한 설정으로
마지막으로 앱이 요구하는 필드명, 자료형, 필수 항목을 확인하세요. timeout이 초인지 밀리초인지, 허용 포트 범위는 YAML 문법이 정하지 않습니다. SheepDev는 서비스에 설정을 보내거나 적용하지 않고 앱 전용 시작 검사도 하지 않습니다. 대상 앱의 검증 명령이나 안전한 시험 환경이 다음 단계입니다.
수정을 설명할 때 '들여쓰기 수정'만으로는 부족할 수 있습니다. 'timeout을 최상위에서 server 아래로 돌리고 30은 유지했다'면 구조와 값을 따로 확인했음을 전합니다. 읽히는가, 계층이 의도와 맞는가, 앱 의미와 맞는가의 세 단계로 보면 공백만 쫓는 작업에서 벗어납니다.