Re: Relating hydra:Classes to hydra:IriTemplates

On Jun 15, 2014, at 10:51 AM, Jindřich Mynarz <mynarzjindrich@gmail.com> wrote:

> Hi,
> 
> in the interest of keeping distinct topics in separate threads, I'll continue with my questions about Hydra in another email.
> 
> Overall, I struggle to understand the connections between several parts of the Hydra Core Vocabulary. The "main" part of the vocabulary, including hydra:Class, hydra:SupportedProperty and hydra:Operation, is well-described and fits nicely most CRUD scenarios. However, I find it difficult to grasp how it's related with the part including hydra:TemplatedLink or hydra:IriTemplate, which seem to match more search-oriented scenarios.
> 
> I was thinking about describing a simple search API in Hydra. I started with a description of an API that allows to search for resources regardless of their type via free-text queries. I found out that Hydra allows to link to hydra:IriTemplate from hydra:ApiDocumentation via hydra:entrypoint: 
> 
> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:entrypoint :simple-search .
> 
> :simple-search a hydra:IriTemplate ;
>   hydra:template "/search{?q}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ;
>       hydra:variable "q" ;
>       hydra:property hydra:freetextQuery ;
>       hydra:required true
>     ] .
> 
> Is this description in line with how Hydra is intended to be used? Or is it a wrong interpretation of Hydra's spec?

I believe so, but this is certainly an under-specified part of the document. I also expect this to change.

If you consider that an IriTemplate describes a form for doing GET operations, the variable binding mechanism needs some work. In this case, it’s just describing text to be used for a free-text search, but in other cases it binds to properties. The question is, is the value space intended to be values of those properties in the entity within which it is defined? Or, could it be any value resource which could be a value of that property?

On his recent visit to SF, Markus and I discussed some ways in the the values to be defined to come from a collection, so you you could imagine having a field with the range of possible values for some variable coming from a referenced collection. For example, if a collection were defined to return the states in the United States, this collection could be used in a select control to identify one member of the collection to be used as the value of the variable to be substituted in the IRI Template.

> Then I thought how to describe a similar simple search but restricted to instances of a specified class. I assume this can be done via hydra:supportedClass. For example, if an API offers a search for instances schema:Person, then I presume schema:Person can be described as hydra:supportedClass: 
> 
> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:supportedClass schema:Person .
> 
> However, then I wondered if it's correct to reuse schema:Person directly and attach to it API-specific hydra:Operations. Is it better to define an API-specific subclass of the extended class, to which operations are attached? This seems to be a better approach, since the API likely doesn't support all instances of schema:Person, but only an API-specific subset of schema:Persons.
> 
> :simple-search-api a hydra:ApiDocumentation ;
>   hydra:supportedClass :SimpleSearchPerson .
> 
> :SimpleSearchPerson a hydra:Class ;
>   rdfs:subClassOf schema:Person .
> 
> Is this a recommended approach in Hydra how to reuse third-party vocabularies and extend them with local assertions?

So as to avoid unnecessary proliferation of  derived classes, I think it makes sense to use the base type (e.g., schema:Person). Note that the fact that schema:Person is defined to be a hydra:Class is an artifact of the API endpoint, and is not an assertion that should leak out as an open-world vocabulary definition. If the API documentation can be taken to be specific to the client, then assertions can be made within the API that might be in conflict with other open-world assertions (for example, the fact that schema:Person is a hydra:Class for the purposes if my API, but may not be for someone else’s).

> Now, what I don't understand is the preferred way of connecting hydra:search (or any hydra:TemplatedLink) to the supported Person class (or any hydra:Class). Can I use hydra:search directly with supported classes of the API, such as in the following example? 
> 
> :SimpleSearchPerson hydra:search :simple-search-person-template .
> 
> :simple-search-person-template a hydra:IriTemplate ;
>   hydra:template "/person{?name}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ;
>       hydra:variable "name" ;
>       hydra:property schema:name ;
>       hydra:required true
>     ] .
> 
> Or instead, is it necessary to attach :simple-search-person-template to :SimpleSearchPerson through hydra:supportedOperation? Relating hydra:Classes to hydra:IriTemplates is probably the part which is the most unclear to me. 

Yes, this is unclear (as I mentioned above). Does the fact that the variable is bound to schema:name imply that it MUST be the schema:name of some existing entity? Otherwise, what purpose does it serve?

If we instead described this as follows:

:simple-search-person-template a hydra:IriTemplate ;
  hydra:template "/person{?name}" ;
  hydra:mapping [
      a hydra:IriTemplateMapping ;
      hydra:variable "name" ;
      hydra:property schema:name ;
      hydra:required true;
      hydra:anyMemberOfCollection  </people/names>
    ] .

This might indicate that the value of the variable is any member from referenced collection. I could also imagine using something like owl:oneOf to enumerate a set of possible values for the variable.

Gregg

> Best,
> 
> Jindřich
> 
> -- 
> Jindřich Mynarz
> http://mynarz.net/#jindrich