Datenstrukturen dokumentieren

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, DummchenTypen 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

IdentifierTypeConstraints
statusint32in Values

status in Values

ValueDescription
0offline
1warten
2daten empfangen
3drucken
4Fehler

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
IdentifierTypeConstraints
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:

NameTypeDocConstraints
drucker_idstringEindeutige Bezeichnung der Maschine[not null]
drucker_statusstatusMaschinenstatus[not null]
drucker_onlineint64Sekunden 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