2. Defining New Structured Fields (新しい構造化フィールドの定義)
HTTPフィールドを構造化フィールドとして指定するには、その作成者は以下を行う必要があります:
必須ステップ
1. 本仕様を規範的に参照
フィールドの受信者と生成者は、本文書の要件が有効であることを知る必要があります。
参照文の例:
"このフィールドは構造化フィールド [RFC8941] です。"
2. フィールドタイプの識別
フィールドが以下のいずれであるかを特定:
- 構造化ヘッダー (Structured Header): ヘッダーセクションでのみ使用可能（一般的なケース）
- 構造化トレイラー (Structured Trailer): トレイラーセクションでのみ使用可能
- 構造化フィールド (Structured Field): どちらでも使用可能
3. トップレベルデータ型の指定
以下のタイプのいずれかを選択:
- List (リスト) - セクション3.1
- Dictionary (辞書) - セクション3.2
- Item (項目) - セクション3.3
4. フィールド値のセマンティクスの定義
フィールドの意味と目的を説明します。
5. 追加の制約の指定
フィールド値の制約条件と、これらの制約に違反した場合の結果を定義します。
定義パターン
通常、フィールド定義はトップレベルタイプ（List、Dictionary、またはItem）を指定し、その許可されるタイプと制約を定義します。
制約の例
List型フィールド:
- すべてのメンバーがInteger
- または混合型
Item型フィールド:
- Stringのみ許可
- かつ文字"Q"で始まる文字列のみ許可
- または小文字の文字列のみ許可
特に注意: 内部リスト (Inner Lists, セクション3.1.1) は、フィールド定義が明示的に許可している場合にのみ有効です。
エラー処理
パースが失敗した場合、フィールド全体が無視されます（セクション4.2参照）。ほとんどの場合、フィールド固有の制約違反も同じ効果を生成すべきです。
デフォルトの動作
シナリオ: フィールドがItemと定義されIntegerでなければならないが、Stringを受信
デフォルトの動作: フィールドを無視
異なるエラー処理が必要な場合は、明示的に指定する必要があります。
拡張性
Parameters (パラメータ) - 拡張メカニズム
ItemとInner Listは両方とも、拡張メカニズムとしてパラメータを許可します。これは、将来的により多くの情報を収容するために値を拡張できることを意味します。
将来互換性を維持するため: フィールド仕様は、認識されないパラメータの存在をエラー条件として定義することは推奨されません (discouraged)。
"Grease" Parameters (グリースパラメータ)
将来の拡張性をさらに確保し、コンシューマーが完全なパーサー実装を使用することを奨励するために、フィールド定義は送信者が"grease"パラメータを追加することを指定できます。
例の戦略:
---------
仕様は、定義されたパターンに一致するすべてのパラメータをこの目的のために
予約することを規定し、リクエストの一部でそれらの送信を奨励できます。
目的:
----
これにより、受信者がパラメータを考慮しないパーサーを
書くことを抑止できます。
Dictionaryの将来互換性
Dictionaryを使用する仕様は、未知のメンバーの存在とそれに関連する値とタイプを無視することを要求することで、将来互換性を実現することもできます。後続の仕様は他のメンバーを追加し、それらに対する制約を適切に指定できます。
その後、構造化フィールドの拡張は、その拡張を理解する受信者が定義された値が制約を満たさないことを発見した場合、フィールド値全体を無視することを要求できます。
制約ルール
要件を緩和できない
フィールド定義は本仕様の要件を緩和することはできません (cannot)。なぜなら、そうすることは汎用ソフトウェアによる処理を妨げるからです。追加の制約のみを追加できます。
追加できる制約の例:
- IntegerとDecimalの数値範囲
- StringとTokenの形式
- Dictionary値で許可されるタイプ
- List内のItemの数
フィールド全体に適用
フィールド定義は、フィールド値の一部ではなく、全体にのみ本仕様を使用できます。
実装制限
最小値
本仕様は、実装がサポートする必要がある様々な構造の長さまたは数の最小値を定義しています。
最大値
ほとんどの場合、最大サイズは指定されていませんが、作成者はHTTP実装が以下について様々な制限を課すことに注意する必要があります:
- 単一フィールドのサイズ
- フィールドの総数
- ヘッダーまたはトレイラーセクション全体のサイズ
命名規則
仕様は、フィールド名を次のように呼ぶことができます:
- "構造化ヘッダー名 (structured header name)"
- "構造化トレイラー名 (structured trailer name)"
- "構造化フィールド名 (structured field name)"
フィールド値は次のように呼ぶことができます:
- "構造化ヘッダー値 (structured header value)"
- "構造化トレイラー値 (structured trailer value)"
- "構造化フィールド値 (structured field value)"
ABNFの使用
フィールド定義は、本仕様で"sf-"で始まるABNFルールを使用することが奨励されます (encouraged)。本仕様の他のルールは、フィールド定義での使用を意図していません。
完全な例: Foo-Exampleヘッダー
42. Foo-Example Header
Foo-Example HTTPヘッダーフィールドは、メッセージにどれだけのFooが
あるかについての情報を伝達します。
Foo-Exampleは項目構造化ヘッダー [RFC8941] です。その値は
Integer (セクション3.3.1 of [RFC8941]) でなければなりません。
そのABNFは以下のとおりです:
Foo-Example = sf-integer
その値はメッセージ内のFooの量を示し、0から10の範囲内（両端を含む）
でなければなりません。他の値はヘッダーフィールド全体を無視させなければ
なりません。
以下のパラメータが定義されています:
* キーが"foourl"で、値がString (セクション3.3.3 of [RFC8941]) である
パラメータで、メッセージのFoo URLを伝達します。処理要件については
下記を参照してください。
"foourl"にはURI-reference (セクション4.1 of [RFC3986]) が含まれます。
その値が有効なURI-referenceでない場合、ヘッダーフィールド全体を
無視しなければなりません。その値が相対参照 (セクション4.2 of [RFC3986])
の場合、使用する前に解決 (セクション5 of [RFC3986]) しなければなりません。
例:
Foo-Example: 2; foourl="https://foo.example.com/"
例の分析
Foo-Example: 2; foourl="https://foo.example.com/"
パース:
- タイプ: Item (Integer)
- 値:
2 - パラメータ:
foourl="https://foo.example.com/"
検証:
- 値はInteger ✓
- 値は0-10の範囲内 ✓
- foourlパラメータが存在 ✓
- foourlは有効なURI ✓
値が15の場合:
Foo-Example: 15; foourl="https://foo.example.com/"
結果: フィールド全体が無視される（0-10範囲制約違反）
定義チェックリスト (Checklist)
新しい構造化フィールドを定義する際、以下を確認してください:
- RFC 8941を規範的に参照
- フィールドがHeader/Trailer/Fieldであることを明確化
- トップレベルタイプ (List/Dictionary/Item) を指定
- フィールドのセマンティクスを定義
- タイプ制約を指定
- 値範囲制約を定義（該当する場合）
- パラメータを説明（存在する場合）
- エラー処理を定義（デフォルトと異なる場合）
- 将来互換性を考慮
- 例を提供
重要なポイント (Key Takeaways)
- 5つの必須ステップ: 参照、タイプ、データ型、セマンティクス、制約
- 厳格なデフォルト: パース失敗 = フィールド無視
- 拡張性優先: パラメータの使用と未知のメンバーの無視を奨励
- 制約のみ追加可能: RFC 8941の要件を緩和できない
- 完全なフィールド: 仕様はフィールド値全体に適用
- 実装制限: HTTP実装のサイズ制限に注意