1.1. 表記規約

この文書におけるキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", および "OPTIONAL" は、 ここに示すようにすべて大文字で出現する場合に限り、 BCP 14 [RFC2119] [RFC8174] に記述されているとおりに解釈されるものとする。¶

この文書における "content negotiation" および "resource" という用語は、[HTTP] における意味で解釈されるものとする。¶

この文書における "fragment" および "fragment identifier" という用語は、 [URI] における意味で解釈されるものとする。¶

この文書における "presentation", "stream", "YAML document", "representation graph", "tag", "serialization detail", "node", "alias node", "anchor", および "anchor name" という用語は、 [YAML] における意味で 解釈されるものとする。¶

YAML コードを含む図は、可読性を向上させるため、常に %YAML ディレクティブで開始する。¶

1.2. フラグメント 識別

フラグメントは、ストリーム内のノードを識別する。¶

"*" で始まるフラグメント識別子は、 YAML エイリアスノードとして解釈されるものとする（Section 1.2.1 を参照）。¶

単一文書の YAML ストリームでは、空であるか "/" で始まる フラグメント識別子は JSON Pointer [JSON-POINTER] として解釈され、 エイリアスノードをたどりながら YAML 表現グラフ上で評価される。特に、空のフラグメント識別子はルートノードを参照する。 この構文は、JSON データモデルと相互運用可能なノードから構成されるパス上にある YAML ノードのみを参照できる（Section 3.4 を参照）。¶

フラグメント識別子が既存のノードを参照することは保証されない。 したがって、アプリケーションは、解決されないエイリアスノードをどのように扱うべきかを 定義するSHOULD。¶

 %YAML 1.2
 ---
 one: &foo scalar
 two: &bar
   - some
   - sequence
   - items
 ...
 %YAML 1.2
 ---
 &document_2
 one: &foo [a, sequence]

2.1. メディア型 application/yaml

YAML のメディア型は application/yaml である。 以下の情報は、このメディア型の登録フォームとして機能する。¶

型名:

application¶

サブタイプ名:

yaml¶

必須パラメーター:

N/A¶

任意パラメーター:

N/A。認識されないパラメーターは無視されるべきである。¶

エンコーディングに関する考慮事項:

binary¶

セキュリティに関する考慮事項:

この文書の Section 4 を参照。¶

相互運用性に関する考慮事項:

この文書の Section 3 を参照。¶

公開された仕様:

[YAML]、この 文書¶

このメディア型を使用するアプリケーション:

動的プログラミング言語の一般的なデータ型を中心に設計された、 人間に親しみやすく、言語横断的で、Unicode ベースのデータシリアライズ言語を必要とする アプリケーション。¶

フラグメント識別子に関する考慮事項:

この文書の Section 1.2 を参照。¶

追加情報:

この型の非推奨の別名:

application/x-yaml, text/yaml, および text/x-yaml。これらの 名前は使用されているが、登録されていない。¶

マジックナンバー:

N/A¶

ファイル拡張子:

"yaml"（推奨）および "yml"。 この文書の Section 3.3 を参照。¶

Macintosh ファイル型コード:

N/A¶

Windows クリップボード名:

YAML¶

詳細情報の連絡先となる人物および電子メールアドレス:

この文書の著者の連絡先の節を参照。¶

想定される用途:

COMMON¶

使用上の制限:

なし¶

著者:

この文書の著者の連絡先の節を参照。¶

変更管理者:

IETF¶

2.2. +yaml 構造化構文サフィックス

サフィックス +yaml は、その表現が application/yaml に対して確立されたものに従う任意のメディア型で 使用されてもよいMAY。 構造化構文サフィックスの登録フォームを以下に示す。 登録フォームの各部分の定義については [MEDIATYPE] を参照。¶

名称:

YAML Ain't Markup Language (YAML)¶

+サフィックス:

+yaml¶

参考文献:

[YAML]、この 文書¶

エンコーディングに関する考慮事項:

application/yaml と同じ¶

相互運用性に関する考慮事項:

application/yaml と同じ¶

フラグメント識別子に関する考慮事項:

application/yaml とは異なり、 +yaml についてはフラグメント識別構文は定義されていない。¶

特定の xxx/yyy+yaml メディア型は、 フラグメント識別子の構文および意味論を定義する必要がある。 なぜなら、application/yaml のために定義されたものは、 明示的に表明されない限り適用されないからである。¶

セキュリティに関する考慮事項:

application/yaml と同じ¶

連絡先:

httpapi@ietf.org または art@ietf.org¶

著者:

この文書の著者の連絡先の節を参照。¶

変更管理者:

IETF¶

3.1. YAML は進化する 言語である

YAML は進化する言語であり、時間の経過とともに、 追加された機能もあれば削除された機能もある。¶

