YAMLの基本事項について

Last updated at 2025-03-12Posted at 2025-03-12

YAMLについて，なんとなくでしか知らなかったので，適切に理解をする必要があると感じた．
そこで，特にJSONとの違いを理解する必要がある為に以下に纏めた．
主観だが，JSONと比較をして，インデントで構造を作成できる事，コメントアウトが可能な事は，感覚的に非常に利用し易いと感じる．

In a nutshell

YAMLは設定ファイルやデータ構造の記述に適したフォーマットであり，JSONよりも可読性が高い．
バックエンドやDevOps（Kubernetes, Ansible, CI/CDなど）で頻繁に利用される．
ただし，スキーマバリデーションがなく，ネストが深くなると可読性が低下する点には注意が必要．

YAMLの特徴

シンプルで読みやすい
- インデント(スペース)を使って階層を表現する．
- JSONやXMLに比べて直感的に理解しやすい．
キーと値のペア
- key: value の形式でデータを記述する．
リスト(配列)を簡単に記述
- -(ハイフン)を使ってリストを表現．
コメントが書ける
- # を使ってコメントを記述できる．
拡張性が高い
- YAMLファイルは多くのプログラミング言語でサポートされており，設定ファイルやデータのシリアライズに適している．

基本的な書き方

キーと値のペア

name: Yamada Taro
age: 30
email: Yamada@example.com

リスト(配列)

OS:
  - Windows
  - Mac
  - Ubuntu

ネスト

person:
  name: Yamada
  age: 25
  address:
    city: Tokyo
    country: Japan

複数行の文字列

description: |
  This is a multi-line string.
  It preserves line breaks.

message: >
  This is also a multi-line string,
  but it will be collapsed into a single line.

変数の参照

defaults: &default_settings
  theme: dark
  language: en

user1:
  <<: *default_settings
  name: Yamada

user2:
  <<: *default_settings
  name: Sasaki
  language: jp

データ型

# 文字列
string: "Hello, YAML"

# 数値
integer: 42
float: 3.14

# 真偽値
boolean_true: true
boolean_false: false

# null値
null_value: null  # または ~

# 配列(リスト)
list:
  - item1
  - item2
  - item3

# マップ(辞書)
dictionary:
  key1: value1
  key2: value2

環境変数

database:
  user: ${DB_USER}  # 環境変数 DB_USER を参照
  pass: ${DB_PASS}  # 環境変数 DB_PASS を参照

関係が深い事

バックエンド側(Python, Node.js, 等)

YAMLと関係が深い

設定ファイル

PythonやNode.jsのアプリケーションでは，設定をYAMLで管理することが多い．
例: config.yaml に設定情報を記述し，Python (PyYAML) やNode.js (js-yaml) で読み込む．

CI/CDの設定

