Re: AW: Re: Getting around in Event API Demo

Hi Dietrich,

> On October 8, 2014 at 10:45 AM Dietrich Schulten <ds@escalon.de> wrote:
> 
> 
>  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
>  > > <mailto: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.
> 

In principle there is nothing to stop you describing schema:event as having
rdf:type hydra:Link in the JSON-LD response.

{ "@id": "http://schema.org/event", "@type":
"http://www.w3.org/ns/hydra/core#Link" }

But seeing as you would need to include that same info in every response that
uses schema:event property, it would make sense to move it to the
vocab/documentation.

As you say DRY.

Another matter of principle is if one should go around redefining/extending the
meaning of terms that you do not 'own', or if you would define a sub-property of
schema:event with these extended semantics defined there. My gut feeling says
the latter is 'better', but seeing as Anyone can say Anything about Anything
(AAA) there's nothing to stop you from doing it the first way. It'd then be up
to the client to decide if they trust what you say and if they apply those
semantics just to your API or in general.

Would be interested to hear others' opinions on that.

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

In principle one should only use schema:event to link from a schema:Place or
schema:Organization to a (singular) schema:Event (i.e. not a collection/list of
events).

Suggest to take a look at
http://www.w3.org/community/hydra/wiki/Collection_Design

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