YAML

YAML Ain’t Markup Language

階層はタブで表現するかも

階層構造になっているためBNFで表現するには少々苦しいのかやや拡張した形を使っているかもしれない

書式は基本的なところは入門で説明できるが細かいところは仕様を読めな感じであまり親切ではないかもしれないが書きやすい

---

layout: spec

title: YAML Ain't Markup Language (YAML™) リビジョン 1.2.2

---

YAML Ain’t Markup Language (YAML™) バージョン 1.2

リビジョン 1.2.2 (2021年10月1日)

著作権は現在 YAML 言語開発チーム が所有しています

著作権 2001-2009 Oren Ben-Kiki、Clark Evans、Ingy döt Net

この文書は、改変しない限り自由に複製できます。

この文書のステータス

これは YAML 仕様 v1.2.2 です。YAML 1.2 データ言語を定義します。YAML 仕様 v1.2 からの規範的な変更はありません。このリビジョンの主な目的は、エラーを修正し、明確性を高めることです。

以前のYAML仕様は12年前に公開されました。この間、YAMLの人気は著しく高まりました。ユーザーのニーズと期待に応えるため、言語の改良と成長に向けた取り組みが続けられています。今回の仕様改訂ではYAML自体に変更はありませんが、言語の進化と最新性を維持するためのプロセスの始まりとなります。

YAML仕様は、一見シンプルに見えるにもかかわらず、複雑すぎると思われがちです。YAMLはソフトウェアの設定によく使用されますが、これまでも、そしてこれからも、完全なデータシリアル化言語であり続けます。今後のYAMLの計画は、言語とエコシステムをより強力で信頼性の高いものにすると同時に、実装者の開発プロセスを簡素化することに重点を置いています。

今回の仕様改訂は情報の変更のみに限定されていますが、YAMLフレームワークの実装者とYAML言語のユーザーをガイドするための付属ドキュメントが用意されています。このドキュメントは、この仕様の改訂版が公​​開されるたびに、継続的に進化・拡張される可能性があります。

参照:

概要

YAML™（「camel」と韻を踏む）は、人間に優しく、言語横断的なUnicodeベースのデータシリアル化言語であり、動的プログラミング言語の一般的なネイティブデータ型に基づいて設計されています。設定ファイルからインターネットメッセージング、オブジェクトの永続化、データの監査や可視化まで、幅広いプログラミングニーズに活用できます。本仕様は、Unicode文字標準4と併せて、YAMLバージョン1.2を理解し、YAML情報を処理するプログラムを作成するために必要なすべての情報を提供します。

第1章 YAML入門

YAML（「YAML Ain’t Markup Language」の再帰的頭字語）は、人間に優しく、日常的なタスクにおいて最新のプログラミング言語と連携して動作するように設計されたデータシリアル化言語です。この仕様は、YAML言語とそれを支える概念の入門書です。また、YAMLを処理するアプリケーションの開発に必要な情報を網羅した仕様でもあります。

オープンで相互運用性が高く、容易に理解できるツールは、コンピューティングを飛躍的に進歩させました。YAMLは当初から、データを扱う人にとって便利で使いやすいように設計されました。YAMLはUnicodeの印刷可能(5.1章)文字を使用しており、その一部は構造情報を提供し、残りはデータそのものを含んでいます。YAMLは、構造化文字の数を最小限に抑え、データが自然で意味のある方法で表現できるようにすることで、独自の簡潔さを実現しています。例えば、インデントは構造を表すために、コロンはキーと値のペアを区切り、ダッシュは箇条書きを作成するために使用できます。

データ構造(3.1.1章)には様々な種類がありますが、それらはすべて、マッピング（ハッシュ／辞書）、シーケンス（配列／リスト）、スカラー（文字列／数値）という3つの基本プリミティブで適切に表現できます。YAMLはこれらのプリミティブを活用し、シンプルな型付けシステムとエイリアス機構を追加することで、あらゆるネイティブデータ構造をシリアル化するための完全な言語を構成します。ほとんどのプログラミング言語はデータのシリアル化にYAMLを使用できますが、YAMLは3つの基本プリミティブを基盤として構築された言語との連携に優れています。これには、JavaScript、Perl、PHP、Python、Rubyといった一般的な動的言語が含まれます。

