Design how header values should be validated in Gavel

[honzajavorek]

Currently Gavel only validates missing headers, i.e. it doesn't look at values, except for content negotiation header values.

However, OAS has headers more like schemas, and API Blueprint plans to introduce similar stuff in the future as well, so API Elements actually already bake in some extra information about what values are expected:

key:
 element: 'string',
 content: 'X-Rate-Limit'
value:
 element: 'number'

This cannot be easily converted to JSON Schema as the number doesn't mean number per se, but indicates that the value should be a string which is parseable as number. Also, these are semantically equivalent:

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next"
Link: <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
      <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

The value of the member might be expected to perhaps be an array, but if the user said it is a string, then a string may be also an array (just because they put the Accept header is a string, the RFC for Accept header says that you can define multiple parts with , etc.).

For the most part, the validation rules for headers from RFC 2616 should be considered, and maybe even more strict that what user puts? (That's up to a question whether Gavel wants to do HTTP spec validation as well, and so far the maintainers are aligned about the idea that it should not be do HTTP spec validation.)

This is all very unexplored area and it is not very clear how the information contained in API Elements should be conveyed to Gavel on input so Gavel could validate the headers. Gavel currently validates the headers as if they were a one level deep JSON object, so introducing JSON Schema to the mix might seem like the most straightforward option, but perhaps that's not possible and the current solution is a dead end. Having a custom validator for the headers might not be such an issue, but what format should Gavel accept on input if JSON Schema? There is a dedicated schema language for URIs, but not for HTTP headers.

---

Most of the issue is @kylef's thoughts written down. Internal discussion link for a reference.

[honzajavorek]

Related to #160 as multiple headers of the same name are another proof that Gavel's current understanding of the headers domain isn't correct and needs to be redesigned.