RE: hydra:expects and hydra:returns

Hi Kuno

On Sunday, November 03, 2013 6:07 PM, Kuno Woudt wrote:
> I'm trying to understand hydra:expects and hydra:returns,
> some help would be appreciated :)
> 
> Let's say I have a database of information about music videos.
> 
> I can use a musicbrainz identifier to refer to a particular music
> video, as they already capture links to e.g. youtube and keep track of
> whether a particular recording is just an audio stream or is audio +
> video.
> 
> MusicBrainz is only interested in the audio part, so my hypothetical
> database is intended to capture things about the video part, e.g. the
> director of the music video.
> 
> A document at https://example.com/musicvideos/murio.jsonld contains
> something like:
> 
> {
>      "@context": "https://example.com/context.json"
>      "@id": "mbrec:95dd147c-71ba-48b1-91f3-0bf2916e9ec4#_",
>      "@type": "mo:Signal",
>      "foaf:isPrimaryTopicOf": [
>          { "@id": "mbrec:95dd147c-71ba-48b1-91f3-0bf2916e9ec4" },
>          { "@id": "https://example.com/musicvideos/murio.jsonld" }
>      ],
>      "dbpedia:Director": {
>          "foaf:name": "Ray Cuts",
>          "sioct:microblog": { "@id": "https://twitter.com/RayCuts" }
>      }
> }

I wouldn't model things like this. In the context of Hydra we are talking
about Linked Data applications and thus
https://example.com/musicvideos/murio.jsonld should be the "primary"
resource in the representation above. You could then say that murio.jsonld's
foaf:primaryTopic is mbrec:95dd... which is a mo:Signal


> Requesting the collection of data about music videos returns a link to
> that document:
> 
> {
>      "@context": "https://example.com/context.json"
>      "@id": "https://example.com/musicvideos/",
>      "hydra:members": [
>          {
>              "@id": "https://example.com/musicvideos/murio.jsonld",
>              "@type": "ex:MusicVideo"
>          }
>      ]
> }
> 
> So, if I understand correctly ex:MusicVideo in this case describes the
> actions I can perform on that resource:

Exactly. In the representation above there's nothing else that could
describe the actions (hydra:members doesn't have any defined).


> ex:MusicVideo a hydra:Class ;
>     hydra:supportedOperations [
>          hydra:method "GET" ;
>          hydra:statusCodes [ hydra:statusCode 200 ]
>          hydra:returns ...
>     ] .
> 
> It isn't entirely clear to me what hydra:returns is supposed to be in
> this case.  It would perhaps be mo:Signal if that request returned an
> .mp4 video file containing the music video, but this returns a
> document about the music video, not the music video itself.

It should give the client an idea what it can expect to get back. This is
related to the modeling of murio.jsonld. I don't know what ex:MusicVideo
actually represents (I assume an entry in your DB) but I would say that's
probably what you want to use for hydra:returns here.


> I see in the demo issue tracker that the hydra:returns for a GET
> request is often the same as the class on which the GET request is a
> supported operation.  So perhaps hydra:returns should be ex:MusicVideo
> here.

I think so, yeah.


> If so, is there a way to express that an ex:MusicVideo resource always
> returns information about a mo:Signal?

That entirely depends on how you model ex:MusicVideo. You could, e.g., say
that ex:MusicVideo has a property which links to a mo:Signal. Something like
this:

{
  "@context": ...
  "@id": "ex:MusicVideo",
  "@type": "Class",
  "supportedProperties": [
    {
      "property": {
        "@id": "ex:video",
        "domain": "ex:MusicVideo",
        "range": "mo:Signal"
      }
    }
  ]
}

Obviously you could also use one of the properties defined by the Music
Ontology instead of ex:video.


> Similarly, can I express that a PUT or POST request expects information
> about a mo:Signal?

Yeah, the idea is the same. You introduce an intermediary concept which then
links to a mo:Signal, i.e., the mp4 file.



--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 5 November 2013 14:30:23 UTC