プログラミング言語は数百種類ありますが、データの保存と転送に使用できる言語はごくわずかです。YAMLの可能性は事実上無限ですが、設定ファイル、ログファイル、プロセス間メッセージング、言語間データ共有、オブジェクトの永続化、複雑なデータ構造のデバッグといった一般的なユースケースに適した設計となっています。データが見やすく理解しやすいと、プログラミングはよりシンプルな作業になります。

YAML の設計目標は、優先度の高い順に以下のとおりです。

1. YAML は人間が容易に読めるものでなければなりません。

2. YAML データはプログラミング言語間で移植可能である必要があります。

3. YAML は動的言語のネイティブデータ構造と一致している必要があります。

4. YAML は、汎用ツールをサポートするために一貫したモデルを備えている必要があります。

5. YAML はワンパス処理をサポートする必要があります。

6. YAML は表現力に優れ、拡張可能である必要があります。

7. YAML は実装と使用が容易である必要があります。

1.2. YAMLの歴史

YAML 1.2仕様は2009年に公開されました。その主な焦点は、YAMLをJSONの厳密なスーパーセットにすることでした。また、問題のある暗黙的な型付けの推奨事項の多くも削除されました。

1.2仕様のリリース以降、YAMLの採用は拡大を続け、多くの大規模プロジェクトが主要なインターフェース言語として使用しています。2020年には、新しいYAML言語設計チームが定期的に会合を開き、YAML言語と仕様の改善について議論し、ユーザーとユースケースのニーズと期待にさらに応えられるよう努めています。

2021年10月に公開されたこのYAML 1.2.2仕様は、YAMLの刷新された開発の道のりの第一歩です。 YAMLはかつてないほど人気が​​高まっていますが、その潜在能力を最大限に発揮するには、解決すべき課題が山積しています。YAML設計チームは、YAMLを可能な限り優れたものにすることに注力しています。

1.3. 用語

本文書におけるキーワード「MUST（しなければならない）」「MUST NOT（してはならない）」「REQUIRED（必須）」「SHALL（するべき）」「SHALL NOT（しないべき）」「SHOULD（すべき）」「SHOULD NOT（すべきではない）」「RECOMMENDED（推奨）」「MAY（してもよい）」「OPTIONAL（選択できる）」は、RFC 211912 に規定されているとおりに解釈されます。

本文書の残りの部分は、以下のとおり構成されています。第2章では、YAMLの主な機能について簡単に説明します。第3章では、YAML情報モデルと、このモデルとYAMLテキスト形式間の変換プロセスについて説明します。本文書の大部分、第4章、第5章、第6章、第7章、第8章、および第9章では、このテキスト形式を正式に定義します。最後に、第10章では、基本的なYAMLスキーマの推奨を示します。

第2章 言語の概要

このセクションでは、YAMLの表現力について簡単に説明します。初めて読む読者がすべての例を理解する必要はありません。むしろ、これらの例は、仕様の残りの部分を理解するための動機付けとして利用されます。

2.1. コレクション

code:例2.1 スカラーのシーケンス（野球選手）

- Mark McGwire

- Sammy Sosa

- Ken Griffey

code:例2.2 スカラーからスカラーへのマッピング（プレイヤー統計）

hr: 65 # Home runs

avg: 0.278 # Batting average

rbi: 147 # Runs Batted In

code:例2.3 スカラーからシーケンスへのマッピング（各リーグの球団）

american:

- Boston Red Sox

- Detroit Tigers

- New York Yankees

national:

- New York Mets

- Chicago Cubs

- Atlanta Braves

code:例2.4 マッピングのシーケンス（選手の統計）

-

name: Mark McGwire

hr: 65

avg: 0.278

-

name: Sammy Sosa

hr: 63

avg: 0.288

YAMLにはフロースタイルもあり、インデントではなく明示的なインジケータを用いてスコープを示します。フローシーケンスは、角括弧で囲まれたカンマ区切りのリストとして記述されます。同様に、フローマッピングでは中括弧を使用します。

code:例2.5 シーケンスのシーケンス

code:Example 2.6 Mapping of Mappings

Mark McGwire: {hr: 65, avg: 0.278}

