Inhaltsverzeichnis

Entwickler-Richtlinien

Vom Schema zur verlässlichen Datenübergabe

Schema auswählen, Version festhalten, Daten prüfen und erst danach fachlich verwenden.

Bibliothek · Beispiele · Grundregeln

Ein Schema verwenden

  1. Das passende Modul aus der Bibliothek wählen und das Austauschschema herunterladen.
  2. Die konkrete $id und Fassung festhalten. Keine automatische Umstellung auf eine unbekannte neue Version.
  3. JSON-Daten in der beschriebenen Struktur erzeugen. JSON ist das Datenformat; JSON Schema beschreibt die Regeln dafür.
  4. Mit einem Validator für Draft 2020-12 prüfen und benötigte Formatprüfer aktivieren. Alle lokalen $ref-Verweise sind in der Datei enthalten.
  5. Anschließend Referenzziele, Registercodes, Prüfziffern, Zeitfolgen und fachliche Regeln prüfen.

Beispiel mit Python

Voraussetzung: Python und das Paket jsonschema[format]. Dies ist ein Beispiel für einen Validator, keine zusätzliche Voraussetzung für den PHP-Workspace. 

import json
from jsonschema import Draft202012Validator
 
with open("money.schema.json", encoding="utf-8") as file:
    schema = json.load(file)
 
Draft202012Validator.check_schema(schema)
validator = Draft202012Validator(
    schema, format_checker=Draft202012Validator.FORMAT_CHECKER
)
validator.validate({"amount": "12.345", "currency": "KWD"})

Validatoren unterscheiden sich im Umfang ihrer Formatprüfer. Insbesondere internationalisierte E-Mail-Adressen, Sprachcodes und nationale Kennungen benötigen zusätzliche geeignete Prüfungen. Dokumentation von python-jsonschema

Im Workflowdesigner verwenden

  1. Auf der Schemaseite Schema für den Designer herunterladen.
  2. Den Designer öffnen und zum Reiter Schema wechseln.
  3. Die JSON-Datei importieren, ihren Inhalt einfügen oder eine direkt erreichbare JSON-URL verknüpfen. Bei einem anderen Server muss dieser CORS erlauben.
  4. Ein Feld wählen und als Formularfeld oder Speicherregel übernehmen. Bei Listen wird zunächst Index 0 angeboten; weitere Einträge brauchen passende Workflowlogik.
  5. Vor einer verbindlichen Übergabe den gesamten Datensatz gegen das Austauschschema und das fachliche Profil prüfen.

Die Designer-Fassung ist eine Hilfe zur Feldübernahme. Sie übernimmt unterstützte Einzelregeln und lässt bedingte Objektregeln, Listenlängen und weitere Strukturprüfungen weg. Die ausgelassenen Schema-Regeln sind zusätzlich in der versionierten manifest.json dokumentiert. Das Schema ist keine Bestätigung, dass ein vollständiger Datensatz bereits gültig ist.

Der derzeitige Designer löst lokale $ref-Verweise auf und unterstützt unter anderem Datentypen, Muster, Grenzen und Auswahllisten. Vollständige Objektvalidierung, freie Erweiterungsobjekte, beliebige payload.data-Felder und zusätzliche Formate wie idn-email, iri und date-time brauchen ergänzende Logik. Bei optionalen verschachtelten Modulen gelten deren Pflichtfelder erst, wenn das Modul im konkreten Ablauf erhoben wird; die Runtime prüft vor allem die gerade erfassten Felder.

Beispiel Speicherpfad: Für das Modul person/nameandbirthdetails ist der Name unter [name][preferredName] erreichbar. Wird dasselbe Modul in einem zusammengesetzten Schema unter person eingebettet, lautet der Pfad [person][name][preferredName]. Der Pfad hängt von der tatsächlichen Datenwurzel ab.

Geldbetrag: [amount] bleibt ein String. Eine Speicherregel verwendet daher {string}[amount] = „12.345“. Nicht als double speichern, wenn Dezimalgenauigkeit erhalten bleiben muss.

Module zusammensetzen

Zwei Objekte nebeneinander sind noch kein gemeinsames Schema. Beim Einbetten eines Moduls müssen seine lokalen Referenzen weiterhin auf die richtigen Definitionen zeigen. Entweder das vollständige Schema als eigene Ressource mit $id registrieren oder mit einem geeigneten Bundler Referenzen umschreiben. Ein bloßes Kopieren der properties verliert leicht Pflichtregeln und $defs.

Die neuen Aufgaben-, Dokument- und Übergabeschemata sind Austauschverträge. Der vorhandene Workspace verwendet seine bisherige Datenstruktur. Ein Adapter muss Werte ausdrücklich zuordnen und danach erneut validieren; das Wiki installiert keine automatische Ausführung von Skripten oder E-Mails.

Einen Standard erweitern

  1. Fachliche Bedeutung und realen Anwendungsfall beschreiben.
  2. Gegenbeispiele aus unterschiedlichen Ländern, Schriften und Datenlagen sammeln.
  3. Gemeinsamen Kern von Länder- oder Verfahrensprofilen trennen.
  4. Gültige und ungültige Beispiele liefern; Syntax, Meta-Schema, vollständige Validierung und Designer-Felder prüfen.
  5. Änderung an Feldnamen, Bedeutung, Typen oder Pflichtangaben als Migrationsentscheidung dokumentieren.
  6. Eine freigegebene Version unverändert lassen. Neue Semantik braucht eine neue Kennung und Fassung.

Pflege im Projekt

Die gemeinsame Quelle liegt in standards/catalog.cjs; Übersichtsseiten und Integrationshinweise in standards/wiki-pages.cjs. Daraus entstehen die JSON-Dateien und die Wiki-Einträge. Dauerhafte Änderungen an generierten Seiten deshalb in diesen Quellen nachführen, sonst überschreibt der nächste Abgleich sie. Das Speichern verwendet die DokuWiki-Versionshistorie. 

node tools/build-standards.cjs
node tools/build-standards.cjs --check
python -m pip install -r tests/requirements-standards.txt
python tests/wiki-standards-test.py
node --test tests/wiki-standards.test.cjs
php tests/wiki-render-test.php

Die Dateien unter schemas/1.0.0-draft.1/ und die Wiki-Konfiguration für die Download-Verweise gehören gemeinsam ins Deployment. Die lokale Wiki-Installation liegt unter wiki/; die Schemadateien liegen im benachbarten Ordner schemas/. Das lokale Bearbeiten veröffentlicht nichts auf einer entfernten Domain.

Hintergrund

BPMN beschreibt den Ablauf; JSON Schema beschreibt Daten. Reguläre Ausdrücke helfen bei begrenzten Mustern, ersetzen aber keine vollständigen fachlichen Prüfungen. Weiterführender Hintergrund zum Projekt: Entbürokratisierung bei Diversifizierung: Geht das überhaupt?.