Zum Hauptinhalt springen

3. Structured Data Types (Strukturierte Datentypen)

Dieser Abschnitt definiert die abstrakten Typen von strukturierten Feldern. Die bereitgestellte ABNF stellt das Übertragungsformat in HTTP-Feldwerten dar.

Überblick​

  • Es gibt drei Typen der obersten Ebene, die zur Definition von HTTP-Feldern verwendet werden können: Lists (Listen), Dictionaries (Wörterbücher) und Items (Elemente)

  • Lists und Dictionaries sind Container; ihre Mitglieder können Items oder Inner Lists sein (Inner Lists sind selbst Arrays von Items)

  • Sowohl Items als auch Inner Lists können mit Schlüssel-Wert-Paaren parametrisiert (Parameterized) werden

3.1 Lists (Listen)​

Lists sind Arrays, die null oder mehr Mitglieder enthalten, wobei jedes Mitglied ein Item (Abschnitt 3.3) oder eine Inner List (Abschnitt 3.1.1) sein kann, beide können parametrisiert werden (Abschnitt 3.1.2).

ABNF-Syntax​

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

Formatbeschreibung​

Jedes Mitglied ist durch ein Komma und optionale Leerzeichen getrennt.

Beispiel​

Example-List: sugar, tea, rum

Als Token-Liste definiertes Feld

Leere Liste​

Eine leere List wird dargestellt, indem das Feld überhaupt nicht serialisiert wird. Dies bedeutet, dass als Lists definierte Felder standardmäßig einen leeren Wert haben.

Mehrzeilige Aufteilung​

Die Mitglieder von Lists können über mehrere Zeilen im selben Header- oder Trailer-Abschnitt aufgeteilt werden (gemäß [RFC7230] Abschnitt 3.2.2); zum Beispiel sind die folgenden äquivalent:

Example-List: sugar, tea, rum

Äquivalent zu:

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

Hinweis: Einzelne Mitglieder einer List können nicht sicher zwischen Zeilen aufgeteilt werden; siehe Abschnitt 4.2 für Details.

Implementierungsanforderungen​

Parser müssen (MUST) Lists unterstützen, die mindestens 1024 Mitglieder enthalten. Feldspezifikationen können die Typen und die Kardinalität einzelner List-Werte nach Bedarf einschränken.

3.1.1 Inner Lists (Innere Listen)​

Eine Inner List ist ein Array, das null oder mehr Items (Abschnitt 3.3) enthält. Sowohl einzelne Items als auch die Inner List selbst können parametrisiert werden (Abschnitt 3.1.2).

ABNF-Syntax​

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

Formatbeschreibung​

Inner Lists sind von Klammern umgeben, ihre Werte sind durch ein oder mehrere Leerzeichen getrennt.

Beispiel 1: Einfache Inner Lists​

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

Als Liste von inneren Listen von Strings definiertes Feld. Beachten Sie, dass das letzte Mitglied eine leere Inner List ist.

Beispiel 2: Inner Lists mit Parametern​

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

Als Liste von inneren Listen mit Parametern definiertes Feld (mit Parametern auf zwei Ebenen).

Implementierungsanforderungen​

Parser müssen (MUST) Inner Lists unterstützen, die mindestens 256 Mitglieder enthalten. Feldspezifikationen können die Typen und die Kardinalität einzelner Inner List-Mitglieder nach Bedarf einschränken.

3.1.2 Parameters (Parameter)​

Parameters sind eine geordnete Zuordnung von Schlüssel-Wert-Paaren, die mit einem Item (Abschnitt 3.3) oder einer Inner List (Abschnitt 3.1.1) verknüpft sind. Schlüssel sind im Geltungsbereich der Parameters, in denen sie erscheinen, eindeutig, und Werte sind nackte Elemente (bare items) (d.h. sie können selbst nicht parametrisiert werden; siehe Abschnitt 3.3).

Implementierungen müssen (MUST) Zugriff auf Parameters sowohl per Index als auch per Schlüssel bereitstellen. Spezifikationen können (MAY) eine der beiden Zugriffsmethoden verwenden.

ABNF-Syntax​

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

Formatbeschreibung​

  • Parameter sind in Serialisierungsreihenfolge angeordnet
  • Parameterschlüssel können keine Großbuchstaben enthalten
  • Parameter sind durch Semikolons von ihrem Item oder Inner List und anderen Parametern getrennt

Beispiel​

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

Spezielle Regel für Boolean-Parameter​

Parameter mit einem Boolean-Wert (siehe Abschnitt 3.3.6) true müssen (MUST) diesen Wert bei der Serialisierung weglassen.

Beispiel:

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

Hier ist der Parameter a true, während der Parameter b false ist.

Hinweis: Diese Anforderung gilt nur für die Serialisierung; Parser müssen true-Werte, die in Parametern erscheinen, weiterhin korrekt verarbeiten.

Implementierungsanforderungen​

