RE: variable representations edited for spec

Hi Ruben,

On 30 Dez 2014 at 09:24, Ruben Verborgh wrote:
> 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.

I really like this summary (and fully agree with it). Maybe we should put it
somewhere.. at least in the Wiki for the time being till we find a better
place.


>>> 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 (*, ?, .).

Well, nothing prevents you from introducing another representation without
that "extension point". What I meant was that knowing that

  - BasicRepresentation is a VariableRepresentation
  - ExplicitRepresentation is a VariableRepresentation
  - *all* values of variableRepresentation are VariableRepresenations

doesn't change much in practice. How would you leverage that knowledge?
About the only thing I can think of is to query for VariableRepresentation.
Is that a compelling use case? Maybe... but much more interesting would be
to know how to use those (newly found) representation formats. We can't
describe that at the moment. Thus I see limited value in introducing such a
superclass and a range.


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

Are you really able "to interpret *how* it can be used"? All it tells you is
one property it can be used with (indirectly, nothing stops you from using
it with other properties as well unless it's explicitly ruled out).


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

I'm sorry but I still don't see how this changes anything. Nothing forbids
minting a URL, assign it some meaning and use it as value of
hydra:variableRepresentation. You have to be aware though that more than
likely no Hydra client will be able to make use of it since it hasn't been
programmed to serialize values according to that representation format. The
best it can thus do is to fail with a clear error message what went wrong.


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

Hmm... I'm not sure you need a separate representation format for that. My
gut feeling is that defining a datatype that defines the query syntax would
be the better choice in such a case. You can then serialize it either
including the datatype (ExplicitRepresentation) or without
(BasicRepresentation).

Apart from that, I do see some value in allowing different serializations
within a single IRI template... I'm just *a bit* worried about the
complexity and variability we introduce by that. Sure it might be able to
save a couple of characters in the resulting IRI, but that's about it. It
neither simplifies serialization nor deserialization. In any case, I removed
variableRepresentation's domain to not prevent this in the future.

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

Another way to implement that would be to provide two IRI templates: one
with subject, predicate and object variables and the other one with just the
freetext variable.. but of course you can't combine them in that case.


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

I could be convinced that this is useful but at the moment I'm still a bit
worried about the increased complexity.


> The domain of this property would then be the union of mapping and
template.

Which tells you what? :-P


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

I expected that :-)


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

Machines can make suggestions based on that information but you are right
that it takes something (someone) smarter to make the decision in the end.
On the other hand, whether I have

   hydra:variableRepresentation rdfs:domain hydra:IriTemplate

   _:x hydra:variableRepresentation hydra:BasicRepresentation
   ...

or

   _:x rdf:type hydra:IriTemplate
   _:x hydra:variableRepresentation hydra:BasicRepresentation
   ...

tells me (and a machine) exactly the same. The only difference is that the
author needs to be more explicit. The clear advantage is that it gives us
the flexibility to reuse hydra:variableRepresentation on things other than
IRI templates in the future.


> We should really remember that the Core Vocabulary is for machines,
> and machines currently need explicit instruction.

Right. The question here is how we provide those instructions to machines.
Do we want authors to be explicit or do we want to depend on reasoning by
making the vocabulary more explicit and rigid? I lean towards the former
because I expect that a lot of the things we define now could be cleanly
reused for other things in the future.


> It costs us not significantly more to get the modeling right,
> but it enables much more intelligent clients.

IMHO this has nothing to do with right or wrong modeling. The end result is
exactly the same.


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

Hmm.. I don't think that will happen.. and if it does, it's quite trivial to
address it.


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

I think this needs much more explanation anyway and it will be better to
explain this in the context of collections than IRI templates.


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

I don't think a freetextQuery is a representation format as outlined above.
Please start a separate thread, if you think that needs more discussion.


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

Good catch, thanks


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

Yep. I'm going to merge this now. Thanks again for taking the lead on this.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 30 December 2014 15:05:34 UTC