application/yaml メディア型登録は、 YAML のバージョンから独立している。 これにより、バージョン非依存の YAML リソースのコンテンツネゴシエーションが可能になる。¶

特定の YAML バージョンに関連する機能を重視する実装者は、 %YAML ディレクティブを使用して YAML 文書内でそれを指定できる （[YAML] の Section 6.8.1 を参照）。¶

3.2. YAML ストリーム

YAML ストリームは、0 個以上の YAML 文書を含むことができる。¶

複数文書ストリームを受信する場合、 単一文書ストリームのみを期待するアプリケーションは、 余分な文書を無視するのではなく、エラーを通知するべきである。¶

現在の実装は、ストリーム内の異なる文書を、 JSON テキストシーケンス（[RFC7464] を参照）と同様に独立したものと見なす。 アンカーなどの要素は、異なる文書をまたいで参照可能であるとは保証されない。¶

3.3. ファイル名拡張子

"yaml" ファイル名拡張子が推奨される。 これはウェブ上で最も普及し、広く使用されている。 "yml" ファイル名拡張子も引き続き使用されている。 同じ文脈で 2 つのファイル名拡張子を同時に使用すると、 相互運用性の問題が生じる可能性がある （例: "config.yaml" と "config.yml" の両方が存在する場合）。¶

3.4. YAML と JSON

フローコレクションスタイル（[YAML] の Section 7.4 を参照）を使用する場合、 YAML 文書は JSON [JSON] のように見えることがある。 したがって、同様の相互運用性に関する考慮事項が適用される。¶

JSON として消費されることを意図した情報を より効率的な形式でシリアライズするために YAML を使用する場合、 表現グラフに反映されず、プレゼンテーションまたはシリアライズの詳細として分類される情報 （[YAML] の Section 3.2 を参照）は破棄できる。 これには、コメント（[YAML] の Section 3.2.3.3 を参照）、 ディレクティブ、および JSON に対応物を持たないエイリアスノード （[YAML] の Section 7.1 を参照）が含まれる。¶

 %YAML 1.2
 ---
 # This comment will be lost
 # when serializing in JSON.
 Title:
   type: string
   maxLength: &text_limit 64

 Name:
   type: string
   maxLength: *text_limit  # Replaced by the value 64.

実装者は、処理中に関連情報が失われないことを 確実にする必要がある。 たとえば、エイリアスノードが静的な値で置き換えられることを 許容可能と見なすことがある。¶

場合によっては、実装者は、 許可される YAML 機能の一覧を定義したいことがある。 その際、以下の機能は [JSON] との 相互運用性に問題を持つ可能性があることを考慮に入れる。¶

• 複数文書 YAML ストリーム¶
• 非 UTF-8 エンコーディング。YAML ストリームを UTF-16 または UTF-32 でエンコードする前に、 閉じたエコシステムの一部ではないシステム間で JSON テキストを交換する場合、 Section 8.1 of [JSON] が UTF-8 の使用を義務付けており、 [YAML] の Section 5.2 が UTF-8 の使用を推奨していることに注意することが重要である。¶
• 文字列ではないマッピングキー¶
• アンカーを使用して表現される循環参照（Section 4.2 および Figure 4 を参照）¶
• .inf および .nan 浮動小数点値。JSON はこれらをサポートしないため¶
• 非 JSON 型。 古い YAML バージョンのデフォルトスキーマに含まれていた !!timestamp のようなタグに関連付けられたものを含む¶
• タグ全般、特に JSON 型に対応しないタグ。 例として、!!python/object や !mytag のようなカスタムタグおよびローカルタグ （[YAML] の Section 2.4 を参照）¶

 %YAML 1.2
 ---
 non-json-keys:
   0: a number
   [0, 1]: a sequence
   ? {k: v}
   : a map
 ---
 non-json-keys:
   !date 2020-01-01: a timestamp
 non-json-value: !date 2020-01-01
 ...

3.5. フラグメント識別子

フラグメント識別子がエイリアスノードをたどれるようにするには、 フラグメント識別子の評価の前に YAML 表現グラフを生成する必要がある。この評価が、 無限ループや予期しないコード実行のような、Sections 3.4 および 4 で述べた問題を 引き起こさないことが重要である。¶

実装者は、YAML のバージョンおよびサポートされる機能 （例: マージキー）が表現グラフの生成に影響を与える可能性があることを 考慮する必要がある（Figure 9 を参照）。¶

Section 1.2 において、この文書は JSON データモデルに基づく仕様の利用を、YAML フラグメント識別子のサポートで拡張する。 これは、YAML で OpenAPI 文書 [OAS] を書くような、 すでに定着した慣行の相互運用性を向上させるためである。¶

