How-to

Step-by-step guidance for common MAT-X tasks.

Manual ontology — GitHub sync

Each working ontology is stored as a public repository in the mds-ontologies organization. The canonical RDF file is ontology.ttl at the repo root. Fuseki holds the live graph; Git holds the versioned snapshot you commit and share. Open Manual ontology to use the UI.

GitHub personal access token (fine-grained)

Mat-X uses a fine-grained token (not a classic token). You must be a member of mds-ontologies before mds-ontologies appears in the token wizard. An org admin can invite you under the organization's People tab on GitHub.

Open github.com/settings/personal-access-tokens/new (or: your avatar → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token).

1. Token name and expiration

Choose any name (e.g. Mat-X manual ontology) and an expiration you are comfortable with. You can rotate the token later in Profile.

2. Resource owner — this selects `mds-ontologies`

Under Resource owner, open the dropdown. You will see your personal GitHub username and, if you are a member, organizations such as mds-ontologies.

Select mds-ontologies, not your personal username. The token is then scoped to that organization's repositories.
If mds-ontologies is missing, you are not a member yet — ask an org admin to add you, then refresh the page and start the wizard again.

3. Repository access

Choose All repositories (recommended). Mat-X creates a new public repo per working ontology (e.g. mds-ontologies/cement-model), so the token must cover repositories that do not exist yet.

Only select repositories works only if you manually add every ontology repo to the token — not practical for new ontologies.

4. Repository permissions

Expand Repository permissions and set:

Contents: Read and write — clone, pull, commit, and push ontology.ttl.
Metadata: Read-only — usually required automatically; leave as read-only.
Administration: Read and write — allows Mat-X to create new public repositories in mds-ontologies when you create a working ontology.

You do not need Issues, Pull requests, Actions, or other permissions for manual ontology sync. Leave organization-level permissions at defaults unless your org policy requires otherwise.

5. Generate token and authorize SSO (if prompted)

Click Generate token and copy the value immediately (GitHub shows it once). If your organization uses SAML single sign-on, go to Settings → Personal access tokens → Fine-grained tokens, find the new token, click Configure SSO next to it, and authorize mds-ontologies. Without SSO authorization, API calls return 403.

Save the token in Mat-X Profile

On the Profile page, add an API credential:

Vendor: GitHub (or any label containing "github").
API URL: https://api.github.com
API key: paste the fine-grained token you just generated.

Keys are encrypted at rest with NEXTAUTH_SECRET. The server uses the first profile credential whose vendor or URL matches GitHub.

Quick checklist

Resource owner:     mds-ontologies  (not your username)
Repository access:  All repositories
Contents:           Read and write
Metadata:           Read-only
Administration:     Read and write
SSO:                Authorized for mds-ontologies (if your org uses SAML)

Server prerequisites

