Can we add "target" to JSON Hyper Schema?

[Donald Pipowitch]

Hi,

we want to express the relationship between links to our current schema. That's why we would like to introduce "target" as the official way to do that - analogous to the same attribute in <a>.

Let's say we have the following data:

{

  "schema": {

    "links": [

      {

        "rel": "self",

        "href": "users/1",

        "method": "GET",

        "target": "_self",

        "targetSchema": { /* the user itself */ }

      },

      {

        "rel": "update",

        "href": "users/1",

        "method": "PUT",

        "target": "_self",

        "schema": { /* the writeable properties of user */ },

        "targetSchema": { /* the user itself */ }

      },

      {

        "rel": "car",

        "href": "cars/17",

        "method": "GET",

        "target": "_blank",

        "targetSchema": { /* some car */ }

      },

      {

        "rel": "kill",

        "href": "users/1/kill",

        "method": "POST",

        "target": "_parent",

        "targetSchema": { /* some arbitrary data... maybe just a success message */ }

      }

    ]

  }

}

And let's say we use a nice JavaScript framework similar to Restangular:

$user.self();  // GET users/1

$user.update(data);  // PUT users/1

$user.car();  // GET cars/17

$user.kill();  // POST users/1/kill

Note: With "rel": "kill" we don't want to remove (aka DELETE) the user, but maybe set some isAlive field from true to false. Let's say this isAlive field is read-only for "rel": "update", because it is a irreversible action and we have some special server-side logic to do this. So a normal PUT isn't an option.

Thanks to "target" we know that

• with "_self" we can update our data object in-place, because the response is the "same" resource as before
  
• with "_blank" we return a completely new data object, because the response is a  completely different resource
  
• with "_parent" we manually reload the data object (with its self link), because this link affects our resource in some way
  

Or to say it in code:

$user.update(data).then(function($updatedUser) {

  $user === $updatedUser; // true

});

$user.car().then(function($car) {

  $user === $car; // false

});

$user.kill().then(function($killedUser) {

  $user === $killedUser; // true, because $user automatically calls and returns $user.self() on $user.kill() internally

});

[Austin Wright]

This seems to introduce (meta)data that doesn't exist at this level of abstraction.

Hyper-schema is making assertions about the relationship of resources to other resources. E.g. the author of the current document, or an HTML form that can edit the document.

It doesn't make sense to say method=PUT to any of these relationships, because that's HTTP operating on a single resource. A PUT or a GET operation doesn't make a relationship between two resources like a link does.

HTML forms do allow you to specify methods, but they're not making links - they're literally instructions on how your client can construct its own PUT, POST, or GET request.

The "target" attribute in HTML links is presentation detail. An <img/> element is also a link, with different presentation semantics ("embed the resource instead of referencing it"). There's really no way to add this to JSON Schema without turning it into something resembling HTML, I think.

Also note that the values for "rel" are well defined, and a registry of valid values is maintained by the IANA at <http://www.iana.org/assignments/link-relations/link-relations.xhtml>. You can't invent your own keywords, but you can use a URI: {"rel":"http://example.com/drives", "href":"{+car}"}

Are you trying to make a kind of HTML form that applications can run? That's sort of a level of hypermedia that JSON Schema doesn't really support. Though you could link to an HTML form with an rel="edit-form" or rel="create-form" relation, and link to an HTML form or similar standard form format.

Austin.

[Donald Pipowitch]

Hi,

sorry for the late response. We use JSON Hyper-Schema in a similar way like HAL behaves. You know like HAL has a _links object in every resource, we have a JSON Hyper-Schema in every resource. It would be very nice for our API, if we could say how links relate to our current resource. E.g. a GET to self-Link would return the same resource, while a different link could return a new resource.

[Donald Pipowitch]

It's a little bit like the transclude attribute in UBER with its true and false values. Taken from http://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html#_reserved_strings:

Reserved strings for the transclude property
true : embed the results of the request into the current document
false : treat the associated url value as a navigation to a new document. [DEFAULT]

However our defaults are the other way around as in <a>'s target with _self as a default value which behaves similar to transclude: true.