Implementierungen müssen (MUST) Parameterlisten mit mindestens 256 Parametern unterstützen. Feldspezifikationen können die Kardinalität einzelner Parameters nach Bedarf einschränken.

3.2 Dictionaries (Wörterbücher)​

Dictionaries sind geordnete Zuordnungen benannter Mitglieder, wobei der Name jedes Mitglieds ein Schlüssel ist und der Wert entweder ein Item (Abschnitt 3.3) oder ein Array von Inner Lists (Abschnitt 3.1.1) ist. Beide können parametrisiert werden (Abschnitt 3.1.2).

ABNF-Syntax​

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

Formatbeschreibung​

  • Mitglieder sind durch Kommas und optionale Leerzeichen getrennt
  • Mitgliedsnamen müssen innerhalb dieses Dictionary eindeutig sein
  • Wenn doppelte Mitgliedsnamen geparst werden, wird nur der letzte verwendet

Beispiel​

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

Als Dictionary mit Strings- und Byte-Sequence-Werten definiertes Feld.

Spezielle Regel für Boolean-Werte​

Dictionary-Mitglieder mit einem Boolean-true-Wert (Abschnitt 3.3.6) werden serialisiert, indem das "=" und sein Wert weggelassen werden.

Beispiel:

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

Hier ist der Wert von b Boolean true, und der Wert von c ist ebenfalls Boolean true mit einem Parameter foo.

Implementierungsanforderungen​

Parser müssen (MUST) Dictionaries unterstützen, die mindestens 1024 Mitglieder enthalten. Feldspezifikationen können die Typen und die Kardinalität einzelner Dictionary-Werte nach Bedarf einschränken.

3.3 Items (Elemente)​

Ein Item besteht aus einem nackten Element (bare item, Abschnitte 3.3.1 bis 3.3.6) und optionalen Parametern (Abschnitt 3.1.2).

ABNF-Syntax​

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

3.3.1 Integers (Ganzzahlen)​

Integers sind Zahlen mit einem Bereich von -999,999,999,999,999 bis 999,999,999,999,999 (einschließlich).

ABNF-Syntax​

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

Beispiele​

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

Implementierungsanforderungen​

Implementierungen müssen (MUST) alle Integers im angegebenen Bereich unterstützen.

3.3.2 Decimals (Dezimalzahlen)​

Decimals sind Zahlen mit bis zu 3 signifikanten Ziffern rechts vom Dezimalpunkt.

ABNF-Syntax​

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

Beispiele​

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

Implementierungsanforderungen​

  • Links vom Dezimalpunkt: maximal 12 signifikante Ziffern
  • Rechts vom Dezimalpunkt: maximal 3 signifikante Ziffern

3.3.3 Strings (Zeichenketten)​

Strings sind Sequenzen druckbarer ASCII-Zeichen (VCHAR, SP).

ABNF-Syntax​

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

Escape-Zeichen​

  • Nur Backslash (\) und doppelte Anführungszeichen (") können escaped werden
  • Ein Backslash nach diesen anderen Zeichen muss zu einem Parse-Fehler führen

Beispiele​

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

Implementierungsanforderungen​

Parser müssen (MUST) Strings von mindestens 1024 Zeichen (nach Dekodierung) unterstützen.

3.3.4 Tokens (Token)​

Tokens sind kurze Textwörter. Ihr abstraktes Modell ist identisch mit ihrer Darstellung in der HTTP-Feldwert-Serialisierung.

ABNF-Syntax​

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

Beispiele​

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

Implementierungsanforderungen​

Parser müssen (MUST) Tokens von mindestens 512 Zeichen unterstützen.

3.3.5 Byte Sequences (Byte-Sequenzen)​

Byte Sequences können in strukturierten Feldern übertragen werden.

ABNF-Syntax​

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

Beispiel​

Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

Implementierungsanforderungen​

Parser müssen (MUST) Byte Sequences von mindestens 16384 Oktetten nach Dekodierung unterstützen.

3.3.6 Booleans (Boolesche Werte)​

Boolesche Werte können in strukturierten Feldern übertragen werden.

ABNF-Syntax​

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

Beispiele​

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

Formatbeschreibung​

  • Booleans werden durch ein führendes "?"-Zeichen angezeigt
  • "1" zeigt true an
  • "0" zeigt false an

Spezielles Verhalten in Dictionary und Parameters​

In Dictionary (Abschnitt 3.2) und Parameter (Abschnitt 3.1.2) Werten wird Boolean true durch Weglassen des Werts angezeigt.

Zusammenfassung der Datentypen​

TypBereich/FormatBeispiel
Integer-999,999,999,999,999 bis 999,999,999,999,99942, -100
Decimal12 Ganzzahlziffern, 3 Dezimalziffern4.5, -0.123
StringDruckbare ASCII-Zeichen, max 1024 Zeichen"hello world"
TokenAlphanumerisch und Symbole, max 512 Zeichenfoo123/456
Byte SequenceBase64-Kodierung, max 16384 Oktette:SGVsbG8=:
Booleantrue/false?1, ?0