Re: profile link relation

On Mon, Aug 26, 2013 at 5:29 PM, Markus Lanthaler
<markus.lanthaler@gmx.net>wrote:

> 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.
>

Ok, you convinced me :)


>
>
> > 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]).
>


That helped, thanks! Do you have localized any resource about this critics
you mention? What you say makes sense to me but I would like to see the
full argumentation.


-- 
Arnau Siches
@arnau_siches