OBIS Schema Extractor is a Java-based web application — a REST service for extracting and analyzing data schemas from SPARQL endpoints. It queries an endpoint, infers the structure of the underlying RDF data, and returns a structured JSON schema model.
Full documentation, execution parameter descriptions, example runs, and guidance on using the produced schemas in data visualization and analysis pipelines is available in the OBIS Schema Extractor wiki.
Contents
The application is packaged as an executable JAR and requires Java 17.
- Install Java 17.
- Copy
build/schema-extractor-exec.jarto any folder along with the other files in thebuilddirectory. - Run the JAR:
java -jar schema-extractor-exec.jar
- Open Swagger UI at http://localhost:8080/swagger-ui.html.
To use a different port:
java -jar schema-extractor-exec.jar --server.port=1234Pull and run the latest image from the GitHub Container Registry:
docker pull ghcr.io/lumii-syslab/obis-schemaextractor:latest
docker run -p 8080:8080 ghcr.io/lumii-syslab/obis-schemaextractor:latestOr use the provided docker-compose.yml to build and run locally (maps container port 8080 to host port 3030):
docker compose upOnce running, Swagger UI is available at http://localhost:8080/swagger-ui.html (or the port you configured).
Services are documented interactively in Swagger UI at http://server:port/swagger-ui.html. To view the V2 services, select the "Schema Extractor API - Current V2" specification from the dropdown in the top-right corner of the Swagger UI page.
| Service | Method | Endpoint | Description |
|---|---|---|---|
| V2: Build Schema from Endpoint | POST |
/schema-extractor-rest/v2/endpoint/buildFullSchema |
Extract schema from a SPARQL endpoint using request parameters |
| V2: Build Schema from Config File | POST |
/schema-extractor-rest/v2/endpoint/buildFullSchemaFromConfigFile |
Extract schema from a SPARQL endpoint using a YAML config file |
Connects to a SPARQL endpoint, extracts and analyzes the RDF data structure, and returns a full schema model as JSON. Parameters are passed as query/form arguments.
Key parameters include the endpoint URL, optional graph name, cardinality calculation mode, subclass and property-relation analysis flags, and optional CSV files to restrict which classes or properties are analyzed. When saveThisConfig=true (default), the effective configuration is saved as a YAML file on the server for later reuse.
All parameters and their descriptions are available in Swagger UI under the "Schema Extractor API - Current V2" specification.
curl -X POST "http://localhost:8080/schema-extractor-rest/v2/endpoint/buildFullSchema?endpointUrl=http%3A%2F%2Flocalhost%3A8890%2Fsparql&graphName=MiniUniv&calculateSubClassRelations=true&calculateMultipleInheritanceSuperclasses=true&minimalAnalyzedClassSize=1&requireClasses=true&calculatePropertyPropertyRelations=true&propertyPropertyLinkCheckBackupMode=details&calculateSourceAndTargetPairs=true&calculateDomainsAndRanges=true&calculateImportanceIndexes=basic&calculateClosedClassSets=true&calculateCardinalities=propertyLevelAndClassContext&calculateDataTypes=propertyLevelAndClassContext&addIntersectionClasses=yes&enableLogging=true&saveThisConfig=true" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data"Example JSON response: SampleExtractedSchemaV2.json
Runs the same schema extraction as above, but reads all parameters from an uploaded YAML configuration file instead of individual query parameters. Useful for automating extractions, reproducing a previous run, or managing complex parameter sets.
An example configuration file with all available parameters and their descriptions is provided at build/example-config.yml.
curl -X POST "http://localhost:8080/schema-extractor-rest/v2/endpoint/buildFullSchemaFromConfigFile" \
-H "accept: application/json" \
-F "configurationFile=@build/example-config.yml"The V1 services are deprecated and kept for backwards compatibility only. New integrations should use the V2 services above.
To view V1 services in Swagger UI, select the "Schema Extractor API - Deprecated V1" specification from the dropdown in the top-right corner of the Swagger UI page.
| Service | Method | Endpoint | Description |
|---|---|---|---|
| buildFullSchema (endpoint) | GET |
/schema-extractor-rest/v1/endpoint/buildFullSchema |
Extract schema from a SPARQL endpoint (version 1) |
| buildFullSchema (OWL file) | POST |
/schema-extractor-rest/v1/owlFile/buildFullSchema |
Extract schema from an OWL/RDF file, optionally enhanced with endpoint data |
Extracts and analyzes data from a SPARQL endpoint and builds a full schema model. All parameters are passed as query string arguments.
curl -X GET "http://localhost:8080/schema-extractor-rest/v1/endpoint/buildFullSchema?endpointUrl=http%3A%2F%2Flocalhost%3A8890%2Fsparql&graphName=MiniUniv&version=fewComplexQueries&mode=full&enableLogging=false&excludeSystemClasses=true&excludeMetaDomainClasses=false&excludePropertiesWithoutClasses=true" \
-H "accept: application/json"Example JSON response: SampleExtractedSchemaV1.json
Reads an uploaded OWL/RDF ontology file and converts it to JSON schema format. Optionally enhances the result with instance data from a SPARQL endpoint if an endpointUrl is provided.
curl -X POST "http://localhost:8080/schema-extractor-rest/v1/owlFile/buildFullSchema?abstractPropertyThreshold=10&propertyInstanceCountThreshold=1000&calculateCardinalities=false" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "file=@SampleTestOntology.owl;type="Example RDF schema: SampleTestOntology.owl
Example JSON response: SampleTestOntology_Schema.json
Clone the repository and build with Maven:
git clone https://github.com/LUMII-Syslab/OBIS-SchemaExtractor.git
cd OBIS-SchemaExtractor
mvn clean install
cd build
java -jar schema-extractor-exec.jarIf you are using IntelliJ IDEA, you can start the application by running SchemaExtractorApplication.java directly.
After startup, Swagger UI is available at http://localhost:8080/swagger-ui.html.