Appendix A は、 フラグメント識別子に関連する相互運用性の問題を読者が理解する助けとなる、 網羅的ではない例の一覧を提供する。¶

4.1. 任意コード 実行

YAML タグを使用する際には注意が必要である。 その解決が予期しないコード実行を引き起こす可能性があるためである。¶

デシリアライザーにおけるコード実行はデフォルトで無効にされるべきであり、 明示的にのみ有効にされるべきである。 後者の場合、実装は（たとえば特定の関数を介して） コード実行の結果が厳密に制限された時間／メモリ上限内に収まることを保証すべきである。¶

多くの実装は、これらの問題に対処する安全なデシリアライザーを提供している。¶

4.2. リソース枯渇

YAML 文書は根付きの連結有向グラフであり、 参照サイクルを含むことができるため、 単純な木として扱うことはできない（[YAML] の Section 3.2.1 を参照）。 それらを単純な木として扱う実装は、 YAML 表現グラフを走査している間に無限ループに陥る危険がある。 これは次の場合に起こり得る。¶

• それを JSON としてシリアライズしようとするとき、または¶
• JSON データモデルに基づく仕様 （例: [JSON-POINTER]）を使用してノードを 検索／識別するとき。¶

 %YAML 1.2
 ---
 x: &x
   y: *x

表現グラフが循環していない場合でも、それを単純な木として扱うと、 指数的データ展開（例: Billion Laughs Attack）を引き起こすなど、 不適切な挙動につながる可能性がある。¶

 %YAML 1.2
 ---
 x1: &a1 ["a", "a"]
 x2: &a2 [*a1, *a1]
 x3: &a3 [*a2, *a2]

これは、アンカー再帰深度を制限し、 処理前に入力を検証するプロセッサーを使用することで対処できる。 そのような場合でも、使用しようとしている実装を慎重にテストすることが重要である。 参照サイクルをサポートしない形式で YAML 表現グラフをシリアライズする場合にも、 同じ考慮事項が適用される（Section 3.4 を参照）。¶

4.3. YAML ストリーム

YAML ストリームのインクリメンタルな解析および処理は、 部分的な結果を生成し、 後でストリームの残りの解析に失敗したことを示す可能性がある。 部分処理を防ぐため、実装者はストリーム内のすべての文書を 同時に検証および処理することを好む場合がある。¶

YAML ストリームの繰り返しの解析および再エンコードは、 文書区切り（例: --- または ...）の追加または削除、 ならびにアンカー名およびその他のシリアライズ詳細の変更をもたらし、 署名検証を破壊する可能性がある。¶

4.4. ブール値の表現

[YAML] の Section 10.3.2 は、 正規表現 true|True|TRUE|false|False|FALSE に一致するスカラーのみが ブール値として解釈されることを規定している。 古い YAML バージョンはより寛容であった（例: NO および N を False として解釈し、 YES および Y を True として解釈する）。 古い構文が使用されると、YAML 実装は {insecure: n} を {insecure: false} ではなく {insecure: "n"} と解釈する可能性がある。 [YAML] の Section 10.3.2 で定義された構文を使用すると、 これらの問題を防げる。¶

A.1. 参照不能なノード

この例は、マッピングキーが文字列ではないため、 JSON データモデルに基づいて参照できない 2 つの YAML ノードを示している。¶

 %YAML 1.2
 ---
 a-map-cannot:
   ? {be: expressed}
   : with a JSON Pointer

 0: no numeric mapping keys in JSON

A.2. 存在しない ノードの参照

この例では、フラグメント #/0 は既存のノードを参照しない。¶

 %YAML 1.2
 ---
 0: "JSON Pointer `#/0` references a string mapping key."

A.3. アンカーおよび循環参照を伴う 表現グラフ

この YAML 文書では、#/foo/bar/baz フラグメント識別子は 表現グラフをたどり、文字列 you を参照する。 さらに、循環参照が存在することは、 &anchor ノードを参照する #/foo/bat/../bat/bar という無限個のフラグメント識別子が 存在することを意味する。¶

 %YAML 1.2
 ---
 anchor: &anchor
   baz: you
 foo: &foo
   bar: *anchor
   bat: *foo

多くの YAML 実装は、YAML 1.1 で定義された マージキー "<<:" を 表現グラフ内で解決する。 これは、フラグメント #/book/author/given_name が文字列 Federico を参照し、 フラグメント #/book/<< は既存のどのノードも参照しないことを意味する。¶

 %YAML 1.1
 ---
 # Many implementations use merge keys.
 the-viceroys: &the-viceroys
   title: The Viceroys
   author:
     given_name: Federico
     family_name: De Roberto
 book:
   <<: *the-viceroys
   title: The Illusion