Home

Head to json-rql.org for syntax documentation

Viewpoint 1

Imagine for a second that you had a document index like elasticsearch containing Artists, and their birthplaces as nested documents. Well, then you could trivially translate the JSON example in the readme into an elasticsearch query.

Let's say further that you have several such indexes for different document shapes, as well as a Triplestore; with all of this fronted by an API accepting json-rql. Your API gateway can then pattern-match the requests against the document structure of your indexes, and quickly choose the optimal one, falling back on the Triplestore if no matching one exists.

Now, this might not be the right thing for production, after all, it effectively means your API is contracted to respond to arbitrary SPARQL queries. However, using this pattern during development means you can decouple your client team from your back-end team. The client team can come up with whatever queries they like, and the back-end team can watch the performance tests in the CI pipeline and optimise the indexes to suit. Then, as the product reaches viability, the Triplestore umbilical can be snipped off, and the API will start responding with 501 Not Implemented to queries for which it does not have an index.

Combine this with JSON-LD Framing for the returned documents, and this is very similar to the thinking underlying GraphQL, but with Semantic Web tech.

Viewpoint 2

So we've modeled our domain, decided on our initial front- and back-end platforms, data store, and transports. Vertical slices are emerging. The first entities are getting saved and loaded in the UI. Everyone is pysched because we're moving so fast. The service API is emerging; we've drafted some guidelines, just to keep everyone on the same page. JSON for structured entities, readable keys, a few extra specifics for dates and blobs.

Now the first UI stories for filtering are coming through. Okay, maybe add some query parameters. Maybe one or two extra end-points to cover aggregations. Or maybe we stretch the entity model a little, re-purpose it into a simple query RPC, accommodate pattern matching, maybe some operators.

But... we're feeling conflicted. To keep our API surface under control we've generalised a bit. But now it feels awfully like we're writing a query language. We know way better than to expose our data store's query language, even with tight controls, but writing our own seems like a terrible idea. How do we know our syntax will survive future requirements? Relying on API versioning sounds like a recipe for code bloat, and anyway, are we even sure of the semantics of the current version?