RE: SupportedOperation fields - Example App vs Spec

Hi Paul,

Welcome on the list.

On Thursday, December 31, 2015 7:14 PM, Paul Sadauskas wrote: 
> I'm working on a hydra generator tool in Ruby, and as part of my

Cool! Is it already available somewhere?


> tests, I wanted to make sure it generated a comparable vocab as the
> one in the example app at http://www.markus-lanthaler.com/hydra/api-
> demo/.

Unfortunately, that isn't the best example anymore as I didn't have the time
to keep it up to date.


> Upon investigating the "supportedOperation" section, the example app's
> vocab looks like this:
> 
>     {
>       "@id": "vocab:User",
>       "@type": "hydra:Class",
>       "subClassOf": null,
>       "label": "User",
>       "description": "A User represents a person registered in the
system.",
>       "supportedOperation": [
>         {
>           "@id": "_:user_replace",
>           "@type": "hydra:Operation",
>           "method": "PUT",
>           "label": "Replaces an existing User entity",
>           "description": null,
>           "expects": "vocab:User",
>           "returns": "vocab:User",
>           "statusCodes": [
>             {
>               "code": 404,
>               "description": "If the User entity wasn't found."
>             }
>           ]
>         },
> 
> The part I had a question about is the "label" and "description"
> fields in the SupportedOperation. Comparing them to the "label" and
> "description" fields of the User resource itself, they seem to be
> switched. And when comparing it to the example given in the Hydra Spec
> (EXAMPLE 10 in http://www.hydra-cg.com/spec/latest/core/), I see that
> it uses "title", and no "label" or "description" at all.

In the example above, label and description are mapped to rdfs:label and
rdfs:comment. I think going forward, we should consistently use hydra:title
and hydra:description.


> Is the example app simply out-of-date with the spec?

Yep :-(


> Forgive my
> ignorance, as I'm still new to Hydra, JSONLD and RDF, but which of
> those is responsible for the "label" field?

As the vocabulary is a valid JSON-LD document as well, you can simply put it
in the HydraConsole and check by hovering it:

 
http://www.markus-lanthaler.com/hydra/console/?url=http://www.markus-lanthal
er.com/hydra/api-demo/vocab

It shows you that label is mapped to
http://www.w3.org/2000/01/rdf-schema#label (or short rdfs:lable).

Once we are done with the spec, we definitely have to write a good intro to
the technology stack. Here's the short version of the technology stack:

Vocabularies: Hydra / Schema.org / RDFS / ...
Serialization formats: JSON-LD / Turtle / RDFa / ...
Data model: RDF 

So, at the bottom you have a quite simple, graph-based data model (RDF).
There exists various serialization formats for that data model, JSON-LD is
one of them. The last thing you need to describe data are vocabularies.
Simply speaking, they are sets of URLs (IRIs to be more precise) with a
well-defined meaning.

So, to answer your question, "label" is a JSON-LD term that is mapped to a
concept of the RDFS vocabulary. It's official definition can be found at

  http://www.w3.org/TR/rdf-schema/#ch_label


> Perhaps my confusion is
> related to "ISSUE 8" in the spec, "Describe the various properties of
> an operation.", and once that happens, things will be clearer. Is this
> section still subject to much change, and I shouldn't worry about
> getting it to match either the spec or the example app exactly for
> now?	

After we finalize the filter design, we will move to operations. I do expect
that we'll make a few changes. So you actually join at the perfect time as
you can weigh in on the design decisions. I'd like to invite you to join the
Hydra W3C Community Group if you are interested. The steps to do so can be
found at

  http://www.hydra-cg.com/#community


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 5 January 2016 21:55:20 UTC