Add "target" to JSON Schema spec

[phili...@gmail.com]

We currently need to express the relation of links to its resource in some way and would like to recommend using a target field to do this. Let's say we have the following data:

{

  "schema": {

   "links": [

      {

        "href": "/users/1",

        "rel": "self",

        "method": "GET",

        "target": "_self"

      },

      {

        "href": "/users/1",

        "rel": "update",

        "method": "PUT",

        "target": "_self"

      },

      {

        "href": "/users/17",

        "rel": "friend",

        "method": "GET",

        "target": "_blank"

      },

      {

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

        "rel": "kill",

        "method": "POST",

        "target": "_parent"

      }

    ]

  }

}

Lets say you have an Angular app consuming data from a REST API with the link structure above. A "target": "_self" means that the following response is effectively a new data set for the current data. Examples for this are of course "rel": "self" or "rel": "update". For a collection it could be "rel": "next", "rel": "prev", etc. It means you can assign the new data from the response to the current data. "target": "_self" is the default behavior.

Example: You have a user, do an update with PUT and assign the response data to old object. The client API could look like this, if you create some helper objects not much different to frameworks like Restangular:

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

  $user === $updatedUser; // true

  // the $user object is smart enough to update itself with the new response

});

If you want a completely different object you would use "target": "_blank".

Example: We want the best friend from our user. With our client framework from above this could look like:

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

  $user === $friend; // false

  // the $friend object is a completely new object

});

If you want to express that some link affects your data you would use "target": "_parent".

Example: We want to kill our user. We don't want to DELETE the user completely from the data base, we just want to express that the user is dead. Maybe we change some field isAlive from true to false. Maybe this field is normally read-only, because it is such a invasive action so we can't update the field with PUT. But we don't get the user itself as a response after killing him, maybe we just get some success message. But we know that after we kill the user with these specific link that the user data has changed in some way, so we could call the self link in him. It could look like:

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

  $user === $updatedUser; // true

  // the $user object is smart enough to update itself manually via calling its self link after a kill

});