Sammy Sosa: {

hr: 63,

avg: 0.288,

}

2.2. 構造

YAMLでは、3つのダッシュ（"---"）を使用してディレクティブとドキュメントの内容を区切ります。これは、ディレクティブが存在しない場合は、ドキュメントの開始を示すためにも使用されます。3つのドット（「...」）は、新しいドキュメントを開始せずにドキュメントの終了を示すもので、コミュニケーションチャネルで使用されます。

code:例2.7 ストリーム内の2つの文書（それぞれ先頭にコメントがある）

# Ranking of 1998 home runs

---

- Mark McGwire

- Sammy Sosa

- Ken Griffey

# Team ranking

---

- Chicago Cubs

- St Louis Cardinals

code:例 2.8 ゲームのプレイバイプレイフィード

---

time: 20:03:20

player: Sammy Sosa

action: strike (miss)

...

---

time: 20:03:47

player: Sammy Sosa

action: grand slam

...

繰り返されるノード (オブジェクト) は、最初にアンカー (アンパサンド「&」でマーク) によって識別され、その後エイリアス (アスタリスク「*」で参照) が付けられます。

code:例2.9 2つのコメントを持つ単一の文書

---

hr: # 1998 hr ranking

- Mark McGwire

- Sammy Sosa

# 1998 rbi ranking

rbi:

- Sammy Sosa

- Ken Griffey

code:例2.10 「サミー・ソーサ」のノードはこの文書に2回出現する

---

hr:

- Mark McGwire

# Following node labeled SS

- &SS Sammy Sosa

rbi:

- *SS # Subsequent occurrence

- Ken Griffey

疑問符とスペース（"? "）は、複雑なマッピングキーを示します。ブロックコレクション内では、キーと値のペアはダッシュ、コロン、または疑問符の直後に開始できます。

code:例2.11 シーケンス間のマッピング

? - Detroit Tigers

- Chicago cubs

: - 2001-07-23

? [ New York Yankees,

Atlanta Braves ]

: [ 2001-07-02, 2001-08-12,

2001-08-14 ]

code:例2.12 コンパクトなネストマッピング

---

# Products purchased

- item : Super Hoop

quantity: 1

- item : Basketball

quantity: 4

- item : Big Shoes

quantity: 1

code:例2.13 リテラルでは改行は保持される

# ASCII Art

--- |

\//||\/||

// || ||__

code:例2.14 折り畳まれたスカラーでは、改行はスペースになる

--- >

Mark McGwire's

year was crippled

by a knee injury.

code:例2.15 折り返された改行は「よりインデントされた」行と空行のために保存される

--- >

Sammy Sosa completed another

fine season with great stats.

63 Home Runs

0.288 Batting Average

What a year!

code:例2.16 インデントによって範囲が決まる

name: Mark McGwire

accomplishment: >

Mark set a major league

home run record in 1998.

stats: |

65 Home Runs

0.278 Batting Average

YAMLのフロースカラーには、プレーンスタイル(plain style)（これまでのほとんどの例）と2つの引用符付きスタイル(two quoted styles)があります。二重引用符付きスタイルはエスケープシーケンスを提供します。一重引用符付きスタイルは、エスケープが不要な場合に便利です。すべてのフロースカラーは複数行にまたがることができ、改行は常に折り返されます。

code:例2.17 引用符付きスカラー

unicode: "Sosa did fine.\u263A"

control: "\b1998\t1999\t2000\n"

hex esc: "\x0d\x0a is \r\n"

single: '"Howdy!" he cried.'

quoted: ' # Not a ''comment''.'

tie-fighter: '|\-*-/|'

code:例2.18 マルチラインフロースカラー

plain:

This unquoted scalar

spans many lines.

quoted: "So does this

quoted scalar.\n"

2.4. タグ

YAMLでは、タグなしノードにはアプリケーションに応じた型が割り当てられます。この仕様の例では、一般的にフェイルセーフスキーマのseq、map、str型を使用しています。また、いくつかの例ではJSONスキーマのint、float、null型も使用しています。

code:例2.19 整数

canonical: 12345

decimal: +12345

octal: 0o14

hexadecimal: 0xC

code:例2.20 浮動小数点

