JSON Schema with Custom Headers

[Charles Reese]

I would like to use JSON Schema for my org but our API uses headers. I'm wondering how to specify those in the schema. For example, many requests need an Authorization header. Others require custom headers, like "X-Session". Is there a way to capture this in a JSON Schema/JSON Hyper-Schema in way that doesn't violate the spec? I need this to work with existing tools for auto-generation of documentation.

Thanks!

[Matthew King]

Basic JSON Schema is for describing data structures in general.  As such, it is great for validating HTTP request and response bodies.  It is not particularly capable of describing the rich fullness of HTTP requests.

The hyperschema spec partially bridges that gap by offering media types and named hrefs.  But there's a lot more to HTTP than URLs and media types.  Standardized HTTP headers vary wildly in their formats and uses.  Custom headers may use whatever format the developer desires.  I do not think JSON Schema should even try to handle this problem.  Schemas are useful for validating or reflecting on data structures.

What I suspect you're looking for (because I've been trying to solve this problem for years) is a format for describing HTTP APIs that is as useful as JSON Schema.  Such a forrmat would also be an excellent basis for auto-generation of documentation.  Ideally, we could describe an HTTP API in a form that could be serialized to JSON, and both server and clients could make use of the description.