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 a triplestore chosen per dataset — Fuseki and Oxigraph are the two that ship ready to run (see Datasets & triplestores).

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:
  • Fuseki — Apache Jena TDB2. Queryable as soon as an upload finishes, and the default: if you are unsure, choose this.
  • Oxigraph — lighter than Fuseki and just as durable; a good choice for a small install. Needs Oxigraph 0.5.11 or later.
  • QLever — very fast over large read-mostly data, but it serves an index built offline, so it must be set up separately and cannot currently be uploaded to from Koetai. Usable for querying an existing QLever.
  • Federation (Comunica) — not a store: the dataset holds no data of its own and queries a list of external sources live.

Virtuoso, Blazegraph and RDF4J are also implemented and can be configured, but have not been tested against Koetai. The form lists every backend, marks the ones that are not running, and preselects one that is — so the options you can actually choose are the stores this install has available.

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 4096 MB). Supported formats: .ttl, .nt, .n3, .rdf, .owl, .trig, .nq, .jsonld, and any of those compressed as .gz, .bz2, .zip or .tgz. The limit is on the bytes uploaded, so compressing a large graph is usually how it fits; for anything larger the Web tab fetches from a URL and is not capped.

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

Uploads are processed in the background: the page hands the file over and then follows the job through its download, extraction and loading stages, so a large file does not depend on the browser staying open. The dataset is queryable once the job reports done.

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