The RELEVEN project implements a heavily reified CIDOC-CRM-based knowledge graph to represent historical claims with full contextual provenance. Exposing such complex semantic data to consuming applications presents significant technical challenges. Our demonstration showcases a model-driven approach for building REST APIs on top of SPARQL endpoints by combining RDFProxy-a Python library that maps SPARQL query results to Pydantic models-with WissKAS, a command-line tool that automatically generates RDFProxy endpoints from a declarative RDF path expression language.
● ●
RDFProxy [
Although WissKI path expressions do not enforce and validate graph constraints like e.g. SHACL, they facilitate a concise means for formally declaring semantic shapes and serve as the structural modelling framework for the core RELEVEN knowledge graph implementation.
Building on this, another RELEVEN-developed tool, WissKAS (the WissKI Adapter Serializer) [
While Knowledge Graphs and CRM-based ontologies provide the semantic expressiveness required for modeling contextualized historical data, the RDF technology stack offers only limited support for delivering graph data to consuming applications. SPARQL, the W3C-standard query language and specification for retrieving data from RDF graphs, is primarily designed for patternbased querying and returns result sets of whatever binding projections satisfy a given graph pattern in flat, basically tabular structures. Although effective for graph navigation and data extraction, SPARQL provides no inherent means of declarative result shape transformation and does not natively support the retrieval of potentially deeply nested data structures, subset aggregation, result pagination, or schema validation. As a result, the expressive power of RDF models and reified graphs in particular stands in contrast to the essentially row-based structure of SPARQL result sets, and integrating RDF-based data into client applications typically requires extensive and endpointspecific post-processing logic to convert SPARQL results into consumable data shapes.
The RDFProxy Python library [
Internally, RDFProxy dynamically modifies the incoming SPARQL query - for instance, by injecting certain clauses and subqueries to implement purely SPARQL-based pagination - and utilizes a dataframe abstraction for highly efficient grouping and aggregation operations over SPARQL result sets before mapping the processed data onto a given Pydantic model definition.
The primary code interface for defining API routes with RDFProxy is the rdfproxy.SPARQLModelAdapter class, which is designed to establish and handle a connection between a triplestore, a SPARQL query and a Pydantic model on a per-route basis.
To summarize, the RDFProxy Python library aims to provide a generic solution for building modern REST APIs on top of SPARQL endpoints, allowing backend implementers to leverage the powerful model-driven abstractions of Pydantic and enabling performant transformations of SPARQL query results into structured, type-safe API responses suitable for production workloads.
Building an RDFProxy endpoint requires two main components: ● ● a SPARQL SELECT query for retrieving data from a triplestore a (potentially nested) Pydantic model that defines the desired API response shape and data validation rules.
Typically, RDFProxy-compliant SPARQL queries and their corresponding Pydantic models are implemented manually by backend implementers. However, given a sufficiently expressive structural model-to-RDF mapping, RDFProxy endpoints can also be derived automatically.
WissKI [
These model-to-RDF path relations — called Pathbuilder Definitions in WissKI — are internally
represented as XML structures, which makes them amenable to automated processing. The WissKI
Adapter Serializer (WissKAS) [
Given a Pathbuilder Definition file and a set of endpoint filter specifications, the WissKAS command-line tool is able to construct: ● ● for each desired endpoint: ○ a Pydantic model (often composed of nested classes) with types inferred from the
WissKI definitions. ○ a SPARQL query with a projection that includes all variables required by the model, reflecting the union of all RDF paths defined for the selected fields. a FastAPI entry point with Python function definitions for all derived routes, each of which instantiates an rdfproxy.SPARQLModelAdapter and calls its methods to execute queries against a Triplestore upon endpoint invocation.
By automating the generation of RDFProxy models and queries from RDF path declarations, WissKAS significantly reduces the effort required to create and maintain structured API endpoints. Within the RELEVEN project, WissKAS serves as a central integration facility in a broader semantic modeling workflow, linking domain-specific data modeling in WissKI to accessible, standardscompliant RESTful interfaces.
Our demonstration will showcase the RDFProxy-based REST layer of the RELEVEN graph implementation and automatic API generation from declarative RDF path expressions using the WissKAS backend serializer, highlighting the model-based transformation of complex RDF data into typed API endpoints.
During the preparation of this work, the author(s) used GPT-4o for grammar and spelling checks.