These are test cases for implementations of Structured Fields for HTTP.

Each test file is a JSON document that contains an array of test records. A test record is an object with the following members:

• name: A string describing the test
• raw: An array of strings, each representing a field value received
• header_type: One of "item", "list", "dictionary"
• expected: The expected data structure after parsing (if successful). Required, unless must_fail is true.
• must_fail: boolean indicating whether the test is required to fail. Defaults to false.
• can_fail: boolean indicating whether failing this test is acceptable; for SHOULDs. Defaults to false.
• canonical: An array of strings representing the canonical form of the field value, if it is different from raw. Not applicable if must_fail is true.

The expected data structure maps the types in Structured Fields to JSON as follows:

• Dictionary: JSON array of arrays with two elements, the member name and the member value
• List: JSON array, where each element is either an Item or Inner-List
• Inner-List: JSON array of arrays with two elements, the list (a JSON array of Items) and Parameters
• Item: JSON array with two elements, the Bare-Item and Parameters
• Bare-Item: one of:
  • Integer: JSON numbers; e.g. 1
  • Float: JSON numbers; e.g. 2.5
  • String: JSON string; e.g., "foo"
  • Token: token __type Object (see below)
  • Binary Content: binary __type Object (see below)
  • Boolean: JSON boolean; e.g., true
  • Date: date __type Object (see below)
  • Display String: displaystring __type Object (see below)
• Parameters: JSON array of arrays with two element, the param name and the param value

For any test that case that has a valid outcome (i.e. must_fail is not true) the expected data structure can be serialised. The expected result of this serialisation is the canonical member if specified, or raw otherwise. The canonical form of a List or Dictionary with no members is an empty array, to represent the field being omitted.

Test cases in the serialisation-tests directory can be used to test serialisation of an invalid or non-canonical value. The expected structure (as defined above) should serialise to the canonical form, unless must_fail is true -- in which case the value cannot be serialised. These cases do not have a raw element.

JSON Schemas for these formats are provided in the schemas directory.

Because JSON doesn't natively accommodate some data types that Structured Fields does, the expected member uses an object with a __type member and a value member to represent these values.

For example:

{
  "__type": "token",
  "value": "foo"
}

... carries a "foo" token. The following types are defined:

• token: carries a Token as a JSON string; e.g., "bar"
• binary: carries Binary Content as a base32-encoded JSON string; e.g., "ZXW6==="
• date: Carries a Date as a JSON integer; e.g., 1692859242
• displaystring: Carries a Display String as a JSON string; e.g. "Füü"

All tests should have a descriptive name. Tests should be as simple as possible - just what's required to test a specific piece of behavior. If you want to test interacting behaviors, create tests for each behavior as well as the interaction.

If a test file ends in -generated.json, please modify generate.py and re-generate the tests in your PR.

Please feel free to contribute!