Re: Replace hydra:Error with application/problem+json

Hi Asbjørn,

+1 that we should attempt to integrate with problem+json as close as
possible. Let us think it through. These are the attributes we are
talking about:

"title" - A short, human-readable summary of the problem type.

"instance" - A URI reference that identifies the specific
      occurrence of the problem.

"status" - The HTTP status code ([RFC7231], Section 6)

"detail" - An human readable explanation specific to this
      occurrence of the problem.

"type" - A URI reference [RFC3986] that identifies the
      problem type [...] When this member is not
      present, its value is assumed to be "about:blank".

The 'title' seems an immediate match to hydra:title, nothing to do here.

If you agree that problem+json 'instance' best matches @id, your
suggestion would affect the existing properties hydra:statusCode and
hydra:description, and it would require to introduce a new property
hydra:type.

Renaming hydra:statusCode to hydra:status seems possible to me. Although
it would be incompatible to previous versions, such changes have been
made before.

Simply renaming hydra:description to hydra:detail is not quite as easy,
since Hydra uses it elsewhere. We would have to add hydra:detail, maybe
as a subtype of hydra:description, and make it a synonym of problem+json
detail. We would sacrifice reuse within Hydra for interoperability with
the web. I would be willing to do that, but that is just me.

Adding hydra:type would not seem ideal to me, I guess many people would
be confused and inadvertently use it like @type or mistake it for
content-type, although problem+json defines 'type' specifically as a URL
which identifies a particular class of problems and has a default value
of about:blank (!). So I would suggest to add hydra:problemType rather
than hydra:type.

As an alternative, we might ask the people behind problem+json, if they
are willing to rename 'type' to 'problemType'. Or, to turn things
around, if they are willing to describe their attributes in a micro
vocabulary, add that to the RFC and declare a rendering in full json-ld
an equivalent of a problem+json. Then the Hydra spec could simply refer
to it, and a service could return an application/ld+json error response
without

Since Erik Wilde is also in this list, I cc'ed him.
Erik, what do you think?

Best regards,
Dietrich

PS: At times the concept of media types and the concept of linked data
seem peacefully coexisting, at best. I'd rather see both concepts
converge. Or, as Manu Sporny put it, "The desire for better Web APIs is
what motivated the creation of JSON-LD, not the Semantic Web" [1]

[1] http://manu.sporny.org/2014/json-ld-origins-2/

