← 전체 글
업데이트: May 29, 20266 min read

YAML 포매터: YAML 포맷, 재들여쓰기, 검증

YAML 포매터는 YAML을 재들여쓰기하고 정규화해 읽기 좋고 diff하기 좋게 만든다. 들여쓰기 규칙, 타입 함정, 포맷 vs JSON 변환 사용 시점을 배운다.

YAML 은 공백이 의미를 가지므로, 잘못 들어간 tab 이나 일관성 없는 들여쓰기는 단순히 지저분해 보이는 정도가 아니라 의미를 바꾸거나 파싱을 깨뜨립니다. YAML formatter 가 그 문제를 해결합니다: YAML 을 일관된 깊이로 다시 들여쓰고, 띄어쓰기를 정규화하고, (선택적으로) key 를 정렬해서 파일을 가독성 있고 diff 가 깔끔하게 만들어 줍니다. 이 가이드는 YAML formatter 가 무엇을 하는지, 어떤 들여쓰기 규칙을 강제하는지, 조심해야 할 타입 함정, 그리고 언제 YAML 을 포매팅할지 vs JSON 으로 변환할지를 설명합니다.

YAML Formatter 가 하는 일

formatter 는 YAML 을 데이터 구조로 파싱한 뒤 일관된 스타일로 다시 직렬화합니다. 데이터는 그대로 —— 표현만 정규화됩니다:

  • 다시 들여쓰기: 모든 레벨을 고정된 폭(보통 2 스페이스)으로 통일하고 tab 을 스페이스로 치환
  • 공백 정규화: 콜론 주변, 리스트 dash 주변, 인라인 컬렉션 주변
  • 선택적으로 key 정렬: canonical 하고 diff 친화적인 순서로
  • 부수적으로 검증 —— 파싱이 안 되면 먼저 고쳐야 할 구문 오류가 있다는 뜻
# 이전 —— 들여쓰기가 뒤죽박죽, 훑어 보기 어려움
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# 이후 —— 2 스페이스 들여쓰기, 정규화됨
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

왜 YAML 을 포매팅하는가

  • 가독성 —— CI 파이프라인, Kubernetes manifest, Docker Compose 파일은 깊이 중첩되는데, 일관된 들여쓰기가 있어야 훑어 볼 수 있습니다.
  • 깔끔한 diff 와 review —— 정규화된 포맷(과 정렬된 key)은 PR 에 진짜 변경만 보이게 하고 공백 노이즈를 없애 줍니다.
  • 오류 조기 발견 —— 포매팅은 유효한 YAML 에서만 성공하니, formatter 가 곧 빠른 유효성 검사이기도 합니다.
  • 팀 전반의 일관성 —— 작성자별 들여쓰기 습관 대신 한 가지 스타일을 자동 적용.

Formatter 가 강제하는 들여쓰기 규칙

YAML 오류의 대부분이 들여쓰기 오류이고, 바로 그것이 formatter 가 표준화하는 부분입니다:

  • 오직 스페이스 —— tab 은 절대 안 됨. YAML 은 들여쓰기에 tab 문자를 금지합니다. tab 하나가 가장 흔한 "왜 파싱이 안 되지?" YAML 버그입니다.
  • 일관된 깊이. 형제 key 들은 부모 기준으로 같은 스페이스 수만큼 들여쓰여야 합니다. formatter 가 모든 것을 하나의 고정 폭으로 다시 씁니다.
  • 리스트 정렬. 블록 시퀀스(-)의 아이템은 key 아래에 정렬됩니다; formatter 가 dash 를 들여쓸지, 맞춰 놓을지 정규화합니다.

다시 포매팅할 때의 타입 함정

포매팅은 데이터를 보존하지만, 값이 따옴표 없이 쓰여 있으면 YAML 의 타입 추론이 깜짝 놀라게 할 수 있습니다 —— 출력을 신뢰하기 전에 알아 둘 만합니다:

  • "Norway problem". 따옴표 없는 NO, yes, on, off 가 boolean 으로 읽힐 수 있어, 국가 코드 NO 가 false 가 됩니다. 문자열로 유지하려는 값은 따옴표로 감싸세요.
  • 선행 0 과 큰 수.007 는 숫자로 읽히면 0 들을 잃을 수 있고, 매우 큰 정수는 정밀도를 잃을 수 있습니다. 문자열로 유지해야 하는 ID 는 따옴표로.
  • 날짜와 타임스탬프. 일부 파서는 따옴표 없는 날짜 같은 문자열을 타임스탬프 타입으로 강제 변환합니다. 리터럴 문자열이 필요하면 따옴표를 씌우세요.

