hydra:expects and hydra:returns

Hello,

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" }
     }
}

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:

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.

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.

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

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

-- Kuno.


ps. context.json:

{
     "dbpedia": "http://dbpedia.org/,
     "ex": "https://example.com/vocab#",
     "foaf": "http://xmlns.com/foaf/0.1/",
     "hydra": "http://purl.org/hydra/core#",
     "mbrec": "http://musicbrainz.org/recording/",
     "mo": "http://purl.org/ontology/mo/"
}

Received on Sunday, 3 November 2013 17:07:14 UTC