json-rql

JSON Resource Query Language, for simple, consistent query APIs

We could, of course, use any notation we want; do not laugh at notations; invent them, they are powerful. In fact, mathematics is, to a large extent, invention of better notations.

– The Feynman Lectures on Physics, Addison-Wesley, Chapter 17 (1963)

This repository and library presents a notation for expressing queries against structured resources, using JSON. It helps resolve the tensions between expressibility and simplicity, and between agility and future-proofing, in API design. It is based on JSON-LD.

A simple example query:

{ "@where" : { "@type" : "Person", "name" : { "@contains" : "Fred" } } }

1. It's JSON: straightforward to construct in code, manipulate and serialize, and also to constrain. Use standard JSON tooling to limit your API to the queries that your back-end has been designed and tested for.
2. It's SPARQL: in context, all queries can be translated to the W3C standard language for directed, labeled graph data. This means that your API can be extended to cover future query requirements, without breaking changes.

Please see the spec for an explanation of these design choices, and for a walkthrough of common query types.

Feedback and contributions welcome!

SPARQL Translation

⚠️ Since v0.6, the sparql module is separately published as json-rql-sparql, to ease the dependencies burden for consumers of the spec only.

The sparql module demonstrates and tests interconvertibility of json-rql and SPARQL. It can be used directly in a Javascript environment to translate queries, for example in an API implementation where the back-end supports SPARQL.

Requires a modern browser / Node.js v10+

require('json-rql/sparql').toSparql({
  '@select' : '?s',
  '@where' : { '@id' : '?s', '?p' : '?o' }
}, function (err, sparql) {
  // sparql => SELECT ?s WHERE { ?s ?p ?o. }
});

For translation into SPARQL, a json-rql query typically requires a @select, @construct or @describe clause, and a @context to provide the mapping between terms and IRIs. When used in an API, these elements will often derive from the call context.

SPARQL language keywords supported so far can be found in spec/index.ts.

Using the example from SPARQL.js:

require('json-rql/sparql').toSparql({
  '@context' : {
    'dbpedia-owl' : 'http://dbpedia.org/ontology/'
  },
  '@select' : ['?p', '?c'],
  '@where' : {
    '@id' : '?p',
    '@type' : 'dbpedia-owl:Artist',
    'dbpedia-owl:birthPlace' : {
      '@id' : '?c',
      'http://xmlns.com/foaf/0.1/name' : {
        '@value' : 'York',
        '@language' : 'en'
      }
    }
  }
} ,function (err, sparql) {
  // sparql => SELECT ?p ?c WHERE {
  //   ?c <http://xmlns.com/foaf/0.1/name> "York"@en.
  //   ?p <http://dbpedia.org/ontology/birthPlace> ?c.
  //   ?p <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Artist>.
  // }
});

See the tests (especially the JSON files in test/data) for more examples.

Development

The sparql modules is still built and tested from the root package. See the prebuild, postpublish npm scripts to see the how the build is coordinated.

Biblio

• JSON-LD Home
• JSON-LD Specification
• SPARQL
• SPARQL.js
• SPARQL Transformer (a similar approach, "... writing in a single file the query and the expected output in JSON.")
• JSON Schema
• Joi
• Jackson
• Resource Query Language (URL query-based)