![Try json-rql on
RunKit](https://npm.runkit.com/json-rql)

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:
``json
{ "@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+

`javascript
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:
`javascript
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 "York"@en.
// ?p ?c.
// ?p .
// }
});
`

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)