Git must be installed on the host that runs the Next.js app (git is invoked for clone, checkout, pull, commit, push).
Optional env MANUAL_ONTOLOGY_REPOS_ROOT: directory for local clones (default: .manual-ontology-repos under the app working directory).
Optional env MANUAL_ONTOLOGY_GRAPH_BASE: base IRI for Fuseki named graphs (default: http://mat-space.eu/graph).

Workflow in the UI

Create working ontology — slugifies the name (e.g. Cement Model → repo mds-ontologies/cement-model), creates the public repo if missing, clones it locally, checks out main, pulls, and loads ontology.ttl into the new Fuseki graph (replacing any existing triples in that graph).
Checkout branch — creates or checks out the branch in the local clone, pulls from origin, and loads that branch's ontology.ttl into the branch Fuseki graph.
Operations — add classes, properties, and axioms as usual; changes apply to the active Fuseki graph only until you commit.
Commit — exports the current named graph to ontology.ttl, commits if there are changes, and pushes to GitHub on the active branch (main when no branch is selected).

Repo layout

mds-ontologies/<ontology-slug>/
  ontology.ttl    # canonical RDF; synced with Fuseki on pull and commit

Local clones are stored as {MANUAL_ONTOLOGY_REPOS_ROOT}/mds-ontologies__{ontology-slug}. You can inspect or back up that folder on the server; normal editing happens in the UI.

Participate in the MAT-X dataspace

A local MAT-X dataspace participant runs the Eclipse Dataspace Connector (EDC) together with a semantic RDF layer. The reference stack lives in the edc repository (sibling project in the Mat-X workspace) and is started with Docker Compose.

Prerequisites

Docker Desktop (or Docker Engine) with Compose v2.
At least 4 GB free RAM for Postgres, Vault, Fuseki, OPA, Nginx, and both EDC planes.
Ports 5432, 3030, 8081, 8181, 8185, 8187, 8188, and 8200 available on the host (or adjust mappings in docker-compose.yml).

What the stack provides

EDC operational state (assets, contract definitions, negotiations, transfers) stays in PostgreSQL. Semantic catalogs and RDF assets live in Jena Fuseki. OPA authorizes SPARQL access; Nginx (semantic-api) is the only public entry to Fuseki and proxies EDC management APIs. The control plane and data plane use Tractus-X EDC images with HashiCorp Vault for secrets.

Start the participant locally

From the edc project root (where docker-compose.yml lives):

docker compose up -d

Wait until Postgres, Vault, and Fuseki health checks pass; vault-init seeds dev secrets; then the control plane and data plane start. First boot can take several minutes while images are pulled.

Services and default endpoints

Semantic API (Nginx) — http://localhost:8081: catalog stub at /assets, catalog query at /catalog, policy-gated SPARQL at /sparql.
EDC management (proxied) — http://localhost:8181/management/v3/ with header X-Api-Key: supersecret-api-key.
Data plane (public) — http://localhost:8185/api/public/ for governed data access after contract negotiation.
Fuseki (dev direct) — http://localhost:3030, dataset semantic, admin password admin. Prefer the semantic API in normal use so OPA policies apply.
Participant identity (dev) — did:web:participant.example.org, BPN BPNL000000000001.

Verify SPARQL access

OPA allows GET on /catalog without auth. /sparql requires a Bearer token (any non-empty dev token in the sample policy). Example from the edc test script:

curl -X POST -H "Content-Type: application/sparql-query" \
  -H "Authorization: Bearer my-token" \
  --data "SELECT * WHERE { ?s ?p ?o } LIMIT 10" \
  http://localhost:8081/sparql

On Windows you can run tests/sparql-edc.ps1 in the edc repo for the same check.

Load semantic data and register assets

Upload RDF into the Fuseki semantic dataset (Fuseki UI at port 3030 or SPARQL UPDATE against the dataset). Register corresponding EDC assets and contract definitions via the management API so peers can discover and negotiate access. Mat-X UI tools (Chat, Util) use a separate Fuseki instance for ontology work; point them at your deployment only when that Fuseki is configured in environment variables— the edc stack Fuseki is the participant's governed semantic store behind semantic-api.

Stop and reset

docker compose down
# remove persisted Postgres/Fuseki volumes:
docker compose down -v

Default passwords and API keys are for local development only. Replace Vault secrets, Postgres credentials, Fuseki admin password, and EDC_API_AUTH_VALUE before any shared or production deployment. Do not expose Fuseki port 3030 without a policy gateway.

Inspect, curate and develop ontologies

Chat

Ask questions in natural language about named graphs in Fuseki. The agent uses your profile API credentials when configured. Use it to explore classes, compare terminology, and draft SPARQL before running queries in Util.

Util

Direct tools for inspecting, querying, uploading, and administering live Fuseki graphs:

Ontology Tree — browse subclass hierarchies from a root class.
Ontology Chat — graph-focused Q&A separate from main Chat.
Ontology Graph — visualize CONSTRUCT query results.
Ontology SPARQL — run ad hoc SPARQL queries.
Upload — ingest RDF/OWL files into user graphs.
Download — export a named graph as Turtle (.ttl) or RDF/XML (.owl).
Fuseki — dataset administration and updates.

Ontology Builder

Pipelines for learning and curating ontology structure from corpora and reference graphs:

Autoencoder — corpus chunking, span attention, training, and RDF export grounded in a reference ontology.
Agent-TOM — extract OWL classes from PDF corpora with an OpenAI agent, anchored under reference or project ontologies.
Manual ontology — curate a working ontology in Fuseki with git-style branches, backed by public GitHub repos.
Manual ontology — GitHub setup — configure a fine-grained GitHub token, mds-ontologies repos, branch sync, and commit workflow.

Ensure your Fuseki instance is reachable from the server and that environment variables match your deployment.

Publish semantic assets in MAT-X

Under construction

Discover materials data in MAT-X

PMD DataPortal

The Platform Material Digital (PMD) DataPortal is the public catalog for sharing and discovering materials research data from the PMD consortium and partner organizations. Browse datasets and resources, inspect publishing organizations, and filter by category or tags such as tensile tests, hardness measurements, microscopy, and PMD Core ontology versions.

Many entries describe experimental workflows and machine-readable protocols aligned with the PMD Core ontology, making it easier to find semantically annotated data you can reuse in Mat-X or connect to through the dataspace.

Use the Discover tab in the header to open the portal, or follow the links above.