JSON Schema enhanced OAuth

{
 "access_token": "SlAV32hkKG",
 "token_type": "Bearer",
 "refresh_token": "8xLOxBtZp8",
 "expires_in": 3600,
 "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

With this response alone, you do not know where it came from, and where it can be used in the next step. This actually stems from one of the weakness of JSON itself.

There are several attempts to mitigate it. One of them is an informational Internet Draft called JSON Schema.

http://tools.ietf.org/html/draft-zyp-json-schema-03

This is much more elaborate spec than HAL, but is obviously capable of converting the conventional JSON document to Hyper-Linked REST response. Specifically, of interest to us is the clause 6, Hyper Schema.

To denote hyperlinks, it proposes to insert a top level JSON object called “links” instead of “_links” in HAL. e.g.,

  "links": [
    {
        "rel":"userinfo", 
        "href":"/userinfo{?access_token}"
    }

Inserting it in the OAuth response, it will become:

{
  "links": [
    {
        "rel":"userinfo", 
        "href":"/userinfo{?access_token}"
    }
 "access_token": "SlAV32hkKG",
 "token_type": "Bearer",
 "refresh_token": "8xLOxBtZp8",
 "expires_in": 3600,
 "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

Since it was an OpenID Connect token endpoint response, the resource that the client was going to access with the access_token was primarily UserInfo endpoint, so I have denoted it like above, but if the protected resource in question was like photo service, then it could have been like:

{
  "links":[
    {
      "rel":"self", 
      "href":"/tokens?code=asdfasdf"
    }, 
    {
      "rel":"photo",
      "href": "https://photo.example.com/{?access_token,schema}"
    }
  ],
 "access_token": "SlAV32hkKG",
 "token_type": "Bearer",
 "refresh_token": "8xLOxBtZp8",
 "expires_in": 3600,
 "id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

It is a bit more verbose than HAL, but it has an advantage of having multiple instances of the same “rel”. The disadvantage obviously is that you have to sequentially process each item in the links array to find out the href of desired “rel”. In case of HAL, you had an ability to directly access that record. Is this flexibility of having multiple records of the same rel type? I do not know. I feel HAL is simpler, but YMMV.