Search code examples
restjsonschemahateoas

When should I return a Json-schema to prevent out-of-band transfer of knowledge to REST API client?

In PoC stage to develop a HATEOAS REST API. Zeroed in on json-schema for everything schema. I am expecting clients to use this schema to smartly create forms on the fly to create new resources. Just not sure when to return it?

Possible options could be:

  1. return it as a link to just another relationship under _schema (like _self)
  2. return it on OPTIONS (not convinced though as OPTIONS is not cacheable and supposed to be used only for proxies and cors type of discoveries)
  3. return full schema of resource whenever it is anticipated that user may create a new resource (but it may increase the payload and not every time user may want to create)
  4. return it if the GET request is coming with a custom header looking for schema.
  5. any other smart option that you can come up with :)
Solution

  • The JSON Schema documentation includes two recommendations for correlating documents with schemas.

    The first and most popular is to use the profile Content-Type header attribute.

    Content-Type: application/my-media-type+json; profile="http://example.com/my-hyper-schema#"

    The other recommendation (that I have never actually seen anyone use) is a Link header with rel=describedBy.

    Link: <http://example.com/my-hyper-schema#>; rel="describedBy"

    Reference: http://json-schema.org/latest/json-schema-core.html#anchor33