Open tpluscode opened 3 years ago
cc @pietercolpaert
Hi @tpluscode,
In the meantime I created the TREE specification which is an extension of Hydra’s Collection design to create search-tree-like hypermedia structures. A 1-dimensional pagination can also be seen as a very simple search tree, and thus the TREE specification also supports describing ordering in Hydra collection. It does not describe the ordering of the members in the page itself, it only qualifies a hydra:next
link into a tree:Relation
object that explains what the next link precisely means, which could be that all members may have a dcterms:created
that’s later in time.
Links:
And needless to say: I’m open to discuss how TREE can become an official Hydra extension!
Please, keep in mind that extensions should not create alternative reality compared to what's doable with raw hydra vocab. Whenever possible, hydra constructs should be provided and then an extension can be applied. I envision clients falling back to raw hydra descriptions in case the client does not understand an extension.
What do you call an "alternate reality"? The whole point of extensions is to provide information which is otherwise not possible with Core (and when we intend to keep it that way).
In the example of ordered collections, there could be multiple ways, so there could be multiple extensions varying in expressivity. What if a client does not understand a given description? Worst case they will display collection members in random order as they come from a parser 🤷♂️
Just please bare in mind that when hydra says it is a collection of users, don't make the extension say its a collection of cars. Extension should well, give an extended description of the collection. Providing sort order falls into this scheme.
The sentence beyond hydra just sounded side by side to hydra to me. If it is not the case - there won't be an issue
Just please bare in mind that when hydra says it is a collection of users, don't make the extension say its a collection of cars.
Please be serious 🤣
Where Hydra Core is not enough the extension would go "beyond" and add the additional details
It's just a matter of experience - I know you're keen to make shortcuts sometimes ;)
Please, keep in mind that extensions should not create alternative reality compared to what's doable with raw hydra vocab. Whenever possible, hydra constructs should be provided and then an extension can be applied. I envision clients falling back to raw hydra descriptions in case the client does not understand an extension.
In the TREE spec, this is exactly what we tried to do with this chapter on Hydra compatibility: https://treecg.github.io/specification/#hydra - Happy to hear your thoughts!
You would know best how to approach TREE from the other end. The least we could build is again a "best practices" document showing how to use TREE to augment Hydra APIs.
I’m thinking about 2 parts:
Instead of just saying next
, we will make this link an entity in itself describing a Relation to another node
I have two examples currently in the repo based on a hydra:Collection
Using a property path to indicate what the search form property is querying exactly
For (2), would you consider SHACL Paths?
I'm not sure I understand correctly - both of the examples @pietercolpaert are not providing any page relations in terms of hydra. Indeed there is some order description using tree
, but hydra powered client would only discover that there is a collection with some members.
There is an equivalence:
<view1> hydra:next <next> .
Is equivalent to:
<view1> tree:relation <rel1> .
<rel1> a tree:Relation ;
tree:node <next> .
So, you can also add hydra:next
if you also want hydra-core agents to follow the next page without having to understand the “qualified” relation that then would be ignored.
A TREE client MUST be able to interpret a hydra:next
though and handle it in the same way as the example above.
This is what I meant - an extension should add features unavailable in pure Hydra, but server should provide all available details in pure hydra and optionally via the extension. It would be undesirable to have details provided via an extension but without hydra equivalent constructs when available.
@alien-mcl Fully agreed! I propose always adding the hydra-core properties in this repo as well, when you want to use TREE as a Hydra extension. However, I also see TREE as an extension on top of for instance activity streams 2.0, Linked Data Platform and Triple Pattern Fragments (ok, this one also uses hydra). So I will not include the Hydra-core fallbacks in the TREE specification in each example though.
OK, my first thoughts were TREE is more rooted in hydra, but the only trace of it within the spec is IriTemplate used for tree:search. Having that in mind I'd go with separate extension that would introduce desired interoperability between hydra and TREE the same way as @tpluscode goes with SHACL.
Ok, I can certainly live with that. In TREE there is a compatibility section already on Hydra: https://treecg.github.io/specification/#hydra
@pietercolpaert finally looking again at a scenario where I want the information about collection order and I think that TREE solves a slightly different problem and another problem that is not really in need of addressing. Please, bare with me.
The latter is regarding tree:path
used in an IRI Template mapping. It's not really about sorting but I'm curious why you need a second property. I typically just rely on hydra:property
and that is exactly the property used to search the collection. It is also slightly irrelevant to the client in a pure REST API scenario but maybe I'm missing something
Now, regarding actually informing the client about collection sort, I have some thoughts.
First of all, this is not necessary limited to partial collections. Ie, the hydra:member
property is itself not an RDF List, thus also non-paged collection will benefit from an order annotation, allowing clients to sort the members
Second, related to the last part of above statement, my goal from the beginning was only to inform the client how to sort. the members of a collection (or page) in memory. Nothing less nothing more. Annotating the next/previous relation is slightly weird because it will inherently keep the same order.
Indicating order of a paged collection
Here's a concrete and complete example of what I have in mind: a paged collection of people sorted by
In SPARQL this would be
SELECT ?res {
?res foaf:birthday ?bd .
?res ex:birthPlace/rdfs:label ?loc .
?res foaf:givenName ?gn .
}
ORDER BY desc(?bd) ?loc ?gn
The client need the exact same information to perform an equivalent sort operation on hydra:members
of a partial collection view. I like the idea of attaching this information to the view itself. Thus, we'd have something like
</people>
hydra:member ... ;
hydra:view </people?page=10> .
</people?page=10>
a hydra:PartialCollectionView ;
hex:orderedBy (
[ hex:descending foaf:birthday ]
( ex:birthPlace rdfs:label )
foaf:givenName
) .
hex:orderedBy
is a list just as ORDER BY
clause is orderedhex:descending
propertyhex:descending
, a valid SHACL Path itselfIndicating order of a non-paged collation
A collection without pages would not typically have hydra:view
, I think. However, the server. might still want to communicate how to sort the collection members. I think we have two options.
My preference could be to require a view to have the model most similar to a paged collection. This is nice, because potentially multiple views could be offered with different possible ways to order that collection.
</people>
hydra:member [], [], [] ;
hydra:view </people#byLastName> .
</people#orderedByLastName>
a hex:OrderedCollectionView ;
rdfs:label "Ordered by last name" ;
hex:orderedBy ( foaf:lastName ) ;
] .
</people#orderedByBirthPlace>
a hex:OrderedCollectionView ;
rdfs:label "Ordered by place of birth" ;
hex:orderedBy ( ( ex:birthPlace rdfs:label ) ) ;
.
At this point I'm not even considering using hex:orderedBy
with the collection resource itself :)
Final thought, we could consider always using hex:OrderedView
also alongside hydra:PartialCollectionView
. In such case offering multiple does not make sense since a client would not want to order partial results in a different way than ordered by the server. However, it would provide a unified way for accessing that information
I propose to pick up where https://github.com/HydraCG/Specifications/issues/172 left off and make an auxiliary vocabulary for describing collection, which goes beyond Hydra Core