SPARQL-Results+JSON Parse


A utility package that allows you to parse SPARQL JSON results
in a convenient RDF/JS-based datastructure.

For example, the following SPARQL JSON result can be converted as follows:

In:
``json
{
"head": {
"vars": [
"book"
]
},
"results": {
"bindings": [
{ "book": { "type": "uri", "value": "http://example.org/book/book1" } },
{ "book": { "type": "uri", "value": "http://example.org/book/book2" } },
{ "book": { "type": "uri", "value": "http://example.org/book/book3" } },
{ "book": { "type": "uri", "value": "http://example.org/book/book4" } },
{ "book": { "type": "uri", "value": "http://example.org/book/book5" } },
{
"book": {
"type": "triple",
"value": {
"subject": {
"type": "uri",
"value": "http://example.org/alice"
},
"predicate": {
"type": "uri",
"value": "http://example.org/name"
}
}
}
}
]
}
}
`

Out:
`javascript
[
{ '?book': namedNode('http://example.org/book/book1') },
{ '?book': namedNode('http://example.org/book/book2') },
{ '?book': namedNode('http://example.org/book/book3') },
{ '?book': namedNode('http://example.org/book/book4') },
{ '?book': namedNode('http://example.org/book/book5') },
{ '?book': quad(namedNode('http://example.org/bob'), namedNode('http://example.org/name'), literal('Bob', namedNode('http://example.org/Type'))) },
]
`

Where namedNode is an RDF/JS named node, quad is an RDF/JS quad/triple, and literal is an RDF/JS literal.

This library automatically converts all SPARQL JSON result values to their respective RDF/JS type.

Usage

$3

`javascript
import {SparqlJsonParser} from "sparqljson-parse";

const sparqlJsonParser = new SparqlJsonParser();
`

Optionally, you can provide a settings object to the constructor with optional parameters:
`javascript
const sparqlJsonParser = new SparqlJsonParser({
dataFactory: dataFactory, // A custom RDFJS datafactory
prefixVariableQuestionMark: true, // If variable names in the output should be prefixed with '?', default is false.
});
`

$3

`javascript
sparqlJsonParser.parseJsonBindings({ "book": { "type": "uri", "value": "http://example.org/book/book1" } })
// This will output { '?book': namedNode('http://example.org/book/book1') }
`

$3

`javascript
const sparqlJsonresponse = {
"head": {
"vars": [
"book"
]
},
"results": {
"bindings": [
{ "book": { "type": "uri", "value": "http://example.org/book/book1" } }
]
}
};
sparqlJsonParser.parseJsonResults(sparqlJsonresponse);
// This will output [ { '?book': namedNode('http://example.org/book/book1') } ]
`

$3

`javascript
const sparqlJsonresponse = {
"head": {},
"boolean": true
};
sparqlJsonParser.parseJsonBoolean(sparqlJsonresponse);
// This will output true
`

$3

If you have many query results, then a streaming-based approach might be more efficient.
In this case, you can use the sparqlJsonParser.parseJsonResultsStream method,
which takes a Node readable stream of SPARQL JSON results as a text stream,
and outputs a stream of parsed bindings.

Optionally, you can also retrieve the variables, links, and version inside the head
as follows by listening to the 'variables', 'link', and 'version' events:
`
sparqlJsonParser.parseJsonResultsStream(myStream)
.on('variables', (variables: RDF.Variable[]) => console.log(variables))
.on('link', (links: string[]) => console.log(links))
.on('version', (version: string) => console.log(version))
.on('data', (bindings: IBindings) => console.log(bindings));
`

sparqlJsonParser.parseJsonBooleanStream also takes a stream as input,
but it returns a promise that resolves to a boolean.

The error thrown for unsupported versions can be skipped
by setting parseUnsupportedVersions to true when constructing the parser.

$3

This library can recognise metadata on the result stream in the following form:

`json
{
"head": { "vars": [ "book", "library" ] },
"results": {
"bindings": [
{ "book": { "type": "uri", "value": "http://example.org/book/book1" }, "library": { "type": "uri", "value": "http://example.org/book/library1" } }
]
},
"metadata": { "httpRequests": 0 }
}
`

This metadata can be captured by listening to the "metadata" event:
`
sparqlJsonParser.parseJsonResultsStream(myStream)
.on('metadata', (metadata: any) => console.log(metadata))
.on('data', (bindings: IBindings) => console.log(bindings));
``

Note that this is not part of the SPARQL/JSON specification.

License

This software is written by Ruben Taelman.

This code is released under the MIT license.