How does swagger-spec relate to hyper-media schema? #370

Open
themihai opened this Issue May 19, 2015 · 2 comments

Projects

None yet

3 participants

@themihai

It seems to me that several swagger properties are actually implemented into the hyper-media schema but with different conventions (e.g. links [0]) . I'm wondering what are the reasons to use proprietary specifications (i.e. what swagger does and hyper-media can't ).

[0] http://json-schema.org/latest/json-schema-hypermedia.html#anchor35

@themihai themihai changed the title from How does swagger-spec relates to hyper-media schema? to How does swagger-spec relate to hyper-media schema? May 19, 2015
@webron
Member
webron commented May 20, 2015

While working on Swagger 2.0, we decided to not include explicit support to hypermedia. Swagger 2.0 was already a huge change from the previous version, and we didn't want to overload it. We also felt there wasn't a wide enough adoption of it back then, though the scene may have changed since.

We're definitely looking into adding explicit support to it in future, in one form or another.

@ePaul
ePaul commented Apr 19, 2016

I just had a look at the JSON Hyper-Schema specification, and while it does solve some of the same problems as OpenAPI, it looks like it doesn't really fit together with OpenAPI as it is now.

In addition to a "normal" object schema definition, we have a description of "links", each of which can somehow extracted from the object (or derived from its properties, using some kind of pattern similar to our path definitions, like "/{id}/comments" to make a relative URI reference from a number). Each link then has some properties defining possible parameters (both query and body parameters). There is also a targetSchema property which defines what is expected to be returned.

What is useful is that it it also mentions the media types, which could then be used for an accept header (or Content-Type, in case of POST/PUT), and it also defines the link relation type for each link.

I think my proposal of interfaces (in #577 + #650) for URI fields is simpler (in that any URI to be used must be actually in the object containing the links, it will not be constructed from that using templates with some substitution beforehand). Also, it uses the existing OpenAPI infrastructure (path items with operations) instead of using a different syntax for a similar goal as the path descriptions again.
I'll have a look on how the link relations can be incorporated here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment