Zum Hauptinhalt springen

2. Defining New Structured Fields (Neue strukturierte Felder definieren)

Um ein HTTP-Feld als strukturiertes Feld zu spezifizieren, muss der Autor folgende Schritte durchführen:

Erforderliche Schritte​

1. Normative Referenz auf diese Spezifikation​

Empfänger und Erzeuger des Feldes müssen wissen, dass die Anforderungen dieses Dokuments gelten.

Beispiel-Referenztext:
"Dieses Feld ist ein strukturiertes Feld [RFC8941]."

2. Feldtyp identifizieren​

Festlegen, ob das Feld ein:

  • Strukturierter Header (Structured Header) ist: Nur im Header-Abschnitt verwendbar (häufigster Fall)
  • Strukturierter Trailer (Structured Trailer) ist: Nur im Trailer-Abschnitt verwendbar
  • Strukturiertes Feld (Structured Field) ist: In beiden Abschnitten verwendbar

3. Übergeordneten Datentyp angeben​

Einen der folgenden Typen auswählen:

  • List (Liste) – Abschnitt 3.1
  • Dictionary (Wörterbuch) – Abschnitt 3.2
  • Item (Element) – Abschnitt 3.3

4. Semantik des Feldwerts definieren​

Bedeutung und Zweck des Feldes beschreiben.

5. Zusätzliche Einschränkungen angeben​

Einschränkungen für den Feldwert definieren sowie die Konsequenzen bei Verletzung dieser Einschränkungen.

Definitionsmuster​

In der Regel gibt eine Felddefinition den übergeordneten Typ (List, Dictionary oder Item) an und definiert dann die zulässigen Typen und Einschränkungen.

Beispieleinschränkungen​

Felder vom Typ List:

  • Alle Mitglieder sind Integer
  • Oder gemischte Typen

Felder vom Typ Item:

  • Nur String erlaubt
  • Und nur Strings, die mit dem Buchstaben „Q" beginnen
  • Oder nur Strings in Kleinbuchstaben

Besonderer Hinweis: Innere Listen (Inner Lists, Abschnitt 3.1.1) sind nur gültig, wenn die Felddefinition dies ausdrücklich erlaubt.

Fehlerbehandlung​

Wenn das Parsen fehlschlägt, wird das gesamte Feld ignoriert (siehe Abschnitt 4.2); in den meisten Fällen sollten Verletzungen feldspezifischer Einschränkungen denselben Effekt haben.

Standardverhalten​

Szenario: Feld ist als Item definiert und muss ein Integer sein, aber ein String wird empfangen

Standardverhalten: Das Feld wird ignoriert

Wenn ein anderes Fehlerverhalten gewünscht wird, muss dies ausdrücklich angegeben werden.

Erweiterbarkeit​

Parameters (Parameter) – Erweiterungsmechanismus​

Item und Inner List erlauben Parameter als Erweiterungsmechanismus; das bedeutet, dass Werte in Zukunft erweitert werden können, um mehr Informationen aufzunehmen.

Zur Wahrung der Vorwärtskompatibilität: Feldspezifikationen sollten nicht (discouraged) das Vorhandensein unbekannter Parameter als Fehlerbedingung definieren.

„Grease"-Parameter​

Um die zukünftige Erweiterbarkeit weiter sicherzustellen und Konsumenten zur Verwendung vollständiger Parser-Implementierungen zu ermutigen, können Felddefinitionen festlegen, dass Sender „Grease"-Parameter hinzufügen.

Beispielstrategie:
---------
Eine Spezifikation kann festlegen, dass alle Parameter, die einem definierten Muster entsprechen,
für diesen Zweck reserviert sind, und dann empfehlen, sie in einem Teil der Anfragen zu senden.

Zweck:
----
Dies soll Empfänger davon abhalten, Parser zu schreiben, die Parameter nicht berücksichtigen.

Vorwärtskompatibilität bei Dictionary​

Spezifikationen, die Dictionary verwenden, können ebenfalls Vorwärtskompatibilität erreichen, indem sie verlangen, dass das Vorhandensein unbekannter Mitglieder sowie deren zugehörige Werte und Typen ignoriert werden. Nachfolgende Spezifikationen können weitere Mitglieder hinzufügen und entsprechende Einschränkungen festlegen.

Eine Erweiterung strukturierter Felder kann dann verlangen, dass ein Empfänger, der die Erweiterung versteht und feststellt, dass die definierten Werte die Einschränkungen nicht erfüllen, den gesamten Feldwert ignoriert.

Einschränkungsregeln​

Anforderungen können nicht gelockert werden​

Felddefinitionen können (cannot) die Anforderungen dieser Spezifikation nicht lockern, da dies die Verarbeitung durch allgemeine Software behindern würde; sie können nur zusätzliche Einschränkungen hinzufügen.

