Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@
/tests/ui/test-results
/rdf/target/
/src/main/js/graph3d/node_modules
/src/main/js/sparql/node_modules
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
- `PATCH /settings` refuses to change `lds:versioningRepository` too: an owner could otherwise have their dataspace commit, with the deployment's credentials, over another dataspace's versions

### Changed
- The browser parses and generates SPARQL with Traqula instead of SPARQL.js 2.x, and the stylesheets read and rewrite queries in Traqula's AST, with typed terms instead of SPARQL.js's term strings (#429)
- A resource a document describes may be left without a type: `PATCH` refuses only to leave the document itself untyped, which it already did, as the document must keep a document hierarchy class. Imported data often describes entities without a type, and a resource that had one could not be given the same shape (#308 held every resource to keeping one)
- The `ldh` plugin's skills show how to check which property views a type gets without a browser, with the page's own lookup query against the installed ontology: `ldh get --accept text/html` returns the page before the browser renders its blocks and property views
- The stylesheets' `forClass` parameter, variable and context key are `for-class`, as every other name in them is spelled. A package stylesheet that passed `forClass` to a platform template passes `for-class`; `data-for-class` and the lookup query's `?forClass` are unchanged
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ The models are transcribed from the code, not extracted from it. The `Formal` wo
### Browser

* [Saxon-JS](https://www.saxonica.com/saxon-js/)
* [SPARQL.js](https://github.com/RubenVerborgh/SPARQL.js)
* [Traqula](https://github.com/comunica/traqula)
* [OpenLayers](https://openlayers.org)
* [Google Charts](https://developers.google.com/chart)

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,28 +37,16 @@
import org.apache.jena.sparql.syntax.ElementGroup;

/**
* Server-side counterpart of the browser's SPARQL.js 2.x <code>Parser</code>, backing the Saxon
* declaration of the <code>ldh:parse-query</code> stylesheet function so that
* <code>ldh:construct-instance</code> runs identically on both products.
* Server-side counterpart of the browser's Traqula <code>Parser</code>, backing the Saxon
* declaration of the <code>ldh:parse-query</code> stylesheet function for
* <code>ldh:construct-instance</code>.
* <p>
* This is deliberately NOT a full SPARQL.js replacement: it emits only the subset of the parse
* tree that the stylesheets consume — a <code>template</code> array of triple maps and a
* <code>where</code> array whose non-emptiness marks a query that cannot be instantiated as a pure
* template (SPARQL.js puts the actual parsed patterns there; only the emptiness test is shared).
* Term strings follow the SPARQL.js 2.x serialization expected by
* <code>ldh:triples-to-descriptions</code>: bare URIs (no angle brackets), <code>_:label</code>
* blank nodes, <code>?name</code> variables, and <code>"lex"</code> /
* <code>"lex"@lang</code> / <code>"lex"^^datatypeURI</code> literals with the datatype URI
* unwrapped — a 2.x quirk that the stylesheet regexes depend on. Divergences from SPARQL.js:
* blank node labels are Jena's parser-allocated ones, not the source labels (downstream only needs
* per-query consistency — <code>ldh:instance-term</code> prefixes them per constructor); variables
* are normalized to the <code>?</code> sigil (SPARQL.js preserves <code>$</code>, and the
* stylesheets accept both); plain literals are emitted without <code>^^xsd:string</code> to match
* SPARQL.js 2.x, although Jena types them as such per RDF 1.1.
* <p>
* If SPARQL.js is ever upgraded to 3.x (see the TO-DO in <code>ldh:triples-to-descriptions</code>),
* this function, <code>ldh:triples-to-descriptions</code> and <code>ldh:construct-instance</code>
* must change in lockstep.
* The stylesheet consumes the Traqula query and pattern keys, including typed RDF terms (a blank
* node carries its name as <code>label</code>, as in Traqula). The server only needs the construct
* template and whether the WHERE group is empty; it does not manufacture a second parser AST for
* query patterns, and since nothing generates SPARQL from this tree, its nodes carry no source
* locations. Jena flattens blank-node property lists and collections in the template, which the
* browser's parser shim does as well.
*
* @author {@literal Martynas Jusevičius <martynas@atomgraph.com>}
*/
Expand Down Expand Up @@ -93,25 +81,34 @@ public XdmValue call(XdmValue[] arguments) throws SaxonApiException
{
Query query = QueryFactory.create(arguments[0].itemAt(0).getStringValue());
JsonObject json = new JsonObject();
JsonArray template = new JsonArray();
JsonArray where = new JsonArray();
JsonObject template = new JsonObject();
JsonArray triples = new JsonArray();
JsonObject where = new JsonObject();
JsonArray patterns = new JsonArray();

if (query.isConstructType())
for (Triple triple : query.getConstructTemplate().getBGP().getList())
{
JsonObject map = new JsonObject();
map.put("type", "triple");
map.put("subject", term(triple.getSubject()));
map.put("predicate", term(triple.getPredicate()));
map.put("object", term(triple.getObject()));
template.add(map);
triples.add(map);
}
else
where.add(new JsonObject()); // not a CONSTRUCT: mark as non-instantiable

Element pattern = query.getQueryPattern();
if (pattern != null && !(pattern instanceof ElementGroup && ((ElementGroup)pattern).isEmpty()))
where.add(new JsonObject());
patterns.add(new JsonObject()); // only emptiness is consumed by construct-instance

template.put("type", "pattern");
template.put("subType", "bgp");
template.put("triples", triples);
where.put("type", "pattern");
where.put("subType", "group");
where.put("patterns", patterns);
json.put("type", "query");
json.put("subType", query.isConstructType() ? "construct" : query.isDescribeType() ? "describe" : query.isAskType() ? "ask" : "select");
json.put("template", template);
json.put("where", where);
return new XdmAtomicValue(json.toString());
Expand All @@ -122,18 +119,41 @@ public XdmValue call(XdmValue[] arguments) throws SaxonApiException
}
}

private String term(Node node)
private JsonObject term(Node node)
{
if (node.isVariable()) return "?" + node.getName();
if (node.isBlank()) return "_:" + node.getBlankNodeLabel();
JsonObject term = new JsonObject();
term.put("type", "term");
if (node.isVariable())
{
term.put("subType", "variable");
term.put("value", node.getName());
}
else if (node.isBlank())
{
term.put("subType", "blankNode");
term.put("label", node.getBlankNodeLabel());
}
if (node.isLiteral())
{
String lex = "\"" + node.getLiteralLexicalForm() + "\"";
if (!node.getLiteralLanguage().isEmpty()) return lex + "@" + node.getLiteralLanguage();
if (node.getLiteralDatatypeURI() != null && !node.getLiteralDatatypeURI().equals(XSDDatatype.XSDstring.getURI())) return lex + "^^" + node.getLiteralDatatypeURI();
return lex;
term.put("subType", "literal");
term.put("value", node.getLiteralLexicalForm());
if (!node.getLiteralLanguage().isEmpty()) term.put("langOrIri", node.getLiteralLanguage());
else if (node.getLiteralDatatypeURI() != null && !node.getLiteralDatatypeURI().equals(XSDDatatype.XSDstring.getURI()))
{
JsonObject datatype = new JsonObject();
datatype.put("type", "term");
datatype.put("subType", "namedNode");
datatype.put("value", node.getLiteralDatatypeURI());
term.put("langOrIri", datatype);
}
}
else if (node.isURI())
{
term.put("subType", "namedNode");
term.put("value", node.getURI());
}
return node.getURI();
return term;
}


}
168 changes: 168 additions & 0 deletions src/main/js/sparql/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
import { Parser as TraqulaParser } from '@traqula/parser-sparql-1-1';
import { Generator as TraqulaGenerator } from '@traqula/generator-sparql-1-1';

// The stylesheets read and rewrite Traqula's AST as JSON (json-to-xml / xml-to-json). This shim keeps that AST in
// a shape the stylesheets can compare and edit without knowing Traqula's source-tracking details:
// - parse() expands prefixed names and BASE-relative IRIs to full IRIs, so a predicate compares as the IRI it is;
// - parse() flattens blank-node property lists ([ ... ]) and collections (( ... )) into plain triples, and gives
// every triple a subject and predicate of its own (Traqula marks repeats after ';' and ',' as not printed), so a
// triple can be matched, moved or appended on its own;
// - generate() gives every node the source location the generator needs, wraps union branches in groups, and
// fills the members a query needs (prologue, dataset clause, solution modifiers), so a stylesheet never writes
// them.

const AUTO = () => ({ sourceLocationType: 'autoGenerate' });

function resolveIri(value, base) {
if (!base) return value;
try {
return new URL(value, base).href;
} catch {
return value;
}
}

function expandIris(node, scope = { prefixes: new Map(), base: undefined }) {
if (Array.isArray(node)) {
node.forEach((value) => expandIris(value, scope));
return node;
}
if (!node || typeof node !== 'object') return node;

let inner = scope;
if (Array.isArray(node.context) && node.context.length > 0) {
inner = { prefixes: new Map(scope.prefixes), base: scope.base };
for (const definition of node.context) {
if (definition.subType === 'base' && definition.value?.value) {
inner.base = resolveIri(definition.value.value, inner.base);
}
if (definition.subType === 'prefix' && definition.key !== undefined && definition.value?.value) {
inner.prefixes.set(definition.key, resolveIri(definition.value.value, inner.base));
}
}
}

if (node.type === 'term' && node.subType === 'namedNode') {
if (node.prefix !== undefined) {
const namespace = inner.prefixes.get(node.prefix);
if (namespace === undefined) throw new Error(`Undefined SPARQL prefix: ${node.prefix}`);
node.value = namespace + node.value;
delete node.prefix;
} else {
node.value = resolveIri(node.value, inner.base);
}
}

for (const [key, value] of Object.entries(node)) {
if (key !== 'context') expandIris(value, inner);
}
return node;
}

// a graph node as a plain term, emitting the triples of a blank-node property list or collection into out
function flattenNode(node, out) {
if (node && node.type === 'tripleCollection') {
for (const triple of node.triples) flattenTriple(triple, out);
return materialize(node.identifier);
}
return materialize(node);
}

function flattenTriple(triple, out) {
if (triple.type === 'tripleCollection') {
flattenNode(triple, out);
return;
}
const subject = flattenNode(triple.subject, out);
const object = flattenNode(triple.object, out);
out.push({ ...triple, subject, predicate: materialize(triple.predicate), object, loc: AUTO() });
}

function materialize(term) {
return term && typeof term === 'object' ? { ...term, loc: AUTO() } : term;
}

function flattenBgps(node) {
if (Array.isArray(node)) {
node.forEach(flattenBgps);
return node;
}
if (!node || typeof node !== 'object') return node;
if (node.type === 'pattern' && node.subType === 'bgp' && Array.isArray(node.triples)) {
const out = [];
for (const triple of node.triples) flattenTriple(triple, out);
node.triples = out;
}
for (const value of Object.values(node)) flattenBgps(value);
return node;
}

function group(patterns) {
return { type: 'pattern', subType: 'group', patterns, loc: AUTO() };
}

// the members the generator dereferences, filled where a stylesheet-built node lacks them
function complete(node) {
if (node.type === 'query') {
if (!Array.isArray(node.context)) node.context = [];
if (!node.datasets) node.datasets = { type: 'datasetClauses', clauses: [] };
if (!node.solutionModifiers) node.solutionModifiers = {};
if (node.subType !== 'describe' && !node.where) node.where = group([]);
const modifiers = node.solutionModifiers;
const limitOffset = modifiers.limitOffset;
if (limitOffset) {
if (limitOffset.limit === undefined && !limitOffset.offset) delete modifiers.limitOffset;
else Object.assign(limitOffset, { type: 'solutionModifier', subType: 'limitOffset' });
}
if (modifiers.order && !(modifiers.order.orderDefs?.length > 0)) delete modifiers.order;
if (modifiers.group && !(modifiers.group.groupings?.length > 0)) delete modifiers.group;
}
if (node.type === 'pattern' && node.subType === 'union' && Array.isArray(node.patterns)) {
node.patterns = node.patterns.map(pattern => pattern.type === 'pattern' && pattern.subType === 'group' ? pattern : group([ pattern ]));
}
}

// every object the generator visits carries a source location; the rows of VALUES are keyed by variable name
// and are not nodes, so they get none (a variable named 'loc' would otherwise be clobbered)
function localize(node, rows = false) {
if (Array.isArray(node)) {
node.forEach(value => localize(value, rows));
return node;
}
if (!node || typeof node !== 'object') return node;
if (rows) {
for (const value of Object.values(node)) localize(value);
return node;
}
if (typeof node.type === 'string') complete(node);
if (!node.loc) node.loc = AUTO();
for (const [key, value] of Object.entries(node)) {
if (key === 'loc') continue;
localize(value, key === 'values' && node.subType === 'values');
}
return node;
}

export class Parser {
constructor(options) {
this.parser = new TraqulaParser(options);
}

parse(query) {
return flattenBgps(expandIris(this.parser.parse(query)));
}
}

export class Generator {
constructor(options) {
this.generator = new TraqulaGenerator(options);
}

generate(ast, options) {
return this.generator.generate(localize(ast), options);
}
}

if (typeof window !== 'undefined') {
window.LDH_SPARQL = { Parser, Generator };
}
Loading
Loading