メインコンテンツまでスキップ

3. Structured Data Types (構造化データ型)

本セクションでは、構造化フィールドの抽象型を定義します。提供されるABNFは、HTTPフィールド値のワイヤー形式を表します。

概要​

  • HTTPフィールドの定義に使用できる3つのトップレベル型があります: Lists (リスト)、Dictionaries (辞書)、Items (項目)

  • ListsとDictionariesはコンテナです。そのメンバーはItemsまたはInner Lists（Inner Lists自体はItemsの配列）になれます

  • ItemsとInner Listsの両方は、キーと値のペアでパラメータ化 (Parameterized) できます

3.1 Lists (リスト)​

Listsは、ゼロ個以上のメンバーを含む配列で、各メンバーはItem（セクション3.3）またはInner List（セクション3.1.1）になることができ、両方ともパラメータ化できます（セクション3.1.2）。

ABNF構文​

sf-list       = list-member *( OWS "," OWS list-member )
list-member   = sf-item / inner-list

形式の説明​

各メンバーはカンマとオプションの空白で区切られます。

例​

Example-List: sugar, tea, rum

Tokenリストとして定義されたフィールド

空リスト​

空のListは、フィールドをまったくシリアライズしないことで表現されます。これは、Listsとして定義されたフィールドがデフォルトで空の値を持つことを意味します。

複数行分割​

Listsのメンバーは、同じヘッダーまたはトレイラーセクション内の複数行に分割できます（[RFC7230]セクション3.2.2による）。例えば、以下は等価です:

Example-List: sugar, tea, rum

次と等価:

Example-List: sugar, tea
Example-List: rum

注意: Listの個別メンバーは行間で安全に分割できません。詳細はセクション4.2を参照してください。

実装要件​

パーサーは、少なくとも1024個のメンバーを含むListsをサポートしなければなりません (MUST)。フィールド仕様は、必要に応じて個々のList値の型と基数を制約できます。

3.1.1 Inner Lists (内部リスト)​

Inner Listは、ゼロ個以上のItems（セクション3.3）を含む配列です。個々のItemsとInner List自体の両方がパラメータ化できます（セクション3.1.2）。

ABNF構文​

inner-list    = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")"
                parameters

形式の説明​

Inner Listsは括弧で囲まれ、その値は1つ以上のスペースで区切られます。

例1: 単純なInner Lists​

Example-List: ("foo" "bar"), ("baz"), ("bat" "one"), ()

Stringsの内部リストのリストとして定義されたフィールド。最後のメンバーは空のInner Listであることに注意してください。

例2: パラメータ付きInner Lists​

Example-List: ("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1

パラメータ付き内部リスト（2つのレベルでパラメータを持つ）のリストとして定義されたフィールド。

実装要件​

パーサーは、少なくとも256個のメンバーを含むInner Listsをサポートしなければなりません (MUST)。フィールド仕様は、必要に応じて個々のInner Listメンバーの型と基数を制約できます。

3.1.2 Parameters (パラメータ)​

Parametersは、Item（セクション3.3）またはInner List（セクション3.1.1）に関連付けられたキーと値のペアの順序付きマッピングです。キーはそれらが出現するParametersのスコープ内で一意であり、値は裸の項目 (bare items)（つまり、それら自体はパラメータ化できません。セクション3.3参照）です。

実装は、インデックスとキーによるParametersへのアクセス方法を提供しなければなりません (MUST)。仕様はいずれかのアクセス方法を使用してもかまいません (MAY)。

ABNF構文​

parameters    = *( ";" *SP parameter )
parameter     = param-key [ "=" param-value ]
param-key     = key
key           = ( lcalpha / "*" )
                *( lcalpha / DIGIT / "_" / "-" / "." / "*" )
lcalpha       = %x61-7A ; a-z
param-value   = bare-item

形式の説明​

  • パラメータはシリアライゼーション順で並べられます
  • パラメータキーに大文字を含めることはできません
  • パラメータはセミコロンでそのItemまたはInner Listおよび他のパラメータから分離されます

例​

Example-List: abc;a=1;b=2; cde_456, (ghi;jk=4 l);q="9";r=w

Booleanパラメータの特別なルール​

Boolean（セクション3.3.6参照）trueの値を持つパラメータは、シリアライズ時にその値を省略しなければなりません (MUST)。

例:

Example-Integer: 1; a; b=?0

ここで、a パラメータはtrueで、b パラメータはfalseです。

注意: この要件はシリアライゼーションのみに適用されます。パーサーは、パラメータ内に出現するtrue値を正しく処理する必要があります。

実装要件​

実装は、少なくとも256個のパラメータを持つパラメータリストをサポートしなければなりません (MUST)。フィールド仕様は、必要に応じて個々のParametersの基数を制約できます。

3.2 Dictionaries (辞書)​

Dictionariesは、名前付きメンバーの順序付きマッピングで、各メンバーの名前はキーで、値はItem（セクション3.3）またはInner Listの配列（セクション3.1.1）のいずれかです。どちらもパラメータ化できます（セクション3.1.2）。

ABNF構文​

sf-dictionary  = dict-member *( OWS "," OWS dict-member )
dict-member    = member-key ( parameters / ( "=" member-value ))
member-key     = key
member-value   = sf-item / inner-list

形式の説明​

  • メンバーはカンマとオプションの空白で区切られます
  • メンバー名はそのDictionary内で一意でなければなりません
  • 重複するメンバー名が解析された場合、最後のものだけが使用されます

例​

Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=:

Stringsとバイトシーケンスの値を持つDictionaryとして定義されたフィールド。

Boolean値の特別なルール​

値がBoolean true（セクション3.3.6）のDictionaryメンバーは、"=" およびその値を省略してシリアライズされます。

例:

Example-Dict: a=?0, b, c; foo=bar

ここで、b の値はBooleantrueで、c の値もBoolean trueでパラメータ foo を持ちます。

実装要件​

パーサーは、少なくとも1024個のメンバーを含むDictionariesをサポートしなければなりません (MUST)。フィールド仕様は、必要に応じて個々のDictionary値の型と基数を制約できます。

3.3 Items (項目)​

Itemは、裸の項目 (bare item, セクション3.3.1～3.3.6) とオプションのパラメータ (セクション3.1.2) で構成されます。

ABNF構文​

sf-item    = bare-item parameters
bare-item  = sf-integer / sf-decimal / sf-string / sf-token
             / sf-binary / sf-boolean

3.3.1 Integers (整数)​

Integersは、範囲が-999,999,999,999,999から999,999,999,999,999（両端を含む）の数値です。

ABNF構文​

sf-integer = ["-"] 1*15DIGIT

例​

Example-Integer: 42
Example-Integer: -42
Example-Integer: 0

実装要件​

実装は、指定された範囲内のすべてのIntegersをサポートしなければなりません (MUST)。

3.3.2 Decimals (小数)​

Decimalsは、小数点の右側に最大3桁の有効数字を持つ数値です。

ABNF構文​

sf-decimal  = ["-"] 1*12DIGIT "." 1*3DIGIT

例​

Example-Decimal: 4.5
Example-Decimal: -4.5
Example-Decimal: 123.456

実装要件​

  • 小数点の左側: 最大12桁の有効数字
  • 小数点の右側: 最大3桁の有効数字

3.3.3 Strings (文字列)​

Stringsは、ASCIIの印刷可能文字のシーケンスです（VCHAR、SP）。

ABNF構文​

sf-string = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E / "\" ( DQUOTE / "\" )) DQUOTE

エスケープ​

  • バックスラッシュ (\) と二重引用符 (") のみエスケープ可能
  • これら以外の文字の後のバックスラッシュはパース失敗を引き起こす必要があります

例​

Example-String: "hello world"
Example-String: "say \"hi\""

実装要件​

パーサーは、（デコード後）少なくとも1024文字のStringsをサポートしなければなりません (MUST)。

3.3.4 Tokens (トークン)​

Tokensは、短いテキストワードです。その抽象モデルは、HTTPフィールド値シリアライゼーションでの表現と同じです。

ABNF構文​

sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )

例​

Example-Token: foo123/456
Example-Token: *

実装要件​

パーサーは、少なくとも512文字のTokensをサポートしなければなりません (MUST)。

3.3.5 Byte Sequences (バイトシーケンス)​

Byte Sequencesは、構造化フィールドで伝達できます。

ABNF構文​

sf-binary = ":" *(base64) ":"
base64    = ALPHA / DIGIT / "+" / "/" / "="

例​

Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

実装要件​

パーサーは、デコード後少なくとも16384オクテットのByte Sequencesをサポートしなければなりません (MUST)。

3.3.6 Booleans (ブール値)​

Boolean値は、構造化フィールドで伝達できます。

ABNF構文​

sf-boolean = "?" boolean
boolean    = "0" / "1"

例​

Example-Boolean: ?1
Example-Boolean: ?0

形式の説明​

  • Booleanは先頭の "?" 文字で示されます
  • "1" はtrueを示します
  • "0" はfalseを示します

Dictionary とParameterでの特別な動作​

Dictionary（セクション3.2）およびParameter（セクション3.1.2）の値では、Boolean trueは値を省略することで示されます。

データ型まとめ​

型範囲/形式例
Integer-999,999,999,999,999 ～ 999,999,999,999,99942, -100
Decimal整数部12桁、小数部3桁4.5, -0.123
StringASCII印刷可能文字、最大1024文字"hello world"
Token英数字と記号、最大512文字foo123/456
Byte SequenceBase64エンコード、最大16384オクテット:SGVsbG8=:
Booleantrue/false?1, ?0
に最終更新