|
| 1 | +# Purpose and Design Philosophy |
| 2 | + |
| 3 | +## Why These Ontologies Exist |
| 4 | + |
| 5 | +The ENVITED-X ontologies solve a fundamental problem: **simulation assets are opaque files**. An OpenDRIVE map file, an OpenSCENARIO scenario, or an OSI trace contains rich structured data — but you cannot search across thousands of them without first understanding what's inside each one. |
| 6 | + |
| 7 | +These ontologies provide a **searchable metadata layer** that sits alongside simulation assets, enabling discovery without parsing each file's native format. |
| 8 | + |
| 9 | +## The Two Personas |
| 10 | + |
| 11 | +### Data Searcher |
| 12 | + |
| 13 | +> "Show me all HD maps of German motorways with at least 3 lanes and right-hand traffic" |
| 14 | +
|
| 15 | +The searcher doesn't want to download and parse hundreds of `.xodr` files. They need a search interface that understands simulation-domain concepts (road types, lane types, geographic coverage, accuracy) and can query structured metadata. |
| 16 | + |
| 17 | +**How it works:** |
| 18 | + |
| 19 | +1. A natural language query is translated into structured search slots |
| 20 | +2. Slots are validated against the SHACL schema (ensuring valid property names and enum values) |
| 21 | +3. A SPARQL query is compiled from the validated slots |
| 22 | +4. The graph store returns matching assets |
| 23 | + |
| 24 | +The [ontology-based-nl-search](https://github.com/ASCS-eV/ontology-based-nl-search) application implements this flow. The ontology IS the search schema — every property becomes a searchable facet, every enum value becomes a filter option. |
| 25 | + |
| 26 | +### Data Creator |
| 27 | + |
| 28 | +> "I have an OpenDRIVE 1.8 file of the A9 near Munich — how do I make it findable?" |
| 29 | +
|
| 30 | +The creator annotates their asset with JSON-LD metadata conforming to the ontology. The annotation captures what's important for discovery without duplicating the entire file content. |
| 31 | + |
| 32 | +**How it works:** |
| 33 | + |
| 34 | +1. The creator (or automated tooling like [sl-5-8-asset-tools](https://github.com/openMSL/sl-5-8-asset-tools)) produces a JSON-LD instance |
| 35 | +2. The instance declares `@type: hdmap:HdMap` and populates properties (format, content, quality, quantity) |
| 36 | +3. SHACL validation ensures the metadata is complete and values are correct |
| 37 | +4. The validated metadata is indexed in a knowledge graph for search |
| 38 | + |
| 39 | +### The Feedback Loop |
| 40 | + |
| 41 | +Both personas generate feedback that improves the ontology: |
| 42 | + |
| 43 | +- **Searcher can't find what they want** → missing property or enum value |
| 44 | +- **Creator can't describe their asset** → missing concept or inadequate granularity |
| 45 | +- **Search returns wrong results** → property semantics unclear or overlapping |
| 46 | + |
| 47 | +This gap-discovery process drives ontology evolution. |
| 48 | + |
| 49 | +## Metadata, Not Data Modeling |
| 50 | + |
| 51 | +A critical design principle: **these ontologies describe metadata ABOUT simulation assets, not the assets themselves**. |
| 52 | + |
| 53 | +``` |
| 54 | +┌────────────────────────────────────────────────────┐ |
| 55 | +│ SIMULATION ASSET (e.g., highway.xodr, 100MB) │ |
| 56 | +│ │ |
| 57 | +│ Contains: every road, lane, junction, signal, │ |
| 58 | +│ geometry point, elevation sample... │ |
| 59 | +│ Format: OpenDRIVE XSD schema (implicit ontology) │ |
| 60 | +└────────────────────────────────────────────────────┘ |
| 61 | + │ |
| 62 | + │ DESCRIBED BY (summarized, not duplicated) |
| 63 | + ▼ |
| 64 | +┌────────────────────────────────────────────────────┐ |
| 65 | +│ METADATA ANNOTATION (~2KB JSON-LD) │ |
| 66 | +│ │ |
| 67 | +│ "This file is an ASAM OpenDRIVE v1.8 map. │ |
| 68 | +│ It covers 45km of motorway with 12 junctions. │ |
| 69 | +│ Right-hand traffic. Lane types: driving, │ |
| 70 | +│ shoulder. Accuracy: ±0.1m 2D." │ |
| 71 | +│ │ |
| 72 | +│ Format: ENVITED-X ontology (explicit, searchable) │ |
| 73 | +└────────────────────────────────────────────────────┘ |
| 74 | +``` |
| 75 | + |
| 76 | +The ontology does NOT re-model OpenDRIVE's road geometry, signal semantics, or lane structure. Instead it captures the **discovery-relevant summary** of what's inside. |
| 77 | + |
| 78 | +## Relationship to Source Standards |
| 79 | + |
| 80 | +The ontologies relate to ASAM/ISO standards in five ways: |
| 81 | + |
| 82 | +| Relationship | Description | Example | |
| 83 | +|-------------|-------------|---------| |
| 84 | +| **Aligns** | Uses the same terminology and enum values | `hdmap:roadTypes` uses OpenDRIVE `e_roadType` values verbatim | |
| 85 | +| **Summarizes** | Counts or lists what's in the file | `numberJunctions: 12` (not each junction's structure) | |
| 86 | +| **Extends** | Adds metadata not present in the format itself | `accuracyLaneModel2d: 0.1` (quality info external to the file) | |
| 87 | +| **Complements** | Adds governance/provenance context | `hasManifest`, `hasResourceDescription` (Gaia-X layer) | |
| 88 | +| **Interconnects** | Links across simulation domains | `scenario` references `hdmap` + `environment-model` | |
| 89 | + |
| 90 | +## Design Principles |
| 91 | + |
| 92 | +1. **Search-first** — Every property should answer a plausible user query. If no one would search by it, it's low priority. |
| 93 | + |
| 94 | +2. **Standard-aligned** — Use the same terms as ASAM/ISO standards. Don't invent new names for existing concepts. Cite the normative source. |
| 95 | + |
| 96 | +3. **Version-aware** — Track format versions and enforce version-appropriate constraints. OpenDRIVE 1.4 has different valid values than 1.8. |
| 97 | + |
| 98 | +4. **Cross-domain** — Enable queries that span multiple asset types. "Find scenarios that use a specific HD map" requires linked metadata. |
| 99 | + |
| 100 | +5. **Fail-fast validation** — SHACL shapes ensure metadata is correct at creation time, not when someone tries to search and gets bad results. |
| 101 | + |
| 102 | +6. **Gap-discoverable** — When the search app can't answer a question, that's a signal to add a property. Document gaps explicitly. |
| 103 | + |
| 104 | +## The Property Test |
| 105 | + |
| 106 | +When considering adding a new ontology property, apply this test: |
| 107 | + |
| 108 | +> **"What natural language search query does this property enable?"** |
| 109 | +
|
| 110 | +- ✅ `junctionTypes` → "Find maps with roundabouts" — clear search value |
| 111 | +- ✅ `geometryTypes` → "Find maps with spiral road segments" — useful for tooling |
| 112 | +- ❌ `numberOfGeometryPoints` → Nobody searches by vertex count — too low-level |
| 113 | +- ❌ `xmlSchemaVersion` → Internal technical detail, not a discovery criterion |
| 114 | + |
| 115 | +## Architecture Overview |
| 116 | + |
| 117 | +``` |
| 118 | +ENVITED-X Ontology Stack |
| 119 | +═══════════════════════════════════════════════════════ |
| 120 | +
|
| 121 | + ┌─────────────────────────────────────────────┐ |
| 122 | + │ Gaia-X Trust Framework │ Governance |
| 123 | + │ (gx:ServiceOffering, Compliance, Trust) │ & Identity |
| 124 | + └──────────────────────┬──────────────────────┘ |
| 125 | + │ |
| 126 | + ┌──────────────────────▼──────────────────────┐ |
| 127 | + │ envited-x (base layer) │ Shared Types |
| 128 | + │ SimulationAsset, Manifest, ResourceDesc │ & Wrappers |
| 129 | + └──────────────────────┬──────────────────────┘ |
| 130 | + │ |
| 131 | + ┌──────────┬───────────┼───────────┬──────────┐ |
| 132 | + │ │ │ │ │ |
| 133 | + ▼ ▼ ▼ ▼ ▼ |
| 134 | +┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ |
| 135 | +│ hdmap │ │scenario│ │osi- │ │environ-│ │surface-│ Domain |
| 136 | +│ │ │ │ │trace │ │ment- │ │model │ Specific |
| 137 | +│OpenDRIVE│ │OpenSCE-│ │OSI │ │model │ │OpenCRG │ |
| 138 | +│Lanelet │ │NARIO │ │ │ │OpenMAT │ │ │ |
| 139 | +└────────┘ └────────┘ └────────┘ └────────┘ └────────┘ |
| 140 | +
|
| 141 | + ┌──────────────────────────────────────────────┐ |
| 142 | + │ openlabel-v2 (cross-cutting) │ ODD/Labeling |
| 143 | + │ ISO 34503 taxonomy, weather, road users │ (shared by |
| 144 | + │ OpenODD modules, OpenLABEL types │ multiple) |
| 145 | + └──────────────────────────────────────────────┘ |
| 146 | +``` |
| 147 | + |
| 148 | +Each domain ontology: |
| 149 | + |
| 150 | +- Is a subclass of `envited-x:SimulationAsset` |
| 151 | +- Has a `DomainSpecification` with format, content, quality, quantity facets |
| 152 | +- Uses SHACL to validate enum values appropriate to the format version |
| 153 | +- Can reference other domains (e.g., scenario → hdmap) |
| 154 | + |
| 155 | +## Source Standards Reference |
| 156 | + |
| 157 | +The [asam-openx-standards](https://github.com/ASCS-eV/asam-openx-standards) submodule (at `submodules/asam-openx-standards/`) contains version-pinned markdown copies of all referenced ASAM standards. See its `AGENTS.md` for navigation guidance and `ENUMERATIONS.yaml` for machine-readable enum data. |
0 commit comments