Wondering what’s next for npm?Check out our public roadmap! »

    json-rql
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.1 • Public • Published

    licence npm Build Status Try json-rql on RunKit

    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

    Install

    npm i json-rql

    DownloadsWeekly Downloads

    10

    Version

    0.6.1

    License

    MIT

    Unpacked Size

    126 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar