How to detect that it is a triple pattern fragments API?

[Maik Riechert]

Let's assume I have a generic dataset catalog which allows you to store links to distributions for a dataset. Such a link can be a downloadable file or some API. Let's also assume I run a triple pattern fragements server that serves multiple datasets. I could say that a dataset distribution is a triple pattern fragment URL like http://fragments.example.com/?subject=http://example.com/datasets/1. As distribution type I would store that this URL supports multiple RDF media types like application/ld+json, turtle etc.

The question is: How can my catalog software assert that this RDF resource actually supports exploring the dataset via triple pattern fragment queries? I know that the control hydra metadata exists, but what does that tell me? It just tells me there is a URL which has three parameters corresponding to rdf subject, predicate, object. But this doesn't tell me the meaning of the API. There could be a completely different API with those three parameters which doesn't support triple pattern queries but actually does something different.

What I'm missing is something like an API type, something like <_:triplePattern> dct:type <ldf:TriplePattern>. Just so that it is clear what happens with the parameters. For example, triple pattern applies an and between parameters, whereas another API could apply an or but still uses the same parameters.

[Ruben Verborgh]

Hi @neothemachine,

How can my catalog software assert that this RDF resource actually supports exploring the dataset via triple pattern fragment queries?

The response will explicitly say “you can query this dataset by triple pattern”.

In the HTML version, you can easily see this through the form on top of the page (example: http://fragments.dbpedia.org/2015/en).

In the RDF version, this is signaled by the presence of this form it will contain the following triples (reformatted for readability):

    <http://fragments.dbpedia.org/2015/en#dataset> a void:Dataset, hydra:Collection;
        void:subset <>;
        hydra:search [
          hydra:template "http://fragments.dbpedia.org/2015/en{?subject,predicate,object}";
          hydra:mapping [
            hydra:variable "subject";
            hydra:property rdf:subject.
          ],[
            hydra:variable "predicate";
            hydra:property rdf:predicate.
          ],[
            hydra:variable "object";
            hydra:property rdf:object.
          ]
        ].

What I'm missing is something like an API type, something like <_:triplePattern> dct:type <ldf:TriplePattern>

While this way of thinking has been followed by some APIs, it does not scale. If every unique API identifies itself just by a URI, then clients have to hardcode those URIs. We instead explicitly explain to a client what they can do, just like we explain it to humans in the HTML version.

More context can be found in this issue and this mailing list post.

Best,

Ruben

PS The best place to ask questions like these is the Specifications repository. The Vocabulary repository is deprecated, and I'll remove it at some point.

[Ruben Verborgh]

I noticed that I haven't answered the most important thing yet:

I know that the control hydra metadata exists, but what does that tell me? It just tells me there is a URL which has three parameters corresponding to rdf subject, predicate, object. But this doesn't tell me the meaning of the API.

It actually does. See this discussion. The hydra:search predicate really has the meaning "you can search this by", not just "the interface accepts these parameters". However, we probably need the even more specific hydra:filter predicate, which has not been created yet, but is discussed on the mailing list.

There could be a completely different API with those three parameters which doesn't support triple pattern queries but actually does something different.

Then it would be incorrect to describe this functionality as hydra:search.

[Maik Riechert]

I agree with what you said, but then you really need to define the full semantics of the parameters/search/filter interface somehow. Basically: the filter interface returns all triples which intersect with the three parameters, where any parameter is optional and corresponds to "any" in that case.

[Ruben Verborgh]

And I agree with that as well! I'll send out a call for consensus on the Hydra mailing list proposing these exact semantics.

[Ruben Verborgh]

I launched a call for consensus for hydra:filter. Then, it will be clear the intended semantics are conveyed fully.

I'll consider this issue closed then, but please don't hesitate to reopen or open another one if anything else comes up. Thanks for your help!

[Maik Riechert]

I just registered on the mailing list, so I cannot reply to your initial post, but it's probably better here anyway (beginner question I think!).

The example with ?member schema:givenName "Markus" is a direct match to what you might get in a RDF dataset. But I'm also looking at derived triples like ?member geo:intersectsBoundingBox "-180;-90;180;0" with a query like ?bbox=-180;-90;180;0 where the conceptually derived triple (it would never appear anywhere, not even inside the server while processing!) would not be part of the response but just exist as a thing to describe the query parameter. Does that fit with the overall model?

[Ruben Verborgh]

I just registered on the mailing list

Great, welcome 😄

But I'm also looking at derived triples like ?member geo:intersectsBoundingBox "-180;-90;180;0" with a query like ?bbox=-180;-90;180;0 where the conceptually derived triple (it would never appear anywhere, not even inside the server while processing!) would not be part of the response but just exist as a thing to describe the query parameter. Does that fit with the overall model?

Absolutely. Nothing in Hydra assumes that there is an underlying dataset. As long as the assertions (materialized or not) are true for each of the members in the response, the filter is correctly implemented.

[Maik Riechert]

Hm, one more thing. What if I have a filter URL "filter?q=foo" which returns a compact representation of each item but then for each item I can also fetch more of the content if I wanted and I can control how much: "item1?levelofdetail=medium". How would I model the latter?

[Ruben Verborgh]

Interesting use case; nothing is implemented in Hydra for that at the moment. Currently, a server would offer multiple resources (high detail collection, low detail collection), and the client would filter those.

[Maik Riechert]

This is similar to doing arbitrary geospatial subsetting on a gridded dataset. Think of a map and the server accepts ?bbox=.. which means that it cuts the map to the given bounding box. Since there are infinitely many possibilities to do that they cannot all be offered for client-side filtering. I guess it's a new thing similar to hydra:filter, like geo:subset. But then I don't understand how hydra works really, because there are many of such uncommon operations and should every new "type" of operation become a new predicate? I thought that with hydra you just list the available API parameters (and http operations) for a given resource and attach semantics to them. There must be a generic way in hydra, I mean it's not just for searching/filtering through collections but for arbitrary APIs, right?

[Ruben Verborgh]

it's not just for searching/filtering through collections but for arbitrary APIs, right?

Yes, that's true. Hydra provides a) building blocks for hypermedia controls and b) common high-level predicates for hypermedia control functionality (like searching and filtering).

I guess it's a new thing similar to hydra:filter, like geo:subset.

If you have an application-specific operation, like “cutting a map to a given bounding box”, you need to define a custom predicate. However, you can make this predicate a subproperty of hydra:search and still reuse functionality like templates etc.