Koetai — Help & Documentation

Everything you need to publish, query and maintain FAIR RDF datasets.

Overview

Koetai is a self-hosted FAIR SPARQL platform. Each registered user can create multiple datasets. Every dataset gets a dedicated named graph and a public SPARQL endpoint, backed by either QLever (ultra-fast read-only index) or Apache Jena Fuseki (updateable TDB2 store).

RDF data can be loaded from local file uploads, GitHub/GitLab repositories, or arbitrary web download pages. Shapes (ShEx / SHACL) can be inferred automatically and visualised as Mermaid class diagrams. Any SPARQL query can be turned into a parameterized REST endpoint.

Getting started

Koetai is invitation-only. To register:

1. Obtain an invite link from an existing user or admin.
2. Click the invite link — it will redirect you to the ORCID sign-in page.
3. Authenticate with your ORCID iD. If you don't have one, registration is free at orcid.org.
4. After the first login your account is created automatically and the invite is consumed.

Admins can generate invite links from the Invites menu item (visible only to admins after sign-in).

Datasets & triplestores

Create a dataset from My Datasets → New Dataset. Each dataset requires:

• Slug — a URL-safe identifier (e.g. ordo). Forms part of the endpoint URL: /u/{orcid}/{slug}/sparql.
• Label — human-readable name.
• Platform:
  • QLever — blazing-fast for large read-only datasets. Data is indexed into an inverted index; re-indexing is required after each bulk load.
  • Fuseki — Apache Jena TDB2, immediately queryable after each upload. Better for datasets that change frequently.

All triples are stored inside a named graph https://koetai.semscape.org/u/{orcid}/{slug}/data.

Uploading RDF data

From the dataset page, use the Upload tab to load a local file (up to 500 MB). Supported formats: .ttl, .nt, .n3, .rdf, .owl, .trig, .nq, .jsonld.

For .owl and .rdf files an Apply OWL reasoning checkbox appears — see the OWL reasoning section below.

After upload, QLever datasets are automatically re-indexed (this may take a few seconds to minutes depending on file size). Fuseki datasets are immediately queryable.

Git repository sources

From the dataset page, click the Git tab. You can link one or more GitHub or GitLab repositories:

1. Choose GitHub or GitLab from the provider dropdown.
2. Enter the repository as owner/repository (e.g. Orphanet/ORDO).
3. Optionally specify a branch (auto-detected if left blank) and a subfolder path.
4. Click Add. The source appears in the list.

For each source you can then:

• Browse files — lists all RDF/OWL files found recursively. Select and import with optional OWL reasoning.
• Check updates — compares the current HEAD commit SHA against the last imported SHA. A yellow badge appears if a new commit is available.

A GitHub personal access token in .env (GITHUB_TOKEN) removes the 60 req/hr anonymous rate limit. Similarly GITLAB_TOKEN for private GitLab repos.

Web download sources

From the dataset page, click the Web tab. Paste the URL of any download page (e.g. Orphadata or WikiPathways).

1. Click Scan for files — the page is fetched and all hyperlinks pointing to RDF/OWL files are discovered. HTTP HEAD requests capture ETag, Last-Modified, and file size.
2. Select the files you want and click Import selected.
3. Later, click Check updates — HEAD requests are repeated and the ETag / Last-Modified headers are compared to detect new versions. A yellow badge appears when a file has changed.

SPARQL endpoint

Every dataset exposes a SPARQL 1.1 endpoint at:

https://koetai.semscape.org/u/{orcid}/{slug}/sparql

The endpoint accepts GET and POST with a query parameter. Public datasets are readable without authentication.

Click the SPARQL tab from the dataset page to open the built-in YASGUI editor with the endpoint pre-configured.

Shape inference & validation

Click the Shapes tab on any dataset page.

Inference

• ShExer (ShEx) — samples triples from the triplestore, infers a ShEx schema and shows per-property coverage statistics as progress bars. Also generates a Mermaid class diagram.
• ShExer (SHACL) — same tool, SHACL output.

Validation

• Apache Jena ShEx validate — validates the dataset against a saved ShEx schema using the Jena CLI.
• RUDOF validate — validates using the rudof Rust binary.

Inferred shapes are saved to the database and can be downloaded as plain text or viewed as a Mermaid diagram.

Parameterized REST API

Click the API tab. Each SPARQLList query is a SPARQL template with {{param}} placeholders that become URL query parameters.

Example: a template with FILTER(?disease = <{{iri}}>) is called as:

/u/{orcid}/{slug}/api/{query-slug}?iri=http://example.org/disease/123

Results are returned as JSON-LD by default. An interactive form is shown in the browser for manual testing.

Saved query examples

Click the Examples tab to create named SPARQL queries that are stored with the dataset. Examples have a slug, label, optional description, keywords, and the query text. They can be run directly in the built-in SPARQL editor.

OWL reasoning

When importing .owl or .rdf files (via upload, Git, or Web sources), an Apply OWL reasoning option appears. Three regimes are available:

• OWL RL (recommended) — scalable rule-based OWL 2 RL reasoning via the owlrl Python library. Materializes inferred triples before loading into the triplestore.
• RDFS — RDFS-only closure (subClassOf, domain, range, etc.). Fast.
• OWL RL+ — OWL RL with additional rules (Extra).

Reasoning runs as a subprocess; the number of inferred triples is shown in the import result.

Supported RDF formats

Extension	Format
.ttl	Turtle
.nt	N-Triples
.n3	Notation3
.rdf	RDF/XML
.owl	OWL/RDF-XML
.trig	TriG (named graphs)
.nq	N-Quads
.jsonld	JSON-LD