YAML이란? 기본 문법·주석·작성법과 실무 활용 예제

Q: YAML은 무슨 뜻인가요?

"YAML Ain't Markup Language(YAML은 마크업 언어가 아니다)"의 약자입니다. 초기에는 "Yet Another Markup Language"였으나, 문서 서식이 아닌 순수한 데이터 표현 형식임을 나타내기 위해 재귀적 약어로 명칭이 바뀌었습니다.

Q: YAML은 프로그래밍 언어인가요?

아닙니다. YAML은 조건문이나 반복문, 함수와 같은 로직 제어 구조가 없는 순수 데이터 직렬화 형식입니다. 프로그램 간의 데이터 교환이나 설정 파일 작성에 사용됩니다.

Q: `.yml`과 `.yaml` 확장자에 차이가 있나요?

기능적인 차이는 전혀 없습니다. 모든 YAML 파서는 두 확장자를 동일하게 처리합니다. 공식 사양에서는 .yaml을 권장하지만, 역사적 관례와 편리성 때문에 1글자 짧은 .yml도 매우 널리 쓰입니다.

Q: 왜 Kubernetes나 GitHub Actions는 JSON 대신 YAML을 쓰나요?

사람이 직접 눈으로 확인하고 편집하기에 훨씬 직관적이기 때문입니다. 중괄호와 쉼표를 생략할 수 있어 시각적 피로도가 적고, 설정의 이유를 설명하는 주석(#)을 자유롭게 작성할 수 있기 때문입니다.

Q: YAML과 JSON의 주요 차이점은 무엇인가요?

두 형식은 동일한 데이터 구조(스칼라, 배열, 맵)를 표현할 수 있지만 구조 표현 방식이 다릅니다. YAML은 들여쓰기를 사용하며 주석, 여러 줄 문자열, 앵커 기능을 제공합니다. 반면 JSON은 중괄호와 쉼표를 사용하며 문법이 엄격하고 파싱 속도가 빨라 시스템 간 API 통신에 주로 쓰입니다.

Q: `country: NO`가 왜 `false`로 바뀌나요?

과거 YAML 1.1 사양에서 NO, no, YES, yes, ON, off 등을 불리언 값의 별칭으로 정의했기 때문입니다. 이를 피하려면 country: "NO"처럼 큰따옴표로 감싸서 명시적 문자열임을 지정해야 합니다.

TL;DR — 30초 만에 파악하는 YAML

YAML은 들여쓰기(공백)로 데이터 계층 구조를 표현하는 사람이 읽기 쉬운 데이터 직렬화 형식입니다.
문자열, 숫자, 불리언, null, 배열(리스트), 객체(매핑) 등 JSON과 동일한 데이터 모델을 다룹니다.
중괄호({})나 대괄호([]), 따옴표, 쉼표를 대폭 줄여 설정 파일(Configuration) 작성에 널리 쓰입니다.
Kubernetes 매니페스트, GitHub Actions 워크플로, Docker Compose, Ansible 등 주요 DevOps 도구의 기본 형식입니다.
JSON에는 없는 주석(#), 여러 줄 문자열(|, >), 앵커(&)와 별칭(*)을 통한 데이터 재사용을 지원합니다.
YAML을 JSON으로 변환하거나 문법 오류를 검사하고 싶다면 YAML to JSON 변환기를 이용하면 브라우저 안에서 안전하게 오류 줄 번호를 확인할 수 있습니다.

YAML이란?

YAML(야믈)은 사람이 쉽게 읽고 쓸 수 있도록 설계된 데이터 직렬화(Data Serialization) 언어입니다. 주로 애플리케이션 설정 파일이나 인프라 코드(IaC) 정의에 널리 사용됩니다.

YAML이라는 이름은 원래 "Yet Another Markup Language(또 다른 마크업 언어)"의 약칭이었으나, 문서 구조를 마크업하는 HTML/XML과 달리 순수 데이터 표현에 중점을 둔다는 점을 강조하기 위해 "YAML Ain't Markup Language(YAML은 마크업 언어가 아니다)"라는 재귀적 두문자어(Recursive Acronym)로 공식 명칭이 변경되었습니다.

YAML은 2001년 클라크 에반스(Clark Evans) 등이 제안했으며, 현재 널리 쓰이는 사양인 YAML 1.2는 JSON의 상위 집합(Superset)으로 정의되어 있습니다. 즉, 문법적으로 올바른 JSON 문서는 유효한 YAML 문서로도 해석될 수 있습니다. JSON의 기본 문법 규칙은 JSON 작성법 가이드에서 확인할 수 있습니다.

가장 큰 특징은 중괄호 대신 들여쓰기(Indentation)를 사용하여 계층 구조를 나타낸다는 점입니다.

동일한 데이터를 YAML과 JSON으로 작성해 비교하면 구조의 차이를 쉽게 이해할 수 있습니다.

name: Alice
age: 30
isStudent: false

{
  "name": "Alice",
  "age": 30,
  "isStudent": false
}

YAML은 중괄호, 키를 감싸는 큰따옴표, 줄 끝의 쉼표를 모두 생략하고 들여쓰기와 줄바꿈만으로 깔끔하게 표현합니다. 사람이 직접 손으로 편집하는 설정 파일에서 이러한 가독성은 큰 장점이 됩니다.

YAML 기본 문법과 작성 규칙

키와 값 (Key-Value)

콜론과 공백(: )으로 키와 값을 구분합니다. 콜론 뒤에는 반드시 공백(스페이스)이 1칸 이상 들어가야 합니다. 따옴표는 대부분의 경우 생략할 수 있습니다.

name: 홍길동
age: 30
city: 서울

따옴표가 필수인 경우는 다음과 같습니다.

다른 자료형으로 자동 해석될 수 있는 값 (version: "1.0", country: "NO", zip: "07030")
콜론(:), 하이픈(-), 해시(#), 대괄호([), 중괄호({) 등 문법 특수 문자가 포함된 문자열 (message: "Error: file not found")

들여쓰기와 계층 구조 (Nesting)

YAML은 공백(스페이스)을 이용한 들여쓰기로 부모-자식 관계를 표현합니다.

스페이스(Space)만 허용: 탭(Tab) 문자는 문법적으로 엄격히 금지됩니다.
일관된 너비: 보통 공백 2칸(2-space) 들여쓰기가 표준 권장 사항입니다.

user:
  name: 홍길동
  address:
    city: 서울특별시
    district: 강남구

배열 (리스트)

하이픈과 공백(- )을 사용하여 목록 항목을 작성합니다.

fruits:
  - 사과
  - 바나나
  - 오렌지

JSON처럼 한 줄로 작성하는 인라인(Flow) 문법도 지원합니다.

fruits: [사과, 바나나, 오렌지]

주석 (Comment)

# 기호를 사용하면 해당 위치부터 줄 끝까지가 주석으로 처리됩니다. JSON에서는 공식적으로 주석을 지원하지 않기 때문에, 설정 파일에 설명과 배경을 남길 수 있다는 점은 YAML의 가장 큰 장점 중 하나입니다. JSON에서 주석을 처리하는 대안은 JSON 주석처리 방법을 참고하세요.

# 데이터베이스 연결 설정
database:
  host: localhost  # 운영 환경에서는 도메인으로 변경할 것
  port: 5432

여러 줄 주석 처리

YAML에는 /* ... */와 같은 블록 주석 문법이 별도로 없습니다. 여러 줄에 걸쳐 주석을 작성할 때는 각 줄마다 #를 붙여야 합니다.

# 이 블록은 기본 데이터베이스 연결을 설정합니다.
# 레플리카 인스턴스를 지정하면 쓰기 작업이 실패하므로 주의하세요.
database:
  host: db-primary.example.com

VS Code, IntelliJ, Vim 등의 주요 에디터에서는 영역을 지정한 뒤 주석 토글 단축키(Cmd + / 또는 Ctrl + /)를 누르면 여러 줄에 한 번에 #를 추가하거나 제거할 수 있습니다.

주석 처리를 통한 설정 임시 비활성화

#는 줄 중간이나 시작 부분 어디에나 쓸 수 있어, 설정을 삭제하지 않고 임시로 비활성화해 둘 때 유용합니다.

timeout: 30
# timeout: 60   # 이전 설정값 (참고용으로 보관)

# 기호가 주석으로 인식되려면 기호 앞에 공백이 있거나 줄의 맨 앞이어야 합니다. 공백 없이 key: a#b처럼 작성하면 #도 문자열 값의 일부로 취급됩니다.

여러 줄 문자열 (Multi-line Strings)

긴 문장이나 스크립트를 작성할 때 YAML은 두 가지 블록 텍스트 표기법을 제공합니다.

1. 리터럴 블록 (`|`): 줄바꿈 유지

파이프(|) 기호를 사용하면 본문의 줄바꿈이 그대로 보존됩니다.

description: |
  첫 번째 줄입니다.
  두 번째 줄입니다.
  작성한 줄바꿈이 그대로 유지됩니다.

2. 폴디드 블록 (`>`): 줄바꿈을 공백으로 결합

꺾쇠(>) 기호를 사용하면 연속된 줄바꿈이 하나의 공백으로 합쳐져 긴 한 줄의 문장으로 변환됩니다.

description: >
  이 문장은 에디터에서
  가독성을 위해 여러 줄로 나누었지만,
  실제로는 한 줄의 긴 문자열로 처리됩니다.

데이터 타입과 암묵적 형변환

YAML 파서는 값의 형태를 보고 데이터 타입을 자동으로 유추합니다.

문자열(String): 따옴표 없이 작성하거나 큰따옴표/작은따옴표로 감쌉니다.
정수/실수(Number): 42, 3.14, 0xFF(16진수) 등 숫자는 숫자로 파싱됩니다.
불리언(Boolean): true, false 외에도 YAML 1.1 사양 파서에서는 yes, no, on, off도 불리언으로 자동 변환될 수 있습니다.
널(Null): null, ~, 또는 콜론 뒤를 비워 두면 null 값으로 처리됩니다.

integer_val: 100
float_val: 3.14
boolean_val: true
null_val: ~
empty_val:

앵커와 별칭 (값 재사용)

YAML은 설정의 중복을 줄이기 위해 앵커(Anchor, &)와 별칭(Alias, *), 그리고 병합 키(<<)를 지원합니다.

# 공통 기본 설정 정의 (앵커)
default_config: &default_settings
  timeout: 30
  retries: 3

# 운영 환경 설정에서 기본값 상속 및 재정의
production:
  <<: *default_settings
  timeout: 60

# 개발 환경 설정
development:
  <<: *default_settings
  debug: true

<<: *default_settings를 통해 공통 설정을 그대로 가져오고, 필요한 키만 개별적으로 덮어쓸 수 있어 대규모 설정 파일 관리에 매우 편리합니다. 앵커, 멀티 다큐먼트 등 세부 문법의 체계적인 작성법은 YAML 문법 가이드를 참고하세요.

YAML이 자주 쓰이는 실무 영역

1. Kubernetes 매니페스트

Kubernetes의 Pod, Deployment, Service, ConfigMap 등 모든 리소스 정의는 YAML이 표준입니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

2. GitHub Actions 워크플로

CI/CD 파이프라인을 정의하는 .github/workflows/*.yml 파일은 모두 YAML로 작성됩니다. 들여쓰기 기반 구조 덕분에 Job과 Step의 계층 관계를 직관적으로 파악할 수 있습니다.

name: CI Pipeline
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 의존성 설치 및 테스트 실행
        run: |
          npm install
          npm test

3. Docker Compose

여러 컨테이너 서비스를 한 번에 구성하고 실행하는 docker-compose.yml 역시 YAML 형식을 채택하고 있습니다.

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: mysecretpassword

4. 기타 개발 도구

Spring Boot: application.yml을 통한 계층적 환경 설정
Ansible: 인프라 자동화 플레이북 정의
OpenAPI / Swagger: REST API 스펙 정의 문서
정적 사이트 생성기(SSG): Jekyll, Hugo, Astro 등의 마크다운 Frontmatter 메타데이터. Frontmatter 변환 방법은 마크다운 Frontmatter YAML을 JSON으로 변환하기를 참고하세요.

YAML 작성 시 자주 빠지는 함정과 주의점

1. 탭(Tab) 사용으로 인한 구문 오류

YAML 파일에서 가장 흔하게 발생하는 오류입니다. 에디터에서 탭 문자를 입력하면 파서가 이를 인식하지 못하고 즉시 오류를 발생시킵니다. 에디터 설정에서 "Tab 키 입력 시 공백 삽입(Insert Spaces)"을 활성화하세요.

2. 노르웨이 문제 (Norway Problem) — `country: NO`

YAML 1.1 사양을 사용하는 파서(예: Python의 PyYAML 등)는 따옴표 없는 NO, no, YES, yes, ON, off를 문자열이 아닌 불리언 값(false/true)으로 자동 변환합니다.

노르웨이의 국가 코드 NO가 시스템에서 false로 바뀌는 문제가 대표적입니다. 문자열로 안전하게 처리하려면 반드시 따옴표로 감싸야 합니다.

# 잘못된 작성 (false로 해석될 위험)
country: NO

# 올바른 작성 (문자열로 안전하게 유지)
country: "NO"

3. 콜론 뒤 공백 누락

key:value처럼 콜론 뒤에 공백이 없으면 단일 문자열로 취급되어 키-값 매핑으로 인식되지 않습니다. 항상 key: value 형태로 작성해야 합니다.

4. 들여쓰기 깊이 불일치

같은 블록 안에서 2칸과 4칸 들여쓰기를 혼용하거나, 1칸만 잘못 들여쓰면 파서가 엉뚱한 부모-자식 관계로 해석하거나 구문 오류를 발생시킵니다.

YAML과 JSON 상호 변환

YAML과 JSON은 거의 동일한 데이터 모델을 공유하므로 자유롭게 상호 변환할 수 있습니다. 두 형식의 구조적 차이점과 상세 비교는 YAML과 JSON의 차이점에서 확인할 수 있습니다.

YAML → JSON: YAML로 작성된 사람이 읽기 편한 설정을 프로그램이나 API가 요구하는 엄격한 JSON 형식으로 바꿀 때 사용합니다.
JSON → YAML: API 응답 데이터나 기존 JSON 설정을 가독성 높은 YAML 문서나 Kubernetes 매니페스트로 변환할 때 사용합니다.

브라우저에서 간편하게 변환하고 구문 검사를 수행할 수 있습니다.

YAML to JSON 변환기 — YAML 텍스트를 붙여넣으면 유효성을 실시간으로 검사하고 JSON으로 즉시 변환합니다. 오류 발생 시 문제의 줄 번호와 원인을 표시합니다. 구체적인 변환 규칙과 주의점은 YAML JSON 변환 가이드를 참고하세요.
JSON to YAML 변환기 — 복잡한 JSON 구조를 읽기 쉬운 YAML 구조로 변환합니다. 역방향 변환 규칙의 세부 사항은 JSON YAML 변환 가이드에서 다룹니다.

FormatArc의 YAML to JSON 변환기에서 YAML 문법을 검사하고 JSON으로 변환한 화면

FormatArc의 모든 데이터 변환 작업은 사용자의 웹 브라우저 로컬 환경에서만 실행되며, 서버로 데이터가 전송되지 않아 보안이 중요한 설정 파일도 안전하게 검증할 수 있습니다.

자주 묻는 질문

YAML은 무슨 뜻인가요?

"YAML Ain't Markup Language(YAML은 마크업 언어가 아니다)"의 약자입니다. 초기에는 "Yet Another Markup Language"였으나, 문서 서식이 아닌 순수한 데이터 표현 형식임을 나타내기 위해 재귀적 약어로 명칭이 바뀌었습니다.

YAML은 프로그래밍 언어인가요?

아닙니다. YAML은 조건문이나 반복문, 함수와 같은 로직 제어 구조가 없는 순수 데이터 직렬화 형식입니다. 프로그램 간의 데이터 교환이나 설정 파일 작성에 사용됩니다.

`.yml`과 `.yaml` 확장자에 차이가 있나요?

기능적인 차이는 전혀 없습니다. 모든 YAML 파서는 두 확장자를 동일하게 처리합니다. 공식 사양에서는 .yaml을 권장하지만, 역사적 관례와 편리성 때문에 1글자 짧은 .yml도 매우 널리 쓰입니다.

왜 Kubernetes나 GitHub Actions는 JSON 대신 YAML을 쓰나요?

사람이 직접 눈으로 확인하고 편집하기에 훨씬 직관적이기 때문입니다. 중괄호와 쉼표를 생략할 수 있어 시각적 피로도가 적고, 설정의 이유를 설명하는 주석(#)을 자유롭게 작성할 수 있기 때문입니다.

YAML과 JSON의 주요 차이점은 무엇인가요?

두 형식은 동일한 데이터 구조(스칼라, 배열, 맵)를 표현할 수 있지만 구조 표현 방식이 다릅니다. YAML은 들여쓰기를 사용하며 주석, 여러 줄 문자열, 앵커 기능을 제공합니다. 반면 JSON은 중괄호와 쉼표를 사용하며 문법이 엄격하고 파싱 속도가 빨라 시스템 간 API 통신에 주로 쓰입니다.

`country: NO`가 왜 `false`로 바뀌나요?

과거 YAML 1.1 사양에서 NO, no, YES, yes, ON, off 등을 불리언 값의 별칭으로 정의했기 때문입니다. 이를 피하려면 country: "NO"처럼 큰따옴표로 감싸서 명시적 문자열임을 지정해야 합니다.

정리

YAML은 들여쓰기로 계층 구조를 나타내는 직관적이고 읽기 쉬운 데이터 형식입니다.
주석(#), 여러 줄 텍스트(|, >), 앵커(&) 등 JSON에 없는 편리한 기능을 지원합니다.
Kubernetes, GitHub Actions, Docker Compose 등 현대 DevOps 설정의 표준 형식으로 자리 잡았습니다.
탭 문자 사용 금지, 콜론 뒤 공백 필수, NO와 같은 암묵적 불리언 형변환에 주의해야 합니다.
YAML 작성 및 검증이 필요할 때는 브라우저 기반 YAML to JSON 변환기를 활용해 문법 오류를 쉽고 안전하게 점검할 수 있습니다.

TL;DR — 30초 만에 파악하는 YAML

YAML이란?

YAML 기본 문법과 작성 규칙

키와 값 (Key-Value)

들여쓰기와 계층 구조 (Nesting)

배열 (리스트)

주석 (Comment)

여러 줄 주석 처리

주석 처리를 통한 설정 임시 비활성화

여러 줄 문자열 (Multi-line Strings)

1. 리터럴 블록 (|): 줄바꿈 유지

2. 폴디드 블록 (>): 줄바꿈을 공백으로 결합

데이터 타입과 암묵적 형변환

앵커와 별칭 (값 재사용)

YAML이 자주 쓰이는 실무 영역

1. Kubernetes 매니페스트

2. GitHub Actions 워크플로

3. Docker Compose

4. 기타 개발 도구

YAML 작성 시 자주 빠지는 함정과 주의점

1. 탭(Tab) 사용으로 인한 구문 오류

2. 노르웨이 문제 (Norway Problem) — country: NO

3. 콜론 뒤 공백 누락

4. 들여쓰기 깊이 불일치

YAML과 JSON 상호 변환

자주 묻는 질문

YAML은 무슨 뜻인가요?

YAML은 프로그래밍 언어인가요?

.yml과 .yaml 확장자에 차이가 있나요?

왜 Kubernetes나 GitHub Actions는 JSON 대신 YAML을 쓰나요?

YAML과 JSON의 주요 차이점은 무엇인가요?

country: NO가 왜 false로 바뀌나요?

관련 글

정리

1. 리터럴 블록 (`|`): 줄바꿈 유지

2. 폴디드 블록 (`>`): 줄바꿈을 공백으로 결합

2. 노르웨이 문제 (Norway Problem) — `country: NO`

`.yml`과 `.yaml` 확장자에 차이가 있나요?

`country: NO`가 왜 `false`로 바뀌나요?