Ontologie-Dokumentationsgenerator SimpleOntoDoc

Statischer Dokumentationsgenerator für Ontologien: Implementierung und Anwendungen

SimpleOntoDoc ist ein Werkzeug zur Erstellung statischer Websites zur Dokumentation von Ontologien. Eine Ontologie beschreibt einen Fachbereich durch Klassen, Attribute und die Beziehungen zwischen ihnen. Das Projekt richtet sich an interne Unternehmensmodelle und Standards wie CIM (IEC61970), hat aber breitere Anwendungsmöglichkeiten.

Das Tool generiert Navigation, Diagramme, Eigenschaftstabellen und Suchfunktionalität. Es unterstützt das Parsen von JSON-Schema-Beschreibungen, rendert UML-Diagramme mit PlantUML und verwendet Bootstrap für die Oberfläche.

Struktur der generierten Website

Die Startseite bietet Kacheln für schnellen Zugriff: Klassen, Aufzählungen, Primitive, Datentypen, Verbundtypen. Jede Kachel filtert Entitäten nach Typ. Die Kopfzeile enthält eine groß-/kleinschreibungsunabhängige Suche nach Namen und Beschreibungen.

Der Entitäten-Tab zeigt eine Tabelle aller Entitäten mit interaktiver Suche. Zeilen sind anklickbar und führen zu Klassenseiten.

Auf einer Klassenseite (Beispiel: PowerSystemResource):

• Beschreibung und UML-Diagramm der Vererbungshierarchie + ausgehende Beziehungen.
• Eigenschaftstabelle mit anklickbaren IDs.
• Zusammenfassungsblock: Navigation zu Eltern, Kindern und Verwendung als Datentyp.
• Referenztabelle: Eigenschaften anderer Klassen, bei denen diese Klasse der Typ ist.
• Tabelle der Kindklassen.

Diagramme sind interaktiv: Panzoom zur Navigation, Knoten sind anklickbar.

Eine Eigenschaftsseite (Beispiel: PowerSystemResource.Controls) enthält eine Beschreibung, Zusammenfassung und Navigation.

Anwendungen in Projekten

Das Tool eignet sich für Domänen mit UML-ähnlichen Strukturen: Klassen, Vererbung, Komposition. Beschreiben Sie die Ontologie in JSON (model.py API) und generieren Sie dann die Website.

Anwendungsfälle:

• Dokumentation von Geschäftsobjekten in einem Service (50+ Klassen).
• Gemeinsame Sprache zwischen Entwicklern, Analysten und Anforderungsautoren.
• CI/CD: Generieren der Website bei JSON-Änderungen in Git.
• Grundlage für Codegenerierung oder Export.

Trennen Sie die Ontologie von der Geschäftslogik in Anforderungen.

Technologie-Stack

• C# / .NET 9: Anwendungsgrundlage.
• PlantUML: Rendert UML-Diagramme über einen temporären Server.
• RazorLight: Seitentemplating.
• Bootstrap 5: Frontend-Layout.

Das Veröffentlichungsskript baut einen Docker-Container mit Nginx.

Vergleich mit Alternativen

| Werkzeug | Vorteile | Nachteile |

|------------|-------|--------|

| ontology.tno.nl | Fertige Websites für CIM | Kein Quellcode, nicht für GOST angepasst |

| Widoco | OWL-Unterstützung | Einzelseite, überflüssige Informationen, Design |

| Ontospy | Vererbungsbaum | Erfordert Anpassungen für JSON/UML |

SimpleOntoDoc konzentriert sich auf Einfachheit der Beschreibung, nahe an Programmiersprachen, und vermeidet die Komplexitäten von RDF/OWL.

Erweiterungsmöglichkeiten

• Mehrsprachige Oberfläche.
• Baumansicht von Klassen mit Vererbung.
• Parser für RDF/XML, OWL, XMI, PDF (GOST).
• Validierung: Min/Max, Regex für Eigenschaften.
• Metadaten für Klassen/Attribute.
• Anker (#) für Seitenabschnitte.

Wichtige Punkte

• Generiert eine vollwertige Website mit Suche, Diagrammen und Hyperlinks.
• Eingabe: JSON von model.py, Ausgabe: statische Dateien in Docker.
• Angepasst für CIM/GOST, erweiterbar.
• Für mittlere/senior Entwickler: Fokus auf Domänenmodelle ohne RDF-Komplexitäten.
• CI-Integration für Live-Dokumentation.

— Editorial Team