AW: Re: Getting around in Event API Demo

Hi John,



---- John Walker schrieb ----

> Hi Dietrich, 
> 
>   
> 
> Some comments on the RDF side of things inline. 
> 
>   
> 
> John 
> 
>   
> 
> 
> > On October 7, 2014 at 9:03 AM Dietrich Schulten <ds@escalon.de> wrote: 
> >  
> >  
> > -----BEGIN PGP SIGNED MESSAGE----- 
> > Hash: SHA1 
> >  
> > Hi, 
> >  
> > I'm toying with the event API demo 
> > http://bit.ly/hydra-console-event-api. I want to share a few 
> > observations and ideas, backed by my experience with designing ReST APIs. 
> > Disclaimer: I have some basic knowledge about rdfs, but my ideas 
> > simply might not work as linked data. 
> >  
> > The meat of the event-api is at 
> > http://www.markus-lanthaler.com/hydra/event-api/vocab. 
> > Observation: the vocab is quite lengthy for a simple use case. 241 
> > LOC, much of it seems repetitive. 
> >  
> > We are talking about a pretty standard situation: you can POST, PUT 
> > and DELETE to the /events resource. If you POST or PUT, your request 
> > should contain an object that has attributes as defined by 
> > http://schema.org/Event. Only some of them are required, most are not 
> > supported. 
> > 
> 
>   
> 
> Your /events page would be a hydra:Collection of schema:Event 'instances'. 
> 
> As such you would presumably only allow GET and POST methods on the collection. 
> 
> PUT and DELETE would be more suited for use on the schema:Event instances. 
> 
> 
> > My general feeling is: it should not be necessary to maintain such a 
> > large description. Somehow we must leverage convention over 
> > configuration and the existing vocabs in such a way that I only need 
> > to define things I cannot take for granted. And we must be more DRY. 
> >  
> > I want to keep my context short so I can embed it. With Javascript 
> > clients in mind, I'd rather have everything in the resource that is 
> > needed to work with it. 
> >  
> > In the following I want to discuss the EntryPoint, the EventCollection 
> > and the Event. 
> >  
> > - ------------------------ 
> >  
> > In my ideal world this could be the EntryPoint: 
> >  
> > { 
> > "@context": { 
> > "@vocab" : "http://schema.org", 
> > "hydra" : "http://www.w3.org/ns/hydra/core#" 
> > }, 
> > "@id": "http://www.markus-lanthaler.com/hydra/event-api/", 
> > "@type": "hydra:EntryPoint", 
> > "event": { 
> > "@id": "http://www.markus-lanthaler.com/hydra/event-api/events/", 
> > "@type": "hydra:Link" 
> > } 
> > } 
> > (I prefer full urls because they work in stock rest clients.) 
> >  
> > Short, no external context, no site-specific vocab. 
> > The question is, is this valid from a Linked Data point of view? 
> > 
> 
>   
> 
> Here you are saying the resource http://www.markus-lanthaler.com/hydra/event-api/events/ has rdf:type hydra:Link, which does not seem correct. 

Yes, it seems I cannot put hydra:Link into the json, it belongs into a site-specific vocab or ApiDocumentation. 

> 
> I would expect that resource to have rdf:type hydra:Collection instead. 
> 
> 
> > Note that the event property is now http://schema.org/event, no longer 
> > EventCollection. 
> > 
> 
>   
> 
> By doing this I would expect the thing you link to with schema:event is a schema:Event, but seems that you link to a hydra:Collection of events. 

I mean to link to a multitude of events since that seems a possible value for schema:event. My idea was that the server is free to present the events as a hydra:Collection or a hydra:PagedCollection, e.g. to make them searchable, or to add other links to the collection as needed.

After all, the response does contain a list of events, only decorated by some additional affordances.

If the response were an html page, the only requirement would be that it contains schema:Event instances which are annotated to be recognizable as such.

My general idea so far is: a vocabulary is about the meaning of things, not (necessarily) about strong types. In that sense a hydra:Collection might be a list of schema:Event at the same time.

Is a link to a json of type hydra:Collection which somewhere inside contains an array of schema:Event a possible value for schema:event?

> 
> 
> > First of all, http://schema.org/event appears on Place, Organization 
> > and a number of Actions. In RDF, are we free to use schema:event on an 
> > EntryPoint? Can I state 
> >  
> > "schema:event rdfs:domain hydra:EntryPoint" 
> >  
> > somewhere in my context to allow this usage? And do I have to, don't I 
> > say that already by using schema:event on a hydra:EntryPoint? In the 
> > json world no "static typing" exists that would prevent me from adding 
> > any attribute. 
> > 
> 
>   
> 
> This is not wrong per-se, but would entail that all resources this property is used on have rdf:type hydra:EntryPoint which does not seem correct. 
> 
> If you used the sematically weaker schema:domainIncludes property, it would be OK from an RDF perspective. 
> 
> However I'd have to question if/why you would want to link from an API entry point to an event, unless you have conferences about an API of course :) 
> 
> 
> > An alternative could be not to use hydra:EntryPoint, but Organization 
> > or Place as @type of the index resource. Now that I think of it, that 
> > also makes a lot of sense. Probably the owner of the events wants to 
> > tell something about himself on the index resource anyway. But the 
> > question remains: may we attach event to EntryPoint at all? 
> > 
> 
>   
> 
> Indeed linking direct from an Organization or Place to an associated Event make perfect sense. 
> 
> The idea here is to link the list/collection of all registered events to the EntryPoint, not a specific Event instance. 
> 
> 
> > Second: Assuming that we are allowed to use http://schema.org/event: 
> > Values of 
> > schema:event are expected to be of type Event, not of type @id. It 
> > would be easy to program clients so that they understand the 
> > difference and transparently resolve links for data. But does RDF 
> > allow that? Is it correct to use a link to events instead of embedding 
> > the events themselves? If not, can Hydra introduce such a convention? 
> > Or can I at least redefine 
> >  
> > "schema:event rdfs:range jsonld:@id" 
> >  
> > somewhere in my @context? 
> > 
> 
>   
> 
> Suggest to go re-read the JSON-LD spec as it seems you misinterpret how @id is used. 

Yes. Meanwhile I have learned that @id is not a type identifier, and saying @type:@id is just an idiom in *a term definition* to say that an attribute value should be interpreted as a link, not a proper type statement.

Thank you for the clarification.

Best regards,
Dietrich