Ontology Management Base

Ontologies for discovering and describing simulation assets in the ENVITED-X data space, maintained by the Automotive Solution Center for Simulation e.V. (ASCS). Compliant with Gaia-X 2.5.0.

Note: This repository is the active development home, forked from GAIA-X4PLC-AAD/ontology-management-base (archived after v0.1.0).

What This Does

These ontologies define searchable metadata for simulation assets (HD maps, scenarios, sensor traces, environment models). They enable:

• Natural language search — "find all German motorway maps with 3+ lanes" → ontology-based-nl-search
• Structured annotation — describe your assets so others can find them → sl-5-8-asset-tools
• Cross-domain discovery — find scenarios that reference a specific HD map
• Quality validation — ensure metadata annotations are complete and correct (SHACL)

The ontology is not a copy of the ASAM OpenDRIVE/OpenSCENARIO data model. It's a metadata layer that summarizes what's inside data files — a 100MB OpenDRIVE file is described by ~2KB of searchable hdmap:HdMap metadata.

Who Uses This

How It Works

flowchart TD
    A[/"Simulation Asset<br/>(OpenDRIVE, OSI, OpenSCENARIO...)"/] -->|annotate| B["JSON-LD Metadata<br/>(@type: hdmap:HdMap)"]
    B -->|validate · SHACL| C[("Knowledge Graph<br/>(SPARQL endpoint)")]
    C -->|search · NL → SPARQL| D["'Show me highway maps near Munich'"]

Getting Started

New to this project? Start with the install, test, build guide.

Looking for ontologies? Browse the ontology catalog.

Need technical details? See concepts and validation strategy.

Quick Links

• Full Documentation — Complete guides and references
• Validation — Run checks on your data
• Contributing — How to add or modify ontologies
• ASAM OpenX Standards — Source standard references (submodule)
• Gaia-X 4 PLC-AAD — Federated catalog upload flow

What's in This Repository

• Ontologies — OWL definitions with SHACL validation shapes (artifacts/)
• Validation Tools — Python suite to validate metadata instances (omb/)
• Test Data — Valid and invalid examples per domain (tests/data/)
• Documentation — Guides, architecture, and specifications (docs/)
• Standard References — ASAM OpenX specs as submodule (submodules/asam-openx-standards/)

Use It in Your Own Repository

If you model your data (in LinkML or otherwise), generate OWL/SHACL/JSON-LD artifacts, and want your test suite to prove that your shapes accept what they should and reject what they should not, install the package — no clone required:

pip install ontology-management-base     # or: uv add ontology-management-base

# data that must conform, validated against your generated artifacts
onto-validate --run check-data-conformance --data-paths tests/data/valid --artifacts artifacts

# data that must fail, checked against its recorded .expected snapshot
onto-validate --run check-failing-tests --data-paths tests/data/invalid --artifacts artifacts

from omb.api import check_negative_fixtures, validate_data

result = validate_data(["tests/data/valid"], artifacts=["artifacts"])
assert result.conforms, result.report_text

report = check_negative_fixtures(["tests/data/invalid"], artifacts=["artifacts"])
assert report.ok, "\n".join(f.message for f in report.failures)

The wheel bundles OMB's own ontologies, imports and registry, so validation works offline and without a checkout. Runtime dependencies are rdflib, pyshacl and oxrdflib. Full guide: Python API.

Requirements

Using the package: Python ≥ 3.12 and nothing else.

Developing the ontologies in this repository:

• Python ≥ 3.12 (required — older versions will fail with syntax errors)
• Git
• uv (installation guide)
• just (installation packages)

Installation (for development)

git clone https://github.com/ASCS-eV/ontology-management-base.git
cd ontology-management-base

# One-command setup (creates .venv, installs dev dependencies, and pre-commit hooks)
just setup

No activation is required for just recipes; they run through uv run. Activate the environment only for direct Python or pip commands:

# Linux / macOS / Git Bash
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

Without Installing the Toolchain

A development container carries uv, just, Python 3.12 and the dev dependencies, so no Python, uv or just is needed on the host:

docker compose build
docker compose run --rm ontology-tools just --list

See Run the Toolchain in a Container.

Validation

# Validate test data
just test

# See validation options
just validate --help

# Validate specific domain
just test-domain hdmap

# Validate a single data file
just validate-file path/to/instance.json

# See all just recipes
just --list

Local Docs Build

# Preview locally
DOCS_SITE_URL=http://127.0.0.1:8000/ontology-management-base just docs-serve

# Build static docs site
just docs-build

Notes:

Hook flow (via hooks/copy_artifacts.py):

1. The hook runs properties_updater and class_page_generator (DOCS_SITE_URL is optional and only affects local diagram links).
2. properties_updater writes tracked artifacts/<domain>/PROPERTIES.md, generates docs/ontologies/properties/<domain>.md (ignored by git), builds the docs/ontologies/properties.md domains overview, and refreshes docs/ontologies/catalog.md.
3. class_page_generator writes docs/ontologies/classes/<domain>/*.md and uses DOCS_SITE_URL to build local diagram links.
4. The hook copies artifacts/<domain>/ into docs/artifacts/<domain>/<versionInfo>/ and adds example instances from tests/data/.

Maintained Ontologies

Acknowledgements

Funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or European Climate, Infrastructure and Environment Executive Agency (CINEA). Neither the European Union nor the granting authority can be held responsible for them.

Consumer contract

See the supported interfaces and feature tests for PyPI and Docker usage.

License

See LICENSE for details.