canonical: 1.23015e+3

exponential: 12.3015e+02

fixed: 1230.15

negative infinity: -.inf

not a number: .nan

code:例2.21 その他いろいろ

null:

string: '012345'

code:例2.22 タイムスタンプ

canonical: 2001-12-15T02:59:43.1Z

iso8601: 2001-12-14t21:59:43.10-05:00

spaced: 2001-12-14 21:59:43.10 -5

date: 2002-12-14

明示的な型指定は、感嘆符（「！」）記号を使用したタグで示されます。グローバルタグはURIであり、ハンドルを用いたタグの省略表記で指定できます。アプリケーション固有のローカルタグも使用できます。

code:例2.23 様々な明示的(Explicit)なタグ

---

not-date: !!str 2002-04-28

picture: !!binary |

R0lGODlhDAAMAIQAAP//9/X

17unp5WZmZgAAAOfn515eXv

Pz7Y6OjuDg4J+fn5OTk6enp

56enmleECcgggoBADs=

application specific tag: !something |

The semantics of the tag

above may be different for

different documents.

code:例2.24 Global タグ

%TAG ! tag:clarkevans.com,2002:

--- !shape

# プレゼンテーションを行う際は、! ハンドルを使用してください。

# tag:clarkevans.com,2002:circle

- !circle

center: &ORIGIN {x: 73, y: 129}

radius: 7

- !line

start: *ORIGIN

finish: { x: 89, y: 102 }

- !label

start: *ORIGIN

color: 0xFFEEBB

text: Pretty vector drawing.

code:例2.25 順序なしSet

# Sets are represented as a

# Mapping where each key is

# associated with a null value

# 集合(Set)は、各キーがnull値に関連付けられたマッピングとして表現されます。

--- !!set

? Mark McGwire

? Sammy Sosa

? Ken Griffey

code:例2.26 順序付きマッピング

# Ordered maps are represented as

# A sequence of mappings, with

# each mapping having one key

# 順序付きマップはマッピングのシーケンスとして表現され、各マッピングは1つのキーを持ちます。

--- !!omap

- Mark McGwire: 65

- Sammy Sosa: 63

- Ken Griffey: 58

2.5. 完全な例

以下に、YAMLの完全な例を2つ示します。1つ目は請求書のサンプル、2つ目はログファイルのサンプルです。

code:例2.27 請求書

--- !<tag:clarkevans.com,2002:invoice>

invoice: 34843

date : 2001-01-23

bill-to: &id001

given : Chris

family : Dumars

address:

lines: |

458 Walkman Dr.

city : Royal Oak

state : MI

postal : 48046

ship-to: *id001

product:

- sku : BL394D

quantity : 4

description : Basketball

price : 450.00

- sku : BL4438H

quantity : 1

description : Super Hoop

price : 2392.00

tax : 251.42

total: 4443.52

comments:

Late afternoon is best.

Backup contact is Nancy

Billsmer @ 338-4338.

code:例2.28 ログファイル

---

Time: 2001-11-23 15:01:42 -5

User: ed

Warning:

This is an error message

for the log file

---

Time: 2001-11-23 15:02:31 -5

User: ed

Warning:

A slightly different error

message.

---

Date: 2001-11-23 15:03:17 -5

User: ed

Fatal:

Unknown variable "bar"

Stack:

- file: TopClass.py

line: 23

code: |

x = MoreObject("345\n")

- file: MoreClass.py

line: 58

code: |-

foo = bar

第3章 プロセスとモデル

YAMLは、テキスト形式であると同時に、任意のネイティブデータ構造をその形式で表現するための手法でもあります。したがって、本仕様では2つの概念を定義しています。すなわち、「YAML表現（YAML representations）」と呼ばれるデータオブジェクトのクラスと、YAML表現を一連の文字として表現するための構文である「YAMLストリーム（YAML stream）」です。

YAMLプロセッサとは、これら相互に補完し合う表現形式の間で情報を変換するためのツールです。YAMLプロセッサは、「アプリケーション」と呼ばれる別のモジュールのために処理を行うものと想定されています。本章では、YAMLプロセッサがアプリケーションに対して提供、あるいはアプリケーションから取得しなければならない情報構造について説明します。