Beispiele für zulässige Einschränkungen:

  • Numerische Bereiche für Integer und Decimal
  • Formate für String und Token
  • Zulässige Typen in Dictionary-Werten
  • Anzahl der Items in einer List

Gilt für das gesamte Feld​

Felddefinitionen dürfen diese Spezifikation nur für den gesamten Feldwert verwenden, nicht für Teile davon.

Implementierungsgrenzen​

Mindestwerte​

Diese Spezifikation definiert Mindestwerte für die Länge oder Anzahl der verschiedenen unterstützten Strukturen.

Maximalwerte​

In den meisten Fällen werden keine Maximalgrößen angegeben, aber Autoren sollten sich bewusst sein, dass HTTP-Implementierungen verschiedene Grenzen für folgende Aspekte setzen:

  • Größe einzelner Felder
  • Gesamtanzahl der Felder
  • Gesamtgröße des Header- oder Trailer-Abschnitts

Namenskonventionen​

Spezifikationen können Feldnamen bezeichnen als:

  • „Strukturierter Header-Name (structured header name)"
  • „Strukturierter Trailer-Name (structured trailer name)"
  • „Strukturierter Feldname (structured field name)"

Feldwerte können bezeichnet werden als:

  • „Strukturierter Header-Wert (structured header value)"
  • „Strukturierter Trailer-Wert (structured trailer value)"
  • „Strukturierter Feldwert (structured field value)"

Verwendung von ABNF​

Felddefinitionen werden ermutigt (encouraged), die ABNF-Regeln aus dieser Spezifikation zu verwenden, die mit „sf-" beginnen; andere Regeln in dieser Spezifikation sind nicht für die Verwendung in Felddefinitionen vorgesehen.

Vollständiges Beispiel: Foo-Example-Header​

42.  Foo-Example Header
  
The Foo-Example HTTP header field conveys information about how
much Foo the message has.
  
Foo-Example is an Item Structured Header [RFC8941].  Its value
MUST be an Integer (Section 3.3.1 of [RFC8941]).  Its ABNF is:
  
      Foo-Example = sf-integer
  
Its value indicates the amount of Foo in the message, and it MUST
be between 0 and 10, inclusive; other values MUST cause the entire
header field to be ignored.
  
The following parameter is defined:
*  A parameter whose key is "foourl", and whose value is a String
   (Section 3.3.3 of [RFC8941]), conveying the Foo URL for the
   message.  See below for processing requirements.
  
"foourl" contains a URI-reference (Section 4.1 of [RFC3986]).  If
its value is not a valid URI-reference, the entire header field
MUST be ignored.  If its value is a relative reference
(Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of
[RFC3986]) before being used.
  
For example:
  
      Foo-Example: 2; foourl="https://foo.example.com/"

Beispielanalyse​

Foo-Example: 2; foourl="https://foo.example.com/"

Parsen:

  • Typ: Item (Integer)
  • Wert: 2
  • Parameter: foourl="https://foo.example.com/"

Validierung:

  1. Wert ist Integer ✓
  2. Wert liegt im Bereich 0–10 ✓
  3. Parameter foourl vorhanden ✓
  4. foourl ist eine gültige URI ✓

Wenn der Wert 15 ist:

Foo-Example: 15; foourl="https://foo.example.com/"

Ergebnis: Das gesamte Feld wird ignoriert (Verletzung der Bereichseinschränkung 0–10)

Checkliste (Checklist)​

Beim Definieren eines neuen strukturierten Feldes sicherstellen, dass:

  • RFC 8941 normativ referenziert wird
  • Das Feld klar als Header/Trailer/Field ausgewiesen ist
  • Der übergeordnete Typ (List/Dictionary/Item) angegeben ist
  • Die Feldsemantik definiert ist
  • Typeinschränkungen angegeben sind
  • Wertebereichseinschränkungen definiert sind (falls zutreffend)
  • Parameter beschrieben sind (falls vorhanden)
  • Fehlerbehandlung definiert ist (falls abweichend vom Standard)
  • Vorwärtskompatibilität berücksichtigt wurde
  • Beispiele bereitgestellt wurden

Wesentliche Erkenntnisse (Key Takeaways)​

  1. Fünf erforderliche Schritte: Referenz, Typ, Datentyp, Semantik, Einschränkungen
  2. Strenger Standard: Parse-Fehler = Feld ignorieren
  3. Erweiterbarkeit zuerst: Verwendung von Parametern und Ignorieren unbekannter Mitglieder empfohlen
  4. Nur Einschränkungen hinzufügen: Anforderungen von RFC 8941 können nicht gelockert werden
  5. Vollständiges Feld: Spezifikation gilt für den gesamten Feldwert
  6. Implementierungsgrenzen: Größenbeschränkungen von HTTP-Implementierungen beachten