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

[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

[webron]

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]

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.

[handrews]

@ePaul @themihai if you are still interested in this, I am on the verge of publishing draft-07 of Hyper-Schema

This includes several new features including for working with request and response headers and content negotiation. It also has a top-to-bottom rewrite to explain its purpose more clearly, and generally read better. You might find the new introduction and overview to be relevant.

Hyper-Schema and OpenAPI are definitely looking at slightly different problems. If Hyper-Schema draft-07 is well-received, it may be worth looking at whether and how they might fit together. But it's probably best for Hyper-Schema needs to prove itself useful (or not) on its own first.

[themihai]

That's awesome! I'm actually using a fork of hyper-schema and it served me well so far.

[handrews]

@themihai great! I'd welcome feedback from you on the pre-publication draft I linked above. Be warned that some things that may have seemed essential in draft-04 are no longer present or work in a different way. In particular, people freak out about method being gone (if you want to indicate method support, you can still do it with "targetHints": {"allow": ["GET", "PUT"]} and the like, but there's a lot of explanation of why you don't need to do that in the same way that you really needed to have method in draft-04)

This has to do with Hyper-Schema being a hypermedia type defining links (which imply operations, usually in a pretty obvious way), rather than OpenAPI being an API specification that defines operations explicitly.

[silkentrance]

I think that this is basically a data modelling issue. Whether or not your data supports the hyper-schema is up to the developer of the api. Of course, it would be nice to have a common set of mixins that one could use to model one's data types, e.g.

components:
  Foo:
   allOf:
     - type: hyper-schema-object
     - type: object
        ...

The hyper-schema-object then could be a built-in of and also a hint to the code generators when generating required code.

I just found out that over at Swagger they already have something like that
https://swagger.io/docs/specification/links/

[handrews]

Hyper-schema hasn't really been active since the revamp in draft-07 (tweaked in 2019-09). While there was a flurry of interest in the revamp, it never got widely adopted. I think we can close this as outdated - if Hyper-Schema is ever revived we can look at whatever that is if and when it happens.