YAML情報は、機械による処理と人間による利用という2つの用途で使用されます。これら2つの視点を両立させるための課題は、表現（representation）、シリアライズ（serialization）、プレゼンテーション（presentation）という3つの明確な変換段階を経ることで最適に解決されます。「表現」は、プログラミング環境間での移植性を実現するために、YAMLがネイティブデータ構造をどのように捉えるかを扱います。「シリアライズ」は、YAML表現をシリアル形式（すなわち、シーケンシャルアクセス制約を伴う形式）に変換することを扱います。「プレゼンテーション」は、YAMLシリアライズ結果を、人間にとって読みやすい一連の文字として整形することを扱います。

3.1. プロセス

ネイティブデータ構造と文字ストリームとの間の変換は、論理的に区別されるいくつかの段階を経て行われます。以下の図に示すように、各段階には明確に定義された入出力データモデルが存在します。

図3.1. 処理の概要

(略)

YAMLプロセッサは、必ずしもシリアライズや表現（リプレゼンテーション）の段階を外部に公開する必要はありません。ネイティブデータ構造と文字ストリームとの間で直接変換を行うことも可能です（上の図における「ダンプ」と「ロード」）。ただし、そのような直接変換を行う場合でも、ネイティブデータ構造の構築は、表現（リプレゼンテーション）内で利用可能な情報のみに基づいて行われる必要があります。特に、構築の過程でマッピングのキーの順序、コメント、タグハンドルなどを参照してはなりません。

3.1.1. ダンプ

ネイティブデータ構造を文字ストリームにダンプする処理は、以下の3つの段階を経て行われます。

ネイティブデータ構造の表現

YAMLでは、あらゆるネイティブデータ構造を3種類のノードを用いて表現します。すなわち、要素の順序付き列である「シーケンス（sequence）」、一意なキーと値の順序を持​​たない関連付けである「マッピング（mapping）」、そしてUnicode文字の列として表現可能な（内部構造が不透明な）データである「スカラー（scalar）」です。

これらのプリミティブを組み合わせることで、有向グラフ構造が生成されます。これらのプリミティブが採用されたのは、強力かつ馴染み深いものだからです。シーケンス(sequence)はPerlの配列やPythonのリストに、マッピングはPerlのハッシュテーブルやPythonの辞書(dictionary)に対応しています。スカラー(scalar)は、文字列、整数、日付、その他のアトミックなデータ型を表します。

各YAMLノードには、その種類（kind）や内容に加え、データ型を指定するタグが必要です。型指定子には、グローバルなURIを用いる場合と、単一のアプリケーション内でのみ有効なローカルなものを用いる場合があります。例えば、整数は、スカラーとグローバルタグ「tag:yaml.org,2002:int」を組み合わせることでYAMLにおいて表現されます。同様に、特定の組織に固有の請求書（invoice）オブジェクトは、マッピングとローカルタグ「!invoice」を組み合わせることで表現できます。この単純なモデルにより、プログラミング言語に依存することなく、あらゆるデータ構造を表現することが可能になります。

表現グラフのシリアライズ

イベントコールバックAPIのような逐次アクセス型の媒体においては、YAMLの表現を順序付きのツリー構造へとシリアライズする必要があります。YAMLの表現において、マッピングのキーは順序を持たず、ノードは複数回参照される（複数の「矢印」が向かう）可能性があるため、シリアライズの過程では、マッピングのキーに順序を割り当て、特定のノードへの2回目以降の参照を「エイリアス（alias）」と呼ばれるプレースホルダーに置き換える処理が求められます。YAML仕様では、これらのシリアライズの詳細をどのように決定するかについては規定していません。人間にとって分かりやすいキーの順序やアンカー名を決定することはYAMLプロセッサの役割であり、その際、アプリケーションの支援を受けることも可能です。このプロセスの結果として生成されるYAMLシリアライゼーションツリーを走査することで、YAMLデータをワンパスで処理するための一連のイベント呼び出しを生成できます。

シリアライゼーションツリーの表現