GitHub Actions (.github/workflows/*.yaml) や GitLab CI (.gitlab-ci.yml) はYAMLで設定を書く．

API定義(OpenAPI)

REST APIの仕様をYAMLで記述し，Python (FastAPI, Flask) やNode.js (Express) で利用する．

データベース

YAMLと関係が深い

データベース設定

database.yaml などに接続情報（DB名，ユーザー，パスワード）を記述し，PythonやNode.jsがそれを読み込む．

database:
  host: localhost
  user: root
  password: secret
  name: mydb

データマイグレーションツール

db-migrate や Liquibase などのツールでYAMLを使うことがある．

フロントエンド側(Javascript, 等)

YAMLとは関係が浅い
フロントエンド側ではあまり利用されない．

設定管理

フロントエンドの設定は通常 .env や JSON，JavaScript ファイルで管理することが多い．
Vue.js では .env や config.js を使う為，YAMLを使うことはほぼない．

データ通信

JSONが主流であり，YAMLで通信することは殆ど無い．

DevOps・インフラ管理

YAMLとは関係が深い
インフラ管理や自動化に広く利用される．

Kubernetes

PodやServiceの設定をYAMLで記述

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: my-app-image

Docker Compose

複数のコンテナ構成を記述するための docker-compose.yml で使用

version: "3.8"
services:
  web:
    image: nginx
    ports:
      - "80:80"

Ansible

サーバー構成管理のプレイブックで利用

- hosts: webservers
  tasks:
    - name: Install Nginx
      apt:
        name: nginx
        state: present

CI/CD

YAMLとは関係が深い
CI/CDパイプラインの設定にYAMLが良く利用される．

GitHub Actions

.github/workflows/*.yaml にワークフローを記述

name: CI/CD Pipeline
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run tests
        run: npm test

GitLab CI/CD

.gitlab-ci.yml にCI/CDの設定を書く

stages:
  - test
  - deploy

test_job:
  stage: test
  script:
    - npm test

API管理・ドキュメント

YAMLとは関係が深い
APIの設計・ドキュメント化で頻繁に使われる

OpenAPI（Swagger）

REST APIの仕様をYAMLで記述してSwagger UIなどで可視化できる

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: Success

YAMLとJSONの違い

項目	YAML	JSON
可読性	高い(直感的)	低い(括弧が多い)
階層表現	インデントで表現	`{}`(中括弧)を使用
コメント	`#` で可能	できない
サポート	設定ファイル，API設定	Web，データ転送

YAMLの活用例

アプリケーションの設定ファイル
- 例: config.yaml
CI/CDツールの設定
- 例: GitHub Actions (.github/workflows/*.yaml)，GitLab CI (.gitlab-ci.yml)
Kubernetesの設定
- 例: deployment.yaml
Ansibleのプレイブック
- 例: playbook.yml

YAMLの注意点

インデントは必ずスペースを使う

タブはNG(エラーの原因になる)

コロンの後にはスペースを入れる

key: value  # OK
key:value   # NG

データ型を明確にする

version: "1.0"  # 文字列(OK)
version: 1.0    # 数値(意図しない型になる場合あり)

boolは`true`or`false`とする

enabled: true  # OK
enabled: yes   # NG(ソフトによってはエラー)

その他の制限や欠点

パースエラーが起こりやすい
上記にもあるが，インデントにタブを使うとエラーとなる為，必ずスペースを使用する必要がある．
スキーマバリデーションがない
JSON等のように厳格なスキーマチェックが無い為，間違ったデータ形式を入力してもを入れても気付きにくい．JSON Schemaなどを利用してバリデーションを行う事も可能．
複雑なデータ構造では可読性が低下する
YAMLは人が読みやすい形式として規定されているが，ネストが深くなると可読性が低下する．

Summary

YAMLは設定ファイルやデータ管理に適したフォーマットで，JSONよりも可読性が高い．
バックエンド（Python, Node.js）や DevOps（Kubernetes, Ansible）で広く使われる．
CI/CD（GitHub Actions, GitLab CI）や API仕様（OpenAPI）でも重要な役割を持つ．
スキーマバリデーションがないため，誤ったデータを記述しても気づきにくい．
ネストが深くなると可読性が低下し，複雑なデータ構造には向かない．
Web APIのデータ通信ではJSONが主流だが，API仕様の管理にはYAMLが適している．

参考文献

YAML公式ドキュメント. YAML Ain’t Markup Language (YAML™) Version 1.2 Specification. YAML.org.
https://yaml.org/spec/
JSON公式ドキュメント. Introducing JSON. JSON.org.
https://www.json.org/json-en.html
PyYAMLドキュメント. PyYAML Documentation. PyYAML.
https://pyyaml.org/wiki/PyYAMLDocumentation
js-yamlリポジトリ. js-yaml: YAML 1.2 parser and serializer for JavaScript. Nodeca.
https://github.com/nodeca/js-yaml
Kubernetes公式ドキュメント. Configuration Overview. Kubernetes.io.
https://kubernetes.io/docs/concepts/configuration/overview/
Docker公式ドキュメント. Compose file reference. Docker Docs.
https://docs.docker.com/reference/compose-file/
Ansible公式ドキュメント. Playbooks: Ansible User Guide. Ansible Docs.
https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html
GitHub Actions公式ドキュメント. Understanding GitHub Actions. GitHub Docs.
https://docs.github.com/en/actions
GitLab CI/CD公式ドキュメント. CI/CD YAML Configuration Reference. GitLab Docs.
https://docs.gitlab.com/ee/ci/yaml/
OpenAPI (Swagger)公式ドキュメント. OpenAPI 3.0 Specification Basics. Swagger.io.
https://swagger.io/docs/specification/v3_0/basic-structure/

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up