Should "headerSchema" always be of type array for HTTP?

[handrews]

We're a bit ambiguous on how headerSchema works. targetSchema, for HTTP or anything similar that allows repeated headers and/or headers with multiple values (which are equivalent in HTTP), we require the hint value to always be an array, even if only one element. This is consistent with the JSON Encoding for HTTP Header Field Values draft that we cite.

However, headerSchema does not clearly state such guidance, and I know I have often written it as assuming a single value (and therefore not an array).

This is fine for most circumstances, but if you want to require someone to pass multiple distinct values through the header, it is not possible to do so in a consistent way.

Should all schemas in headerSchemas for HTTP (and similar systems) be of "type": "array" and use "items" (either the single schema or tuple syntax) for their contents?

The one implementation that I know of, https://github.com/mokkabonna/json-hyper-schema from @mokkabonna, does not do anything specific with headerSchema, as that is not necessary for link construction.

The Getting Started With JSON Hyper-Schema, Part 2, from @Dashron, shows it as a schema describing a single value. I reviewed that article and either approved of it or was the person who told him that's how it worked :-P

My personal inclination is to say that it has to be an array schema and to use items. It's a bit more boilerplate, but it is also more consistent, and covers a small but significant gap (e.g. what if I want to say that you have to supply both the "respond-async" preference and the "wait" preference if you supply either of them- those are two separate preferences that often work together).

Also paging @dlax, @philsturgeon

[philsturgeon]

+1 for consistency, especially if we're ourselves are forgetting which one is correct.

[handrews]

Digging into this a bit more, trying to figure out a general structure for HTTP headers, they mostly consist of a single value (multiple values being equivalent to multiple occurrences of the header) and zero or more parameters. The value is probably either a string (Content-Type, WWW-Authenticate) or a single name=value pair (Prefer). Parameters are often name=value pairs, but can be strings.

Prefer makes it explicit that single strings are interchangeable with a name=value pair where the value is the empty string.

The auth headers are annoying in that they separate their parameters with commas instead of semi-colons, which somehow ends up not being ambiguous grammatically, and seriously wtf people. But we can pretend they're normal.

So, using Prefer as the most complicated I could find (name=value pair for primary value and for parameters), we get something like this as a generic structure (more or less based on this email thread for the tuple thing, although ignoring the possibility of nested values where the nesting uses the same delimiters as the outer part because 💥 🤕 )

{
  "$comment": "Always array to allow multiple occurrences",
  "type": "array",
  "items": {
    "$comment": "Must be tuple to allow name=value primary",
    "type": "array",
    "minItems": 1,
    "items": [ 
      { 
        "description": "This is the primary value",
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1 
      },
      { 
        "description": "These are the parameters",
        "type": "object"
      } 
    ]
  }
}

Now, we could say "we think nearly everything can be hammered into this shape with Prefer's "single strings are equivalent to names with empty string values" approach, or we could encourage simpler schemas for simpler headers. This WWW-Authenticate example would drop the tuple since the primary value is a string and works as an object key. So a generic schema for headers like this would look like:

{
  "$comment": "Always array to allow multiple occurrences",
  "type": "array",
  "items": {
    "$comment": "Object because value is always one string",
    "type": "object",
    "minProperties": 1,
    "maxProperties": 1,
    "additionalProperties": { 
      "description": "These are the parameters",
      "type": "object"
    } 
  }
}

and the propertyNames keyword could be used to restrict the set of valid primary values.

Going further, the Accept-Encoding example shows this general syntax with various simplifications down to single strings (as Accept-Encoding does not equate single strings to empty string values). To cover all of these JSON structures, we would use:

{
  "$comment": "Always array to allow multiple occurrences",
  "type": "array",
  "items": {
    "$comment": "Object because value is always one string",
    "type": ["string", "object"],
    "minProperties": 1,
    "maxProperties": 1,
    "additionalProperties": { 
      "description": "These are the parameters",
      "type": ["string", "object"]
    } 
  }
}

which is not bad.

If we wanted to combine this with the Prefer scenario where the main value can itself be a name=value pairs, and allow for all name=value pairs to optionally just be strings, we end up with the following (assuming you would not use the tuple syntax with a string primary value as its more complex and adds nothing):

{
  "$comment": "Always array to allow multiple occurrences",
  "type": "array",
  "items": {
    "oneOf": [
      { 
        "type": "array",
        "minItems": 1,
        "items": [
          { 
            "description": "This is the primary value",
            "type": "object",
            "minProperties": 1,
            "maxProperties": 1
          },
          { 
            "description": "These are the parameters",
            "type": ["string", "object"]
          }
        ]
      },
      { 
        "type": ["string", "object"],
        "minProperties": 1,
        "maxProperties": 1,
        "additionalProperties": { 
          "description": "These are the parameters",
          "type": ["string", "object"]
        }
      }
    ]
  }
}

which is more than a little messy but not that hard to follow once you break it down. Here is the most compact way to write it:

{
  "$comment": "Always array to allow multiple occurrences",
  "type": "array",
  "items": {
    "type": ["string", "object", "array"],
    "minProperties": 1,
    "maxProperties": 1,
    "additionalProperties": { 
      "description": "These are the parameters",
      "type": ["string", "object"]
    },  
    "minItems": 1,
    "items": [
      {   
        "description": "This is the primary value",
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1
      },  
      {   
        "description": "These are the parameters",
        "type": ["string", "object"]
      }   
    ]   
  }
}

---

Do we want to provide some sort of recommendation here? Do we want to include the schema that covers the various common structure as a $defs entry in the meta-schema to encourage folks to use it as a base? Or should we stick with "Make it an array to allow multiple values, and follow https://tools.ietf.org/html/draft-reschke-http-jfv-09 as best you can"?

[handrews]

We're going to:

stick with "Make it an array to allow multiple values, and follow https://tools.ietf.org/html/draft-reschke-http-jfv-09 as best you can"?

because I just want to ship the draft at this point, and the array-for-multi-value thing for symmetry with targetHints is the real point of confusion. The rest is open to interpretation and we can refine it next time (Hyper-Schema is not as close to RFC as the others anyway).