最終的な出力プロセスは、YAMLシリアライゼーションを人間にとって読みやすい形式の文字ストリームとして表現することです。人間による可読性を最大限に高めるため、YAMLは単なるデータ保存という最小限の機能的要件をはるかに超える、豊富なスタイル設定の選択肢を提供しています。そのため、YAMLプロセッサはストリームを生成する際、ノードスタイルの選択、スカラー内容の書式設定、インデント量、使用するタグハンドル、明示しないノードタグ、指定するディレクティブのセット、さらには追加するコメントの選択など、表現に関する様々な詳細を決定する必要があります。こうした処理の一部はアプリケーションの支援を受けて行われることもありますが、一般的には、ユーザーの好みに基づいて進められるべきプロセスです。

3.1.2. ロード (Load)

文字ストリームからネイティブデータ構造をロードする処理は、以下の3つの段階で行われます。

プレゼンテーションストリームの解析 (Parsing the Presentation Stream)

解析（パース）はプレゼンテーションの逆のプロセスであり、文字ストリームを受け取ってシリアライゼーションツリーを生成します。解析では、プレゼンテーションの過程で導入された詳細情報はすべて破棄され、シリアライゼーションツリーのみが出力されます。入力が不正な形式である場合、解析は失敗することがあります。

表現グラフの構築 (Composing the Representation Graph)

構築（コンポジション）は、シリアライゼーションツリーを受け取って表現グラフを生成します。構築では、シリアライゼーションの過程で導入された詳細情報はすべて破棄され、表現グラフのみが出力されます。構築は、後述するいくつかの理由により失敗することがあります。

ネイティブデータ構造の生成 (Constructing Native Data Structures)

最後の入力プロセスは、YAML表現からネイティブデータ構造を生成することです。生成は、表現に含まれる情報のみに基づいて行う必要があり、コメント、ディレクティブ、マッピングのキー順序、ノードスタイル、スカラー内容の形式、インデントレベルといった、シリアライゼーションやプレゼンテーションに関する追加情報に依存してはなりません。必要なネイティブデータ型が利用できない場合、生成は失敗することがあります。

この節では、上記のプロセスの結果に関する詳細を規定します。プログラミング言語や実装間でのデータ移植性を最大化するために、YAMLの利用者は、シリアライゼーションやプレゼンテーションの特性と、YAML表現の一部である特性との違いを意識する必要があります。例えば、YAML表現をシーケンシャルアクセス可能な媒体にフラット化（直列化）する際にはマッピングのキー順序を定める必要がありますが、このシリアライゼーション上の詳細は、アプリケーションレベルの情報を伝達するために使用してはなりません。同様に、人間にとっての読みやすさを確保するためにインデント技法やノードスタイルの選択が必要となりますが、これらのプレゼンテーション上の詳細は、YAMLのシリアライゼーションの一部でも、YAML表現の一部でもありません。シリアライゼーションやプレゼンテーションに必要な特性を慎重に分離することで、アプリケーション情報のYAML表現は一貫性を保ち、様々なプログラミング環境間で移植可能となります。

以下の図は、これら3つの情報モデルをまとめたものです。実線の矢印はコンポジション（構成）を、白抜きの矢印は継承を表し、「1」と「*」は「1対1」および「1対多」の関係を表します。単一の「+」はシリアライゼーションの詳細を、二重の「++」はプレゼンテーションの詳細を表します。

図3.2 情報モデル

(略)

3.2.1. 表現グラフ

YAMLにおけるネイティブデータ構造の表現は、タグ付きノードから構成される、根（ルート）を持つ連結有向グラフです。ここで「有向グラフ」とは、ノードと有向エッジ（「矢印」）の集合を指し、各エッジはあるノードを別のノードへと結びつけます（有向グラフの正式な定義13を参照）。すべてのノードは、そのようなエッジをたどって根ノードから到達可能でなければなりません。なお、YAMLのグラフには閉路（サイクル）が含まれる場合があり、一つのノードに複数の入力エッジが接続されることもあります。

他のノードとの関係に基づいて定義されるノードは「コレクション」であり、他のノードから独立したノードは「スカラー」です。YAMLは、シーケンスとマッピングという2種類のコレクションノードをサポートしています。マッピングノードは少々扱いが複雑です。なぜなら、そのキーは順序を持たず、かつ一意（ユニーク）でなければならないからです。

図3.3 表現モデル

(略)