New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

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

Comments

Projects
None yet
5 participants
@themihai

themihai commented May 19, 2015

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

This comment has been minimized.

Show comment
Hide comment
@webron

webron May 20, 2015

Member

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.

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

This comment has been minimized.

Show comment
Hide comment
@ePaul

ePaul Apr 19, 2016

Contributor

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.

Contributor

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.

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Oct 27, 2017

@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.

handrews commented Oct 27, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@themihai

themihai Oct 28, 2017

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

themihai commented Oct 28, 2017

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

@handrews

This comment has been minimized.

Show comment
Hide comment
@handrews

handrews Oct 28, 2017

@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.

handrews commented Oct 28, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@silkentrance

silkentrance Aug 3, 2018

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/

silkentrance commented Aug 3, 2018

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/

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