Use of Hydra collections for W3C WoT Discovery

wiresio commented 3 years ago

I'm reaching out to you from the W3C WoT Discovery TF since we have a special issue there.

Describe your API requirement

In https://w3c.github.io/wot-discovery/#exploration-directory-api-registration-listing we are describing an API where all WoT Thing Descriptions (TD) can be downloaded from a so-called Thing Description Directory (TDD). TDs describe the interface towards specific devices or services and are defined as JSON-LD documents. The TDD is responsible to store and make them available for other devices or services interested in "consuming" these resources.

Since a TDD might store a large number of TDs, it is not appropriate to "dump" all of the TDs in one flush but rather offer some form of pagination such that the clients have a chance to receive all of them.

Solution(s)

Currently the spec. features two methods for pagination very specific for http (1.1): "Chunked transfer encoding" and "header based pagination". Since I got a quite reserved response from developers using these methods, I'm interested in designing an "envelope based" pagination response as an alternative similar to as it is described in your spec: https://www.hydra-cg.com/spec/latest/core/#collections

The special issue that we have, is that the objects in the "members" array are JSON-LD documents having individual contexts other than the context of the envelope. Due to the expertise that we have in our TF this will yield to implications once it comes to transfer to (RDF) triples. IMHO I would consider the envelope as format that is just needed "on the wire" to send server side information like pagination info along with the actual data and that clients could directly access the "members" array and then do the RDF processing.

Question

What is your take on this? Have you ever come across such requirements? Would you know a good solution for the envelope approach?

Thanks!

tpluscode commented 3 years ago

We tend to keep Hydra agnostic of the RDF format an API would use. Our examples too are JSON-LD but it is a detail which would be unimportant to a generic client which is our default "audience".

That said, you would be free to structure your RDF responses whichever way you need, as long as they represent valid RDF syntactically and Hydra semantically. In that regard, nested @context inside each member of a hydra collection is perfectly fine as it breaks neither of the syntactic and semantic requirement.

So such an envelope would look something like below?

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@id": "/things",
  "@type": "Collection",
  "member": [{
    "@context": "https://www.w3.org/2019/wot/td/v1",
    "@id": "td:Thing"
  }],
  "view": {
    "@id": "/things/5",
    "previous": "/things/4",
    "next": "/things/6"
  }
}

This would be a valid way to ensure there are no clashes between Hydra and TD terms, keeping the members separate from the envelope's vocabulary

wiresio commented 3 years ago

Thanks for your quick response! It supports my view and I'd have designed the envelope also this way.

@AndreaCimminoArriaga - Would be great if you could comment it. Do we miss something here?

AndreaCimminoArriaga commented 3 years ago

It could be an alternative, but I think this should be discussed and studied before taking a decision. I think @farshidtz proposed a sensible approach to this in issue

wiresio commented 3 years ago

@AndreaCimminoArriaga - thanks for your reply! The discussion with Hydra colleagues should ensure that - from the semantic standpoint - we're on the safe side. Discovery discussion will continue in the issue you mentioned.

@tpluscode - Anything to add from you or other Hydra CG members?

HydraCG / Specifications