RE: profile link relation

On Monday, August 26, 2013 10:32 AM, Arnau Siches wrote:
> Alright, I was thinking all the time in using the 'profile' link
> to tag resources of the API. The spec is clear about that. My mistake.
>
> What I said was based in (quoting RFC6906):
>   As one example, consider the case of podcasts, where a specific kind
>   of feed uses additional fields for media-related metadata.  Using a
>   'profile' link, it would be easily possible for clients to understand
>   that a specific feed is supposed to be a podcast feed, and that it
>   may contain entries using podcast-specific fields.
> 
> Which, if I'm correct, overlaps with the `@context` intention. Is it?

Partially.. Profile gives *additional* hints to a client. It must not change the semantics of a representation, i.e., a client ignoring the profile (because it doesn't know it) must interpret the representation exactly the same way as a client understanding it. So the client understanding the profile just has some additional knowledge that it can use to, e.g., present a different UI for a podcast feed.

A JSON-LD context on the other hand may change the semantics of the data completely. Thus, a JSON-LD client must not ignore it.


> Just to make sure, the `apiDocumentation` link it's intended to be used
> primarily to discover the API (through its documentation) from the outside
> whereas the `@context` in each API resource is enough description/explanation
> to know how a field should be handled.

Yes, you can use the apiDocumentation link to discover an API (or its description if you've already discovered the API). JSON-LD's context maps "terms" (as we call them in the spec) to URIs to make them unambigous. Take the following JSON document:

{
  "@id": "/1",
  "ystävät": [ "/4", "/9" ]
}


Now, unless you are Finn, you probably have problems to interpret that data without out of band knowledge. Machines have exactly the same problems regardless the language we use. A solution is to pick an unambiguous identifier instead of just some natural language token. On the Web those identifiers are URIs (or IRIs if you want to allow some more characters). So by adding a context, we can make that data unambiguous for both machines and humans:

{
  "@context": {
    "ystävät": { "@id": "http://schema.org/knows", "@type": "@id" }
  }
  "@id": "/1",
  "ystävät": [ "/4", "/9" ]
}

This maps "ystävät" to http://schema.org/knows and specifies that its values are URIs. A context just allows you to keep writing idiomatic JSON while still getting all the advantages of using unambiguous identifiers. A JSON-LD processor would interpret the following document exactly the same way

{
  "@id": "/1",
  "http://schema.org/knows": [
    { "@id": "/4" },
    { "@id": "/9" }
  ]
}

Some people criticize JSON-LD for this because it increases the variability you have to expect in your client code. IMO that's not a very strong argument. It's far more important to optimize for humans than for machines. As a side effect, it often decouples clients and servers as it becomes apparent that programming directly against a specific JSON structure isn't such a great idea after all [1] (for those who prefer slides, [2]).


Hope this helps,
Markus


[1] http://m.lanthi.com/wsrest2013-paper
[2] http://bit.ly/wsrest2013-preso


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 26 August 2013 15:29:33 UTC