Re: Moving forward with hydra:filter (ISSUE-45)

Hi Markus

>I think Ruben was simply a bit too enthusiastic as we were finally able to 
>solve an issue he raised more than half a year ago. Our (and basically any 
>standardization effort's) process is to first have a discussion. When there 
>seems to be consensus the chair sends out a Call for Consensus to give 
>people that didn't participate in the discussion that far a last chance to 
>raise their objections before an official decision is being made. This 
>process works quite well, so let's try to stick to it. If you have ideas on 
>how to improve the process, please let me know. I'm always open to change 
>things to the better.

Understood

>Could you please expand on what you mean by that? This is a IRI template so 
>all variables need to be replaced by the client/user input.

Well, first of all - not all variables needs to be replaced. Consider query 
string parameters - these are usually optional and if no suitable value is 
provided the query string parameter should be removed (this is doable 
easily). Other thing is when a variable sits in the path.
Anyway, my general understanding of the spec (which is somehow very raw and 
dry with good examples), is that each mapping tells value of which property 
should get into the template. Special cases like hydra:freetextQuery should 
cover situations where no source resource is available and direct user input 
should be taken. Consider an api:
GET /users - > returns a collection of users
GET /users/someUserName - returns a specific user with someUserName 
username - this would be invoked just be dereferencing a member's IRI taken 
from the previous call.
PUT /users/{?userName} - template telling client on haw to craft the URL - 
this operation has a very specific resource in context - the resource that 
is being sent back to the server after changes. I understood the mapping 
mechanism that it shows the client that it should take a hydra:property of 
that resource in context. That seemd logical to me :).
Correct me if I'm wrong. And if indeed I'm wrong I think the situation above 
gives a real life scenario to be considered!

>> The client is informed that the variables first and last will match on 
>> the
>> server side properties schema:givenName and schema:familyName 
>> respectively.
>No, the semantics would be to filter a collection of (presumably) 
>schema:Persons to just return the instances whose schema:givenName and 
>schema:familyName have specific values. In other words, it expresses the 
>following SPARQL query
>   SELECT ?member WHERE {
>     ?member schema:givenName <"first" value supplied by client> ;
>     ?member schema:familyName <"last" value supplied by client> .
>   }
Ok, maybe I was not precise, but this was exactly what I wanted to say.

>> But he doesn't know on where to take the values from to craft the url! In
>> case with hydra:search:
>>
>> </collection> hydra:search [
>>       hydra:template "/collection?search={?search}",
>>       hydra:mapping [ hydra:variable "search"; hydra:property
>> hydra:freetextQuery ]
>>     ]
>>
>> my understanding is that client should take a value from the user input.
>The same is true with hydra:filter. One thing that we need to clarify is 
>whether we always want those conditions to be combined by a logical AND or 
>whether we want to allow other >functions (OR, NOT) as well. This quickly 
>brings us into complex territory though.
Indeed. We should also consider whether these matches should exact or close 
to SQL's LIKE operator. What about typed values?

>> Taking this by analogy:
>>
>> </collection> my:customTemplatedLink [
>>       hydra:template "/container/{?name}",
>>       hydra:mapping [ hydra:variable "name"; hydra:property
>> schema:givenName ]
>>     ]
>>
>> name value that feeds the template is taken from the resource in context
>> (i.e. PUT operation that updates the resource) or other user input based
>> thingy.
>I don't understand what you mean by "resource in context". But it probably 
>also doesn't matter as my:customTemplatedLink could be defined to take the 
>value from anywhere.
See my first comment at the beginning. Still, my:customTemplatedLink doesn't 
define anything related to source of values in the template. I don't recall 
any piece of spec in hydra related to this topic.

>> Unless my understanding is incorrect, hydra:filter completely changes 
>> that
>> logic but puts disturbance in the force - client doesn't know how to feed
>> the template as the hydra:property doesn't point to the input but to the
>> server side behavior.
>No, I think you misunderstood this. We are not trying to parse components 
>of a URL here but try to tell the client how to construct URLs that enable 
>filtering of the collection the hydra:filter property is attached to.
Indeed - you tell the client that in a given Iri template each variable 
should be replaced with a value. I just though that the hydra:property 
points to the source of the value to be used as a replacement. If 
hydra:property tells the client how this variable matches the server side 
predicates this leaves a client without any clue on where to take the value 
from.

>> I'd make it a standalone predicate disconnected from the hydra:search or
>> present a new predicate applicable to the hydra:IriTemplateMapping, i.e.:
>> </collection> hydra:search [
>>       hydra:template "/collection?first={?first}&last={?last}",
>>       hydra:mapping [ hydra:variable "first"; hydra:property
>> hydra:freetextQuery; hydra:filterOnProperty schema:givenName ],
>>       hydra:mapping [ hydra:variable "last"; hydra:property
>> hydra:freetextQuery; hydra:filterOnProperty schema:familyName ],
>>     ]
>> This way you're consistent and fully express what you would like to 
>> express.
>I think what is being proposed expresses exactly the same but allows a 
>terser serialization. What you the proposal doesn't allow though, is what 
>you express as hydra:property hydra:freetextQuery. Namely, the description 
>of what values are acceptable etc. I guess we have to postpone that for now 
>and re-use what we will decide when we discuss hydra:Operation and 
>hydra:expects.
Well, hydra:freetextQuery is the only example related to IriTemplates in the 
spec thus it's my puppet in my examples.
As for the acceptable values - client can discover value's range if 
hydra:property is referenced by any of the expected class' supported 
properties.
The example above exactly tells on how to build a valid Iri - client knows 
how each variable is used by the server and how the values used as variable 
replacements should be obtained. I think that some more IriTemplate examples 
should be presented.

>>>> Additional clarifications:
>>>> – if a parameter value is empty, it is ignored (i.e., an empty value 
>>>> does
>>>> not mean the property needs to be empty)
>How will we be able to express that then?
I think it was Ruben's statement. As for empty variable values - if client 
cannot provide a value for a variable in query string, it should be removed. 
As for the path segment variables - some value needs to be provided. We do 
not have any hydra:nil, do we?

>>>> – if a filter contains multiple conditions, each of the result items
>>>> must match *all* of the conditions
>>>> Examples:
>>>> – /collection?first=Markus&last= returns a collection of items with
>>>> first name "Markus"
>>>> – /collection?first=Markus&last=Lanthaler returns a collection of items
>>>> with first name "Markus" and last name "Lanthaler". Items that only
>>>> meet one of these conditions are not returned.
>Are we sure that is all we need? How would we extend the model if we find 
>out later that we need more operators?
Ruben's statements as well. Indeed, as you already noticed we're entering a 
complex territory. Few quick ideas: AND, OR, NOT, LIKE. This is only the 
beginning.
I think we shouldn't expand it to deeply as we'll end up with a querying 
language, which I think we want to avoid, but few basic constructs will 
greatly improve Hydra usability.

Best

Karol

Received on Thursday, 29 October 2015 22:24:17 UTC