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

2. Syntax (構文)

URIテンプレートは、印刷可能なUnicode文字の文字列であり、ゼロ個以上の埋め込まれた変数式 (Variable Expressions) を含み、各式は対応する波括弧 (', ') のペアで区切られます。

URI-Template  = *( literals / expression )

テンプレート（およびテンプレートプロセッサ実装）は上記で4つの段階的なレベルで説明されていますが、URIテンプレート構文はLevel 4のABNFで定義します。低レベルのテンプレートに限定されたテンプレートプロセッサは、より高いレベルにのみ適用されるABNF規則を除外してもよい (MAY) です。ただし、すべてのパーサーが完全な構文を実装して、サポートされていないレベルをエンドユーザーに適切に識別できるようにすることが推奨されます (RECOMMENDED)。

2.1. Literals (リテラル)​

URIテンプレート文字列の式の外側の文字は、その文字がURIで許可されている場合 (reserved / unreserved / pct-encoded)、URI参照に文字通りコピーされることを意図しています。許可されていない場合は、UTF-8 [RFC3629] でのその文字のエンコーディングに対応するパーセントエンコードされたトリプレットのシーケンスとしてURI参照にコピーされます。

literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
              /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
              /  pct-encoded
                   ; 任意のUnicode文字、ただし次を除く: CTL, SP,
                   ;  DQUOTE, "'", "%" (pct-encoded以外),
                   ;  "<", ">", "\", "^", "`", "{", "|", "}"

2.2. Expressions (式)​

テンプレート式はURIテンプレートのパラメータ化された部分です。各式には、式の型とそれに対応する展開プロセスを定義するオプションの演算子 (Operator) と、それに続くカンマ区切りの変数指定子 (Variable Specifiers) のリスト（変数名とオプションの値修飾子）が含まれます。演算子が提供されていない場合、式はデフォルトで予約されていない値の単純な変数展開になります。

expression    =  "{" [ operator ] variable-list "}"
operator      =  op-level2 / op-level3 / op-reserve
op-level2     =  "+" / "#"
op-level3     =  "." / "/" / ";" / "?" / "&"
op-reserve    =  "=" / "," / "!" / "@" / "|"

演算子文字は、URI一般構文における予約文字としての役割を反映するように選択されています。本仕様の第3節で定義されている演算子には以下が含まれます：

  • + 予約文字列 (Reserved character strings)
  • # "#" で接頭辞が付けられたフラグメント識別子 (Fragment identifiers)
  • . "." で接頭辞が付けられた名前ラベルまたは拡張 (Name labels or extensions)
  • / "/" で接頭辞が付けられたパスセグメント (Path segments)
  • ; ";" で接頭辞が付けられたパスパラメータ名またはname=valueペア (Path parameter name or name=value pairs)
  • ? "?" で始まり "&" で区切られたname=valueペアで構成されるクエリコンポーネント (Query component)
  • & リテラルクエリコンポーネント内のクエリ形式 &name=valueペアの継続 (Continuation of query-style pairs)

演算子文字の等号 ("=")、カンマ (",")、感嘆符 ("!")、アットマーク ("@")、およびパイプ ("|") は将来の拡張のために予約されています。

式構文は、ドル記号 ("$") と括弧 ["(" および ")"] 文字の使用を特に除外しているため、本仕様の範囲外で使用できるようになっています。たとえば、マクロ言語は、文字列をURIテンプレートとして処理する前に、これらの文字を使用して文字列にマクロ置換を適用する場合があります。

2.3. Variables (変数)​

演算子（存在する場合）の後、各式には1つ以上のカンマ区切りの変数指定子 (varspec) のリストが含まれます。変数名には複数の目的があります：期待される値の種類のドキュメント、テンプレートプロセッサ内で値を関連付けるための識別子、およびname=value展開で名前に使用するリテラル文字列（関連配列を展開する場合を除く）。変数名は大文字と小文字を区別します。これは、名前が大文字と小文字を区別するURIコンポーネント内で展開される可能性があるためです。

variable-list =  varspec *( "," varspec )
varspec       =  varname [ modifier-level4 ]
varname       =  varchar *( ["."] varchar )
varchar       =  ALPHA / DIGIT / "_" / pct-encoded

varname には1つ以上のパーセントエンコードされたトリプレットを含めることができます (MAY)。これらのトリプレットは変数名の本質的な部分と見なされ、処理中にデコードされません。パーセントエンコードされた文字を含む varname は、これらの同じ文字がデコードされた varname とは異なる変数です。URIテンプレートを提供するアプリケーションは、変数名内でパーセントエンコードを一貫して使用することが期待されます。

式は、テンプレートプロセッサに不明な変数、または値が特別な "undefined (未定義)" 値（undef や null など）に設定されている変数を参照してもよい (MAY) です。このような未定義の変数は、展開プロセスで特別な扱いを受けます（第3.2.1節）。

長さゼロの文字列の変数値は未定義とは見なされません。空の文字列の定義された値を持ちます。

Level 4テンプレートでは、変数は値のリストまたは (name, value) ペアの連想配列の形式で複合値 (Composite Value) を持つことができます。このような値型はテンプレート構文によって直接示されませんが、展開プロセスに影響を与えます（第3.2.1節）。

リストにゼロメンバーが含まれている場合、リスト値として定義された変数は未定義と見なされます。配列にゼロメンバーが含まれているか、配列内のすべてのメンバー名が未定義の値に関連付けられている場合、(name, value) ペアの連想配列として定義された変数は未定義と見なされます。

2.4. Value Modifiers (値修飾子)​

Level 4テンプレート式の各変数には、その展開が変数値文字列の接頭辞に制限されることを示す修飾子、または値のリストまたは (name, value) ペアの連想配列の形式で複合値として展開されることを示す修飾子を持つことができます。

modifier-level4 =  prefix / explode

2.4.1. Prefix Values (プレフィックス値)​

プレフィックス修飾子 (Prefix Modifier) は、変数展開が変数値文字列のプレフィックスに制限されることを示します。プレフィックス修飾子は、参照インデックスやハッシュベースのストレージで一般的なように、識別子空間を階層的に分割するためによく使用されます。また、展開された値を最大文字数に制限する役割も果たします。プレフィックス修飾子は複合値を持つ変数には適用されません。

prefix        =  ":" max-length
max-length    =  %x31-39 0*3DIGIT   ; 正の整数 < 10000

max-length は、Unicode文字列としての変数値の先頭からの最大文字数を参照する正の整数です。この番号付けは、マルチオクテットエンコード文字のオクテット間またはパーセントエンコードされたトリプレット内での分割を避けるため、オクテットではなく文字単位であることに注意してください。max-length が変数値の長さよりも大きい場合、値文字列全体が使用されます。

例：

変数割り当て

  var   := "value"
  semi  := ";"

テンプレート例       展開

  {var}              value
  {var:20}           value
  {var:3}            val
  {semi}             %3B
  {semi:2}           %3B

2.4.2. Composite Values (複合値)​

展開修飾子 (Explode Modifier) ("*") は、変数が値のリストまたは (name, value) ペアの連想配列で構成される複合値として扱われることを示します。したがって、展開プロセスは、複合の各メンバーが個別の変数としてリストされているかのように適用されます。この種の変数指定は、変数名と展開後のURI参照の表示方法との対応が少ないため、非展開変数よりも自己文書化の程度が大幅に低くなります。

explode       =  "*"

URIテンプレートには型やスキーマの指示が含まれていないため、展開された変数の型はコンテキストによって決定されると想定されます。たとえば、プロセッサは、文字列、リスト、または連想配列として値を区別する形式で値を提供される場合があります。同様に、テンプレートが使用されるコンテキスト（スクリプト、マークアップ言語、インターフェース定義言語など）は、変数名を型、構造、またはスキーマに関連付けるルールを定義する場合があります。

展開修飾子はURIテンプレート構文の簡潔性を向上させます。たとえば、特定の住所の地理的マップを提供するリソースは、部分的な住所（市区町村や郵便番号のみなど）を含む、住所入力のフィールドに対する数百の順列を受け入れる場合があります。このようなリソースは、すべての住所コンポーネントを順番にリストしたテンプレートとして記述することも、展開修飾子を使用したはるかにシンプルなテンプレートとして記述することもできます：

/mapper{?address*}

"address" という名前の変数に何を含めることができるかを定義するコンテキストとともに、たとえば住所に関する他の標準（例：[UPU-S42]）への参照によって。スキーマを認識している受信者は、次のような適切な展開を提供できます：

/mapper?city=Newport%20Beach&state=CA

展開変数の展開プロセスは、使用されている演算子と、複合値を値のリストとして扱うか、(name, value) ペアの連想配列として扱うかの両方に依存します。構造は、構造定義のフィールドに対応する名前を持つ連想配列として処理され、"." セパレータを使用してサブ構造の名前階層を示します。

変数が複合構造を持ち、その構造のフィールドの一部のみが定義された値を持つ場合、展開には定義されたペアのみが存在します。これは、多数の潜在的なクエリ用語で構成されるテンプレートに役立ちます。

リスト変数に適用される展開修飾子は、各リストメンバーに対して演算子に従って変数の展開を繰り返す展開を引き起こします。

に最終更新