Am 25.09.2015 um 09:47 schrieb Asbjørn Ulsberg:
> Yes, this is what I have in mind. But I think we should go even futher;
> use the exact same naming as in application/problem+json as well, since
> people reading these responses are much more likely to have seen
> application/problem+json responses before than responses decorated with
> Hydra. I think we should even rename hydra:Error to hydra:Problem to
> make the relationship explicit and unambiguous. That is: A hydra:Problem
> *is* application/problem+json and there should be no doubt about it,
> even though those reading the JSON on the wire have never heard about
> Hydra before.
> 
> -- 
> Asbjørn Ulsberg          -=|=-         asbjorn@ulsberg.no
> <mailto:asbjorn@ulsberg.no>
> «He's a loathsome offensive brute, yet I can't look away»
> 
> 
> On Wed, Sep 23, 2015 at 8:44 PM, Dietrich Schulten <ds@escalon.de
> <mailto:ds@escalon.de>> wrote:
> 
>     In my very first posting to the list I asked for a similar thing.
>     Essentially I asked to adopt the problem+json attribute semantics into
>     Hydra. I think the discussion is still open.
> 
>     Back then Markus answered [1]: "What would we need to redefine to
>     achieve that? Please also have a look at
>     ISSUE-27 [2] and ISSUE-39 [3]."
> 
>     [1] https://lists.w3.org/Archives/Public/public-hydra/2014Oct/0065.html
> 
>     Markus also noted that one could easily contextualize the json
>     attributes of problem+json and map them to Hydra, saying that 'status'
>     is hydra:statusCode, 'title' is hydra:title, 'detail' is
>     hydra:description and 'instance' could be @id. Still lacks 'type',
>     which
>     also has valuable semantics.
> 
>     The advantage of adopting problem+json would be that problem+json is
>     richer and more precise, and if things work out well, more widely
>     understood. It makes a clear distinction what does and does not belong
>     into the response, and what exactly the error response is for.
>     As it stands now, hydra:Error does not come with such a clarification.
>     People might be tempted to define new status codes just for their
>     API or
>     redefine existing ones, which I would consider an abuse.
> 
>     Proposal:
>     - define all problem+json attributes in Hydra (i.e. add 'type')
>     - publish a json-ld context 'problem.jsonld' which maps problem+json
>     attributes to Hydra
>     - say in the spec that the semantics of the hydra attributes is an
>     exact
>     match to the problem+json attributes and that hydra:Error should be
>     used
>     to explain possible solutions, not to overload existing or define
>     API-specific status codes
>     - explain the use of the problem.jsonld context
> 
>     If we would adopt the problem+json semantics into hydra by publishing a
>     problem.jsonld error context file, one could respond:
> 
>     HTTP/1.1 403 Forbidden
>     Content-Type: application/problem+json
>     Link: <http://www.w3.org/ns/hydra/contexts/problem.jsonld>;
>     rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
>     Content-Language: en
> 
>     {
>     "type": "http://example.com/probs/out-of-credit",
>     "title": "You do not have enough credit.",
>     "status": 403,
>     "detail": "Your current balance is 30, but that costs 50.",
>     "instance": "http://example.net/account/12345/msgs/abc"
>     }
> 
>     Where http://www.w3.org/ns/hydra/core/problem.jsonld dereferences to
>     our
>     published error context file:
> 
>     @context": {
>     "@vocab" : "http://www.w3.org/ns/hydra/core#",
>     "type": "errorType" <-- yet to be defined in Hydra,
>     "status": "statusCode",
>     "detail": "description",
>     "instance": "@id" <-- see ISSUE-27/ISSUE-39
>     }
> 
>     If an api decides to use custom attributes:
> 
>     HTTP/1.1 403 Forbidden
>     Content-Type: application/problem+json
>     Link: <http://api.example.com/example.problem.jsonld>;
>     rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"
>     Content-Language: en
> 
>     {
>     "type": "http://example.com/probs/out-of-credit",
>     "title": "You do not have enough credit.",
>     "status": 403,
>     "detail": "Your current balance is 30, but that costs 50.",
>     "instance": "http://example.net/account/12345/msgs/abc",
>     "balance": 30,
>     "accounts": ["http://example.net/account/12345",
>     "http://example.net/account/67890"]
>     }
> 
> 
>     Where http://api.example.com/example.problem.jsonld dereferences to:
> 
>     "@context": [
>     "http://www.w3.org/ns/hydra/contexts/problem.jsonld",
>     {
>     "balance" : "http://api.example.com#balance",
>     "accounts" : "http://api.example.com#accounts"
>     }
>     ],
> 
> 
>     Both Hydra and non-Hydra clients could work with that. We would be good
>     web citizens if we promoted the use of commonly understand semantics.
> 
> 
>     Am 23.09.2015 um 08:56 schrieb Thomas Hoppe:
>     > Hi,
>     >
>     > nice idea but in the same way you could argue we should use JSON
>     > JSON-Home [1] as API-Documntation (hydra:ApiDocumentation).
> 
>     If it happened to fit, why not? I want to make my API understandable by
>     many clients.
> 
>     One might also argue, the fewer attributes hydra defines and the more
>     well-established semantics from the "world of the uniform interface" it
>     adopts, the better.
> 
>     E.g. why have hydra:nextPage if there is an IANA rel next
>     (urn:iana:link-relations:next)?
> 
>     Best regards,
>     Dietrich
> 
> 
>

Received on Saturday, 26 September 2015 11:15:59 UTC