Die titan Datenbeschreibungssprache UJO Schema erlaubt nicht nur die Beschreibung der eigentlichen Datenstruktur, sondern bietet auch Möglichkeiten umfangreich zu dokumentieren. So kann an einer Stelle die technische Beschreibung und die Dokumentation gepflegt werden, was es wesentlich erleichtert, beide auf einem aktuellen Stand zu halten.
Selbst wenn zu Beginn eines Projekts Datenstrukturen gut dokumentiert sind, wird dieser Aspekt mit der Zeit oft vernachlässigt. Wenn das passiert, passen die realen Daten mit der Zeit immer weniger zur Dokumentation. Um diese Lücken wieder zu schließen, sind aufwendige Analysen erforderlich. Was sich jemand beim Erstellen der Datenstruktur gedacht hat, ist so allerdings nicht mehr zu ermitteln und für immer verloren.
In den drei vorangegangenen Blogs Es sind die Daten, Dummchen, Typen gibt’s und Grenzen setzen wurde erklärt wie mit UJO Schema Datenstrukturen beschrieben werden. Auch wenn die dort gezeigten Beispiele relativ leicht verständlich sind, ist es sinnvoll Informationen hinzuzufügen, die zwar technisch keine Rolle spielen, aber für das Verständnis der Daten wichtig sind.
Das Folgende Beispiel zeigt einen Datentyp, der einen bestimmten Status als Zahlenwert darstellt.
status = int32
: in (0 ,1, 2, 3 ,4);
Was die einzelnen Werte aussagen, oder wofür der Status verwendet wird ist nicht ersichtlich. Fügt man jedoch mit dem Schlüsselwort doc entsprechende Beschreibungen ein, wird klar, worum es dabei geht.
status = int32
: in (
0 : doc "offline",
1 : doc "warten",
2 : doc "daten empfangen",
3 : doc "drucken",
4 : doc "Fehler"
)
: doc "Aktuelle Aktivität eines Druckers";
Jeder mit der Einschränkung in definierte Wert ist dokumentiert. Die Dokumentation des Datentyps status steht am Ende. So wird deutlich, wie die Werte interpretiert werden und welchen Zweck sie erfüllen.
So kann aus der rein technischen Beschreibung auch eine Online-Dokumentation generiert werden:
status
Aktuelle Aktivität eines Druckers
| Identifier | Type | Constraints |
|---|---|---|
| status | int32 | in Values |
status in Values
| Value | Description |
|---|---|
| 0 | offline |
| 1 | warten |
| 2 | daten empfangen |
| 3 | |
| 4 | Fehler |
Damit auch ausführlichere Texte gut lesbar zu formatieren sind, wird mit dreifachen Anführungszeichen """...""" über mehrere Zeilen dokumentiert. Dabei werden Markdown Formatierungen verwendet.
number = (int32, int64, float32, float64)
: doc """Zahlenwert im [__JSON__](https://www.json.org) Stil.
Eine Aufstellung der verwendeten _Datentypen_ ist
[hier](https://www.geeksforgeeks.org/json-data-types/) zu finden.
__folgende Typen sind möglich:__
- string
- number
- boolean
- null
- object
- array
""";
Das Beispiel zeigt, wie einfach eine gut lesbare Dokumentation mit zusätzlichen Links angereichert wird. Übersetzt in eine Online-Dokumentation sieht es dann wie folgt aus:
number
Zahlenwert im JSON Stil. Eine Aufstellung der verwendeten Datentypen ist hier zu finden.
folgende Typen sind möglich:
- string
- number
- boolean
- null
- object
- array
| Identifier | Type | Constraints |
|---|---|---|
| number | [int32, int64, float32, float64] |
Records und Objekte dokumentieren
drucker = [
drucker_id = string : not null : doc "Eindeutige Bezeichnung der Maschine",
drucker_status = status : not null : doc "Maschinenstatus",
drucker_online = int64 : doc "Sekunden online"
] : doc "Aktuelle Informationen des Druckers";
In diesem Beispiel wird der oben deklarierte Datentyp status verwendet. Beim Erzeugen der Dokumentation wird automatisch ein entsprechender Link erzeugt.
drucker
Aktuelle Informationen des Druckers.
Items:
| Name | Type | Doc | Constraints |
|---|---|---|---|
| drucker_id | string | Eindeutige Bezeichnung der Maschine | [not null] |
| drucker_status | status | Maschinenstatus | [not null] |
| drucker_online | int64 | Sekunden online |
In gleicher Weise können die Druckerinformationen auch als Objekt beschrieben werden.
drucker = {
"drucker_id" -> string : not null : doc "Eindeutige Bezeichnung der Maschine",
"drucker_status" -> status : not null : doc "Maschinenstatus",
"drucker_online" -> int64 : doc "Sekunden online"
} : doc "Aktuelle Informationen des Druckers";
Fazit
So entsteht quasi nebenbei eine Dokumentation der Datenstrukturen zusammen mit der technischen Beschreibung für die automatische Prüfung von Daten. Die navigierbare, verlinkte HTML Version der Dokumentation lässt sich automatisch generieren und aktualisieren.
Interesse geweckt? – Bald gibt es mehr Infos zu titan. Folge uns auf Twitter @InDevOps_Titan
Hier findest Du das Projekt ujoschema-py
Titel Photo by Andrea Piacquadio from Pexels