Re: variable representations edited for spec

Hi Markus,

Before I answer the points below, first a general remark
that can help the decision process of other points like these.

For me, the added value of Hydra, and the Core Vocabulary,
is that it, for the first time in the Web API domain,
recognizes how limited machines currently are.
All information they need to process a request is spoon-fed,
they are given explicit instruction about what to do.
Hydra allows to build APIs from the bottom up
through small pieces that machines do understand,
and everything works because we are explicit.

>> 1. Should hydra:BasicRepresentation and hydra:ExplicitRepresentation
>>    have a superclass hydra:VariableRepresentation?
>>    This would allow to set a specific range
>>    on the hydra:variableRepresentation property.
> 
> I don't think that's necessary at this point. It doesn't add any concrete value IMO

It adds value by providing an extension point.
I already have a use case in mind
where I will need another representation that is not covered:
free-text searches with specific control characters (*, ?, …).

This case is likely too specific to put into the Core Vocabulary,
but by defining a hydra:VariableRepresentation,
I can explicitly tell a machine that this thing is a variable representation
and it is thus able to interpret how it can be used
(cfr. my remark about explicitness above).

> and thus I'd rather like to keep the vocabulary as small as
> possible instead of adding such helper classes for the sake of modeling it.

So it would not be “for the sake of modeling”;
rather, to allow extension and to help machines through explicitness.

>> 2. Currently, hydra:variableRepresentation's domain is hydra:IriTemplate.
>>    Just to ensure that this is not an oversight, do we want to:
>>    - Have this only on hydra:IriTemplate?
>>      Then all variables of the template have the same representation
>>      type.
> 
> AFAICT, that was the plan.
> 
>>   - Have this only on hydra:IriTemplateMapping? Then variables
>>      of the template can have different representation types.
>>  - Allow both of the above. Then variables of the template can have
>>      different representation types, but we can also easily make them
>>      all the same.
> 
> If we have a compelling use case, we could decide to do so.

My use case would be extensions of triple pattern fragments.
The current interface is
    ?subject / ?predicate / ?object
where all of these 3 are hydra:ExplicitRepresentation.

However, let's extend the interface with a structured free-text field:
    ?subject / ?predicate / ?object / ?freeText
where the ?freeText field allows control characters (*, ?, …).
Then the first 3 are hydra:ExplicitRepresentation,
and the 4th is ex:FreeTextWithControlChars.

It's not about this use case per se (even though I will implement it),
but also to show that such use cases are actually quite common.

Therefore, I would propose that adding a representation to a mapping
if actually the default—and that adding it to an entire template is a shortcut.
The domain of this property would then be the union of mapping and template.

> I'm less and
> less a fan of using rdfs:domain/range as it prevents us from doing such
> things in the future. What about switching to schema.org's
> domainIncludes/rangeIncludes instead? I find that much more flexible.

Given my remark above, I have a very strong opinion about this: no.
domainIncludes and rangeIncludes are meaningless for machines;
there is literally nothing they can derive from this information.
Only humans might be able to do something with this;
but they already have the spec and natural-language documentation.

We should really remember that the Core Vocabulary is for machines,
and machines currently need explicit instruction.
It costs us not significantly more to get the modeling right,
but it enables much more intelligent clients.

>> 3. Section 5.2 of the document ("Templated Links") has now become large.
>>    I was tempted to subsection this, but that would not be in line
>>    with the rest of the document's structure.
>>    Given a rewrite for the entire document is pending, I did not act yet.
> 
> I edited it slightly and removed the second example as it differed only in
> the property used.

I separated those examples on purpose,
because the first example you give is already a special one: hydra:freeTextQuery.
This could lead people to think that hydra:property always expects a hydra:* value,
and they would have trouble connecting Hydra to their application domain.

The purpose of the second example was to introduce hydra:freetextQuery,
as the commit explains: https://github.com/HydraCG/Specifications/commit/492982f2.

So if you remove something, I strongly recommend to remove hydra:freetextQuery.
By the way, given the resolution for hydra:VariableRepresentation,
I wonder whether "freetextQuery" could not be a variable representation instead
(but then there's still the issue of searching over one or multiple fields).

> Please have a look at my changes (I fear the diff won't
> be very helpful) and let me know your opinion. I'll then go ahead, squash
> the commits and merge the edits into the master branch.

Other than the example, I fully agree with your changes.
Just made one edit for consistency.

When a restructuring of the spec happens (as discussed some time ago),
this section really needs subsections though.

Best,

Ruben

Received on Tuesday, 30 December 2014 08:25:25 UTC