$ show sparna-git/Sparnatural
Sparnatural is a client-side, web-component-based visual SPARQL query builder. It allows non-technical users to construct complex SPARQL SELECT queries by selecting classes, properties, and values through an interactive criteria tree, with support for AND/OR, OPTIONAL, NOT EXISTS, aggregated variables, and geospatial filters. The system is configurable via SHACL or OWL shape definitions, which define available entities, properties, widgets, and datasources. It integrates with YASGUI for query editing and result display, and provides multiple built-in widget types (list, autocomplete, tree, map, date range, number, boolean, search). The core architecture is a custom HTML element (`<spar-natural>`) with a component-based UI, event-driven state management (ActionStore), and a SPARQL generation pipeline that converts an internal JSON query format to SPARQL algebra using sparqljs. The codebase demonstrates solid engineering with clean interfaces for specification providers and data providers, but carries technical debt from a legacy OWL configuration path, two query JSON formats (v1 and v13), heavy jQuery/DOM manipulation, and limited test coverage outside the SPARQL translator. It is actively maintained and well-documented, but its tight coupling to SPARQL endpoints and large dependency bundle may limit reuse in non-RDF contexts.
The LLM identified 5 files worth highlighting for reuse:
A generic DAG (Directed Acyclic Graph) data structure used to represent entity and property hierarchies. It provides addEdge, getRoots, getChildren, topological sort, and cycle detection. The implementation is self-contained, uses TypeScript generics, and has no external dependencies, making it easily extractable for any project needing hierarchical relationship modeling.
A centralized, event-driven state management store that dispatches typed actions (such as generateQuery, redrawBackgroundAndLinks, selectViewVar) to decouple components from the query generation and UI update logic. It follows a redux-like pattern where actions are objects with a type and optional payload, and are processed by registered handlers. The implementation is independent of the Sparnatural domain and could be reused for any client-side state flow.
The primary translator that converts the internal JSON query format (v13) into a SPARQL SELECT query using the sparqljs library. It delegates WHERE clause generation to BranchTranslatorV13, handles OPTIONAL and NOT EXISTS branches, and integrates widget-specific value builders. The design is a clean visitor-style translator with a well-defined interface, testable in isolation, and could serve as a reference pattern for any JSON-to-query-language transformation.
A TypeScript interface defining the contract for specification providers that supply entity and property definitions from ontology files (SHACL or OWL). Methods like getEntity(), getProperty(), getConnectingProperties(), getDomainOfProperty() abstract away the underlying shape representation. This interface enables plugging in different configuration formats without modifying the UI layer, demonstrating a clean adapter pattern.
The base class for all widget types (list, autocomplete, tree, map, date, etc.). It defines a common lifecycle with methods like render(), parseInput(), getRdfJsPattern(), and handles value repetition (SINGLE/MULTIPLE). Subclasses only implement domain-specific logic. The class is self-contained aside from importing value builders and data provider interfaces, making it a reusable template for adding new widget types in any SPARQL-based UI.