SPARQL Transformer

Write your SPARQL query directly in the JSON-LD you would like to have in output.

JavaScript package. Try it with the Playground.

Looking for the Python one?

News

• The parameter $libraryMode allows to perform the pagination on the merged objects, obtaining exactly n=$limit objects
• It is now possible to set a different merging anchor instead of id/@id using the $anchor modifier.

Table of Contents

• Motivation
• Query in JSON
• How to use
• Credits

You want to learn more? Watch this Tutorial

Query in JSON

The core idea of this module is writing in a single file the query and the expected output in JSON.

Two syntaxes are supported: plain JSON and JSON-LD. Here the examples in the 2 formats for the query of cities.

• plain JSON

{
  "proto": [{
    "id" : "?id",
    "name": "$rdfs:label$required",
    "image": "$foaf:depiction$required"
  }],
  "$where": [
    "?id a dbo:City",
    "?id dbo:country dbr:Italy"
  ],
  "$limit": 100
}

• JSON-LD

{
  "@context": "http://schema.org/",
  "@graph": [{
    "@type": "City",
    "@id" : "?id",
    "name": "$rdfs:label$required",
    "image": "$foaf:depiction$required"
  }],
  "$where": [
    "?id a dbo:City",
    "?id dbo:country dbr:Italy"
  ],
  "$limit": 100
}

The syntax is composed by two main parts.

The prototype

The @graph/proto property contains the prototype of the result as I expect it. When the value should be taken from the query result, I declare it using the following syntax:

$<SPARQL PREDICATE>[$modifier[:option...]...]

The subject of the predicate is the variable (declared of automatically assigned) of the closer mergin anchor in the structure, which is the @id/id property (if it exists, otherwise is the default ?id). The SPARQL variable name is manually (with the $var modifier) or automatically assigned.

Some modifiers can be present after, separated by the $ sign. The : prepend the options for a given modifier.

In this way, I specify a mapping between the JSON-LD output properties and the ones in the endpoint. The values non prepended by a $ are transferred as is to the output.

The root $ properties

The $-something root properties allow to make the query more specific. They will be not present in the output, being used only at query level. The supported properties are:

The @context property (for the JSON-LD version) will be transferred to the output.

The output of this query is intended to be:

• for the plain JSON, an array of object with the shape of the prototype;
• for the JSON-LD, an array of object with the shape of the prototype in the @graph property and with a sibling @context.

How to use

Install in nodeJS

Install by npm.

npm install sparql-transformer

Add to the application.

import sparqlTransformer from 'sparql-transformer';

Install in the browser

SPARQL Transformer is exposed as ES Module. We rely on getlibs until the technology will allow to use "bare" import specifier.

<script src="https://unpkg.com/getlibs"></script>
<script>sparqlTransformer = System.import('https://unpkg.com/sparql-transformer')</script>

Use

sparqlTransformer(query, options)
  .then(res => console.log(res))
  .catch(err => console.error(err););

The first parameter (query) is the query in the JSON-LD format. The JSON-LD can be:

• an already parsed JS object (or defined real time),
• ONLY if running in NodeJS, the local path of a JSON file (that will then be read and parsed).

The options parameter is optional, and can define the following:

See test.js for further examples.

Credits

If you use this module for your research work, please cite:

Pasquale Lisena, Albert Meroño-Peñuela, Tobias Kuhn and Raphaël Troncy. Easy Web API Development with SPARQL Transformer. In 18th International Semantic Web Conference (ISWC), Auckland, New Zealand, October 26-30, 2019.

BIB file

Pasquale Lisena and Raphaël Troncy. Transforming the JSON Output of SPARQL Queries for Linked Data Clients. In WWW'18 Companion: The 2018 Web Conference Companion, April 23–27, 2018, Lyon, France. https://doi.org/10.1145/3184558.3188739

BIB file

1: Using a lightweight SPARQL client.