Zum Hauptinhalt springen

2. Syntax

Eine URI-Vorlage ist eine Zeichenkette aus druckbaren Unicode-Zeichen, die null oder mehr eingebettete Variablenausdrücke (Variable Expressions) enthält, wobei jeder Ausdruck durch ein passendes Paar geschweifter Klammern (', ') begrenzt wird.

URI-Template  = *( literals / expression )

Obwohl Vorlagen (und Vorlagenprozessor-Implementierungen) oben in Bezug auf vier graduelle Ebenen beschrieben werden, definieren wir die URI-Template-Syntax in Bezug auf die ABNF für Level 4. Ein Vorlagenprozessor, der auf Vorlagen niedrigerer Ebenen beschränkt ist, KANN (MAY) die ABNF-Regeln ausschließen, die nur für höhere Ebenen gelten. Es wird jedoch EMPFOHLEN (RECOMMENDED), dass alle Parser die vollständige Syntax implementieren, sodass nicht unterstützte Ebenen als solche für den Endbenutzer ordnungsgemäß identifiziert werden können.

2.1. Literals (Literale)​

Die Zeichen außerhalb von Ausdrücken in einer URI-Vorlagenzeichenkette sollen wörtlich in die URI-Referenz kopiert werden, wenn das Zeichen in einem URI erlaubt ist (reserved / unreserved / pct-encoded), oder, wenn nicht erlaubt, als Sequenz von prozentkodiert

en Triplets, die der Kodierung dieses Zeichens in UTF-8 [RFC3629] entsprechen, in die URI-Referenz kopiert werden.

literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
              /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
              /  pct-encoded
                   ; jedes Unicode-Zeichen außer: CTL, SP,
                   ;  DQUOTE, "'", "%" (außer pct-encoded),
                   ;  "<", ">", "\", "^", "`", "{", "|", "}"

2.2. Expressions (Ausdrücke)​

Vorlagenausdrücke sind die parametrisierten Teile einer URI-Vorlage. Jeder Ausdruck enthält einen optionalen Operator (Operator), der den Ausdruckstyp und seinen entsprechenden Expansionsprozess definiert, gefolgt von einer durch Kommas getrennten Liste von Variablenspezifizierern (Variable Specifiers) (Variablennamen und optionale Wertmodifikatoren). Wenn kein Operator bereitgestellt wird, verwendet der Ausdruck standardmäßig die einfache Variablenexpansion von nicht reservierten Werten.

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

Die Operatorzeichen wurden gewählt, um ihre jeweilige Rolle als reservierte Zeichen in der URI-generischen Syntax widerzuspiegeln. Die in Abschnitt 3 dieser Spezifikation definierten Operatoren umfassen:

  • + Reservierte Zeichenketten (Reserved character strings)
  • # Fragment-Identifikatoren mit "#"-Präfix (Fragment identifiers)
  • . Namensbezeichnungen oder Erweiterungen mit "."-Präfix (Name labels or extensions)
  • / Pfadsegmente mit "/"-Präfix (Path segments)
  • ; Pfadparametername oder name=value-Paare mit ";"-Präfix (Path parameter name or name=value pairs)
  • ? Abfragekomponente, die mit "?" beginnt und aus name=value-Paaren besteht, die durch "&" getrennt sind (Query component)
  • & Fortsetzung von Abfrage-Stil-&name=value-Paaren innerhalb einer literalen Abfragekomponente (Continuation of query-style pairs)

Die Operatorzeichen Gleichheitszeichen ("="), Komma (","), Ausrufezeichen ("!"), At-Zeichen ("@") und Pipe ("|") sind für zukünftige Erweiterungen reserviert.

Die Ausdruckssyntax schließt die Verwendung des Dollar-Zeichens ("$") und der Klammern ["(" und ")"] ausdrücklich aus, sodass sie für die Verwendung außerhalb des Geltungsbereichs dieser Spezifikation verfügbar bleiben. Beispielsweise könnte eine Makrosprache diese Zeichen verwenden, um eine Makrosubstitution auf eine Zeichenkette anzuwenden, bevor diese Zeichenkette als URI-Vorlage verarbeitet wird.

2.3. Variables (Variablen)​

Nach dem Operator (falls vorhanden) enthält jeder Ausdruck eine Liste von einem oder mehreren durch Kommas getrennten Variablenspezifizierern (varspec). Die Variablennamen dienen mehreren Zwecken: Dokumentation für die erwarteten Werttypen, Identifikatoren zum Zuordnen von Werten innerhalb eines Vorlagenprozessors und die literale Zeichenkette, die für den Namen in name=value-Expansionen verwendet wird (außer beim Explodieren eines assoziativen Arrays). Variablennamen sind groß- und kleinschreibungssensitiv, da der Name in einer groß- und kleinschreibungssensitiven URI-Komponente expandiert werden kann.

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

Ein varname KANN (MAY) ein oder mehrere prozentkodierte Triplets enthalten. Diese Triplets werden als wesentlicher Bestandteil des Variablennamens betrachtet und während der Verarbeitung nicht dekodiert. Ein varname, der prozentkodierte Zeichen enthält, ist nicht dieselbe Variable wie ein varname mit denselben dekodierten Zeichen. Von Anwendungen, die URI-Vorlagen bereitstellen, wird erwartet, dass sie in ihrer Verwendung von Prozentkodierung in Variablennamen konsistent sind.

Ein Ausdruck KANN (MAY) auf Variablen verweisen, die dem Vorlagenprozessor unbekannt sind oder deren Wert auf einen speziellen "undefined (undefiniert)"-Wert wie undef oder null gesetzt ist. Solche undefinierten Variablen erhalten eine spezielle Behandlung durch den Expansionsprozess (Abschnitt 3.2.1).

Ein Variablenwert, der eine Zeichenkette der Länge null ist, wird nicht als undefiniert betrachtet; er hat den definierten Wert einer leeren Zeichenkette.

In Level 4-Vorlagen kann eine Variable einen zusammengesetzten Wert (Composite Value) in Form einer Werteliste oder eines assoziativen Arrays von (name, value)-Paaren haben. Solche Werttypen werden nicht direkt durch die Vorlagensyntax angezeigt, aber sie haben Auswirkungen auf den Expansionsprozess (Abschnitt 3.2.1).

Eine als Listenwert definierte Variable wird als undefiniert betrachtet, wenn die Liste null Mitglieder enthält. Eine als assoziatives Array von (name, value)-Paaren definierte Variable wird als undefiniert betrachtet, wenn das Array null Mitglieder enthält oder wenn alle Mitgliedsnamen im Array mit undefinierten Werten verknüpft sind.

2.4. Value Modifiers (Wertmodifikatoren)​

Jede der Variablen in einem Level 4-Vorlagenausdruck kann einen Modifikator haben, der entweder anzeigt, dass ihre Expansion auf ein Präfix der Wertzeichenkette der Variable beschränkt ist, oder dass ihre Expansion als zusammengesetzter Wert in Form einer Werteliste oder eines assoziativen Arrays von (name, value)-Paaren explodiert wird.

modifier-level4 =  prefix / explode

2.4.1. Prefix Values (Präfixwerte)​

Ein Präfixmodifikator (Prefix Modifier) zeigt an, dass die Variablenexpansion auf ein Präfix der Wertzeichenkette der Variable beschränkt ist. Präfixmodifikatoren werden häufig verwendet, um einen Identifikatorraum hierarchisch zu partitionieren, wie es bei Referenzindizes und hashbasiertem Speicher üblich ist. Es dient auch dazu, den expandierten Wert auf eine maximale Anzahl von Zeichen zu beschränken. Präfixmodifikatoren sind nicht auf Variablen anwendbar, die zusammengesetzte Werte haben.

prefix        =  ":" max-length
max-length    =  %x31-39 0*3DIGIT   ; positive Ganzzahl < 10000

Der max-length ist eine positive Ganzzahl, die sich auf eine maximale Anzahl von Zeichen vom Anfang des Variablenwerts als Unicode-Zeichenkette bezieht. Beachten Sie, dass diese Nummerierung in Zeichen, nicht in Oktetten erfolgt, um eine Aufteilung zwischen den Oktetten eines mehrfach-Oktett-kodierten Zeichens oder innerhalb eines prozentkodierte Triplets zu vermeiden. Wenn der max-length größer als die Länge des Variablenwerts ist, wird die gesamte Wertzeichenkette verwendet.

Zum Beispiel:

Gegebene Variablenzuweisungen

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

Beispielvorlage        Expansion

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

2.4.2. Composite Values (Zusammengesetzte Werte)​

Ein Explode-Modifikator (Explode Modifier) ("*") zeigt an, dass die Variable als zusammengesetzter Wert behandelt werden soll, der entweder aus einer Werteliste oder einem assoziativen Array von (name, value)-Paaren besteht. Daher wird der Expansionsprozess auf jedes Mitglied des Verbunds angewendet, als ob es als separate Variable aufgeführt wäre. Diese Art der Variablenspezifikation ist deutlich weniger selbstdokumentierend als nicht-explodierte Variablen, da es weniger Entsprechung zwischen dem Variablennamen und dem Erscheinungsbild der URI-Referenz nach der Expansion gibt.

explode       =  "*"

Da URI-Vorlagen keine Angabe von Typ oder Schema enthalten, wird angenommen, dass der Typ für eine explodierte Variable durch den Kontext bestimmt wird. Beispielsweise könnte dem Prozessor Werte in einer Form zur Verfügung gestellt werden, die Werte als Zeichenketten, Listen oder assoziative Arrays unterscheidet. Ebenso könnte der Kontext, in dem die Vorlage verwendet wird (Skript, Auszeichnungssprache, Schnittstellendefinitionssprache usw.), Regeln zur Zuordnung von Variablennamen zu Typen, Strukturen oder Schema definieren.

Explode-Modifikatoren verbessern die Kürze in der URI-Vorlagen-Syntax. Beispielsweise könnte eine Ressource, die eine geografische Karte für eine bestimmte Straßenadresse bereitstellt, hundert Permutationen von Feldern für die Adresseingabe akzeptieren, einschließlich Teiladressen (z. B. nur die Stadt oder Postleitzahl). Eine solche Ressource könnte als Vorlage mit jeder einzelnen Adresskomponente in der Reihenfolge aufgelistet oder mit einer weitaus einfacheren Vorlage beschrieben werden, die einen Explode-Modifikator verwendet, wie in:

/mapper{?address*}

zusammen mit einem Kontext, der definiert, was die Variable namens "address" enthalten kann, beispielsweise durch Verweis auf einen anderen Standard für Adressierung (z. B. [UPU-S42]). Ein Empfänger, der das Schema kennt, kann dann geeignete Expansionen bereitstellen, wie z. B.:

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

Der Expansionsprozess für explodierte Variablen hängt sowohl vom verwendeten Operator als auch davon ab, ob der zusammengesetzte Wert als Werteliste oder als assoziatives Array von (name, value)-Paaren behandelt werden soll. Strukturen werden als assoziatives Array mit Namen verarbeitet, die den Feldern in der Strukturdefinition entsprechen, und "."-Trennzeichen werden verwendet, um die Namenshierarchie in Unterstrukturen anzuzeigen.

Wenn eine Variable eine zusammengesetzte Struktur hat und nur einige der Felder in dieser Struktur definierte Werte haben, sind nur die definierten Paare in der Expansion vorhanden. Dies kann für Vorlagen nützlich sein, die aus einer großen Anzahl potenzieller Abfragebegriffe bestehen.

Ein Explode-Modifikator, der auf eine Listenvariable angewendet wird, führt dazu, dass die Expansion die Expansion dieser Variablen gemäß dem Operator wiederholt, einmal für jedes Listenmitglied.

Letztes Update am