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:
- Wert ist Integer ✓
- Wert liegt im Bereich 0–10 ✓
- Parameter foourl vorhanden ✓
- 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)
- Fünf erforderliche Schritte: Referenz, Typ, Datentyp, Semantik, Einschränkungen
- Strenger Standard: Parse-Fehler = Feld ignorieren
- Erweiterbarkeit zuerst: Verwendung von Parametern und Ignorieren unbekannter Mitglieder empfohlen
- Nur Einschränkungen hinzufügen: Anforderungen von RFC 8941 können nicht gelockert werden
- Vollständiges Feld: Spezifikation gilt für den gesamten Feldwert
- Implementierungsgrenzen: Größenbeschränkungen von HTTP-Implementierungen beachten