RE: In-place hydra:Link

On 7 Okt 2014 at 09:27, tomasz@t-code.pl wrote:
> October 7 2014 9:16 AM, "Dietrich Schulten" wrote:
>> Hi,
>> 
>> is it possible to express that an attribute is a hydra:Link inside a
>> json object, without external context, either by saying so near a
>> jsonld IRI like this:

I think we should first clarify what a context is and what a (vocabulary) definition is. A JSON-LD context defines a mapping from meaningless string tokens (we call them terms) such as JSON property names to IRIs. The context may also be used to language tag string values or to type them. A vocabulary definition describes the IRIs (resources) that are used within a JSON-LD document or context. To make this a bit more concrete, a context that maps the term "comments" to "http://api.example.com/vocab#comment" would look as follows:

  {
    "@context": {
        "comments": "http://api.example.com/vocab#comment"
    }
  }

This tells a client only what the IRI corresponding to the "comments" property in the following document is:

  {
    "@context": ...
    "comments": [
        { "@id": "/comments/1", "title": "A comment" }
    ]
  }

But if the client doesn't understand that IRI (http://api.example.com/vocab#comment) yet, it has too little information to process it. Thus, you describe it in a machine-processable manner. Following Linked Data principles (use deferenceable URLs to name things), you would put that description in the document at http://api.example.com/vocab:

  {
    "@context": "http://www.w3.org/ns/hydra/core",
    "@id": "http://api.example.com/vocab#comment",
    "@type": "hydra:Link",
    ...
  }

Now, a client that doesn't understand the IRI is able to look it up (since it is actually a URL). If it did so, it would find out that this IRI/URL represent a hydra:Link. So, the client would know that "comments" is actually a link.

As Tom already said, using this "methodology", you would have to dereference each IRI you encounter without knowing beforehand whether it is worth it. Thus, in most cases it is beneficial to define an ApiDocumentation (a single document) which describe those things and requires just a single HTTP request.



>> {
>> "@context" : {
>> "@vocab" : "http://schema.org",
>> }
>> "@type": "Event",
>> "name": "Walk off the Earth - REVO tour",
>> "offers" : {
>> "@id": "http://api.example.com/event/123/offers",
>> "?": <-- say that this is to be dereferenced as hydra:Link

Almost. You could use hydra:Resource in this case to achieve what you want. A hydra:Link is simply a property, whose value is a hydra:Resource, i.e., a dereferenceable Web resource. If you would like to define the "offers" property itself, you would have to do that separately as Tom outlines further down. But in this case, it isn't necessary IMO.


>> }
>> }
>> 
>> Or maybe in the context?
>> 
>> {
>> "@context" : {
>> "@vocab" : "http://schema.org",
>> "offers" : "?" <-- say that the value of offers is a hydra:Link
>> }

No, not in the context. The context just describes mappings. It doesn't define concepts (IRIs/resources -> vocabularies) .



> I don't think either can be done. Though you could include the representation of offers
> property next to the resource itself. Though this would be something non-standard to do.
> 
> [
>   {
>     "@context": { },
>     "@type": "Event",
>     "offers": "..."
>   },
>   {
>     "@id:": "offers",
>     "@type": "hydra:Link"
>   }
> ]

Yep, that's fine.. but please keep in mind that the context from in the first object doesn't apply to the second object... you would have to repeat it or structure your document slightly differently:

  {
     "@context": ...
     "@graph": [
       { ... },
       { ... }
     ]
  }


> This way your client could look at the retrieved document for link descriptions 
> before trying to dereference them or the ApiDocumentation (as I described in
> me earlier mail).

Right. The only "problem" is that you "leak" the information that "schema.org/offer" is a hydra:Link to the public and don't restrict it to the scope of your API (an ApiDocumentation limits the scope to the API itself).


> However that's not something a generic client would do. In fact I would
> expect generic client to be confused if they got such a document in response.

No, I don't think so. The problem is that if you would import such a document into your knowledge base (e.g. a triple store) you would "infect" everything that uses schema.org/offers. All the data, even if it came from a different API in which it wasn't a link, would then be interpreted as a link. Thus it is better to either use an ApiDocumentation to avoid that or to use hydra:Resource as outlined above instead.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 7 October 2014 08:39:40 UTC