블록 스타일 vs 플로우 스타일

YAML 은 컬렉션을 쓰는 방법이 두 가지입니다: block(들여 쓴, 줄 단위)과 flow(인라인, JSON 같은 형태로 [] / {} 사용):

# block
ports:
  - 80
  - 443

# flow (같은 데이터)
ports: [80, 443]

formatter 는 보통 가독성을 위해 block 스타일로 정규화합니다. flow 스타일은 JSON 호환 —— JSON 만 받는 도구에 YAML 을 끼워 넣을 때 유용 —— 하지만 중첩이 깊어질수록 훑어 보기 어렵습니다.

앵커와 별칭: 재사용 가능한 스니펫

& 가 anchor 를 표시하고 * 가 그것을 참조합니다. 복붙 없이 서비스 간 설정을 공유할 때 유용하고, formatter 가 이들을 보존합니다:

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

주의: JSON 으로 변환하면 anchor 와 alias 는 사라집니다 —— JSON 에는 참조 타입이 없어서 값이 인라인되기 때문입니다. YAML → JSON → YAML 왕복하면 잃어버립니다.

파싱을 넘는 Lint: yamllint

formatter 는 형태를 정규화하고, yamllint 는 스타일 가이드(줄 길이, key 순서, 문서 시작 마커, truthy 값, 주석 띄어쓰기)를 강제합니다. CI 에서 짝지어 쓰세요: 먼저 format, 다음에 팀이 고른 규칙으로 lint.

YAML 을 포매팅할지, JSON 으로 변환할지

포매팅은 파일을 YAML 로 유지합니다 —— 사람이 계속 편집할 때 최적. JSON 변환은 프로그램이 소비할 때(대부분 앱은 런타임에 JSON 만 파싱). YAML 1.2 는 JSON 의 엄격한 상위집합이므로 데이터적으로는 무손실 변환입니다; YAML 을 JSON 으로 변환 과 JSON vs YAML 에서 언제 무엇을 쓸지 참고.

브라우저에서 YAML 포매팅 & 검증

YAML 을 fixjson 의 YAML 검증기 & 포매터 에 붙여 넣고 Format YAML 을 눌러 다시 들여쓰기 & 정규화 하거나, To JSON 으로 변환하세요. 모든 구문 오류의 정확한 줄 번호를 보고하고, 모든 것이 브라우저에서 동작합니다 —— 업로드 없음 —— 호스트명, 시크릿, 사내 설정이 들어 있는 설정 파일에 중요합니다.

자주 묻는 질문

YAML formatter 는 무엇을 하나요?

YAML 을 파싱한 뒤 일관된 들여쓰기와 띄어쓰기(필요하면 정렬된 key 포함)로 다시 직렬화해서 파일을 가독성 있고 diff 친화적으로 만들어 줍니다. 데이터는 그대로 —— 포맷만 정규화됩니다.

내 YAML 은 왜 파싱이 안 되나요?

거의 항상 들여쓰기: tab 문자(YAML 은 들여쓰기에 tab 금지)나 형제 key 들이 깊이가 들쭉날쭉. formatter 는 모든 것을 스페이스 기반의 단일 폭으로 다시 쓰므로 대부분이 드러나고 고쳐집니다.

YAML 포매팅이 데이터를 바꾸나요?

아니요 —— 공백과 key 순서만 바뀝니다. 다만 따옴표 없는 값은 조심: YAML 이 타입을 추론할 수 있습니다("Norway problem"). NO 나 007 처럼 문자열을 유지해야 하는 값은 따옴표로 감싸세요.

YAML 을 포매팅할지, JSON 으로 변환할지?

사람이 계속 편집하면 포매팅; 프로그램이 소비하면 JSON 변환. 많은 팀이 YAML 로 작성하고 로드 시 JSON 으로 변환합니다.

관련 도구 & 가이드