Mit Schematron QuickFix vom Styleguide zur interaktiven Benutzerführung

(Autoren: Nico Kutscherauer und Manuel Montero Pineda)

Schematron wird häufig als reine Prüfsprache verstanden: Eine Regel meldet, dass etwas nicht passt, und der Anwender muss selbst wissen, wie er das Problem löst. In Kombination mit Schematron QuickFix (SQF) entsteht daraus jedoch ein interaktives Werkzeug. Die Regel beschreibt nicht nur den Befund, sondern bietet direkt passende Aktionen an. 

So lassen sich Styleguides, Modellierungsregeln und redaktionelle Vorgaben in Oxygen XML Editor so umsetzen, dass Anwender geführt werden, ohne die technischen Details auswendig kennen zu müssen. Das gilt für Inhaltsdokumente ebenso wie für XML-basierten Programmcode, etwa XSD oder XSLT.

Weitere Inhalte dieser Seite:

• Styleguide, Schematron und XML-basierter Code
• Aufgabenstellung: Regeln sollen nicht nur prüfen, sondern führen
• Beispiel 1: XSD Guide als interaktiver Styleguide
• Beispiel 2: Konfigurierbares DITA-Menü für Redaktionen
• Was beide Beispiele gemeinsam zeigen

Styleguide, Schematron und XML-basierter Code

Eine Standard-Spezifikation beschreibt, ob ein Dokument oder ein Programmcode syntaktisch und strukturell erlaubt ist. Im XML-Kontext übernehmen dies üblicherweise der XML-Parser (Syntax-Prüfung) und ein XML Schema (Struktur-Prüfung). Ein Styleguide beschreibt dagegen Vereinbarungen, die über Validität hinausgehen: ob das Dokument oder der Programmcode auch so aufgebaut ist, wie es Konvention ist. Beispiele dafür sind Vorgaben für vergebene IDs oder Namen oder der einheitliche Einsatz semantisch ähnlicher Strukturen. Solche Regeln stehen üblicherweise in einem Dokument, das während der Arbeit niemand geöffnet hat – und im schlimmsten Fall werden sie gar nicht überprüft!

Schematron ist für genau diese Regelklasse gemacht. Statt ein Inhaltsmodell zu beschreiben, formuliert es Bedingungen an konkreten Stellen im Dokument: ein XPath wählt den Kontext, ein Test beschreibt die Erwartung, der Meldungstext steht in natürlicher Sprache. Und weil Schematron zwischen Fehler, Warnung und Hinweis unterscheiden kann, lassen sich auch Empfehlungen ausdrücken, die nicht zum Validierungsabbruch führen sollen.

Dabei wird leicht übersehen, dass das geprüfte Dokument kein Inhaltsdokument sein muss. XML Schema, XSLT, XProc und Schematron selbst sind XML – und damit für Schematron ganz normale Prüfobjekte. Ein Schematron kann also Programmcode prüfen: ob ein XSLT-Template dokumentiert ist, ob ein Modus deklariert wurde, ob eine XSD dem vereinbarten Design-Pattern folgt. Was in anderen Sprachwelten ein eigenes Linting-Werkzeug erfordert, ist im XML-Umfeld mit Bordmitteln möglich. Das erste Beispiel in diesem Artikel “XSD Guide als interaktiver Styleguide” nutzt genau das.

Aufgabenstellung: Regeln sollen nicht nur prüfen, sondern führen

Die Stärke von Schematron bei Prüfungen auf sehr spezifische Styleguide-Regeln führt in der Praxis zu einer weiteren Frage: Was soll der Anwender mit einem Hinweis auf einen Verstoß tun?

Ein Styleguide ist nur dann wirksam, wenn die empfohlene Lösung im Arbeitsprozess leicht erreichbar ist. Wer für jede Warnung erst eine Dokumentation öffnen, ein Attribut im richtigen Namespace setzen oder eine komplexe XML-Struktur von Hand aufbauen muss, wird die Regel früher oder später umgehen. Schematron QuickFix setzt hier an: Zu einer Meldung werden konkrete Korrektur- oder Erzeugungsaktionen angeboten.

Damit verschiebt sich die Rolle des Styleguides. Er ist nicht mehr nur ein Dokument, das außerhalb des Editors gelesen werden muss, und auch nicht nur eine Prüfliste am Ende eines Prozesses. Er wird zu einem aktiven Bestandteil des Authoring-Workflows. Die fachliche Regel, die technische Prüfung und die empfohlene Korrektur liegen am selben Ort: direkt an der betroffenen Stelle im XML-Dokument.

Der Vorteil ist besonders groß, wenn Regeln nicht offensichtlich sind. Viele XML-Vorgaben sind nicht falsch oder richtig im Sinne eines Standards, sondern projektspezifisch, zum Beispiel: 

• Welche XSD-Architektur soll verwendet werden? 
• Welche DITA-Strukturen sind redaktionell erwünscht? 
• Welche Layout-Hilfen dürfen benutzt werden, und in welcher Form? 

Genau solche Vereinbarungen lassen sich mit Schematron und SQF sehr nah an die tägliche Arbeit bringen.

Die folgenden zwei Beispiele zeigen unterschiedliche Ausprägungen dieses Prinzips:

• Ein XSD Guide führt Entwickler dabei, ein XML Schema nach einem gewählten Design-Pattern aufzubauen.
• Ein DITA-Redaktionsmenü bietet Redakteuren konfigurierbare Einfügeaktionen für Layout- und Inhaltsbausteine.

Beispiel 1: XSD Guide als interaktiver Styleguide

XML Schema erlaubt viele Wege, dieselbe Struktur auszudrücken. Ein Team kann sich zum Beispiel auf ein Design-Pattern wie Venetian Blind oder Salami Slice einigen. Daneben gibt es weitere verbreitete Stile wie Russian Doll. Die Herausforderung besteht darin, diese Vereinbarung im Alltag konsistent umzusetzen, auch wenn nicht alle Beteiligten XSD-Spezialisten sind.

Die Unterschiede zwischen diesen Stilen sind für die Wartbarkeit entscheidend. Venetian Blind arbeitet typ-orientiert: Wurzelelemente werden global deklariert, die eigentliche Struktur steckt in benannten globalen xs:complexType- und xs:simpleType-Definitionen. Das ist sinnvoll, wenn Typen wiederverwendet, erweitert oder in größeren Schemata gezielt referenziert werden sollen. Salami Slice ist element-orientiert: Elemente werden global deklariert und an anderen Stellen per @ref verwendet. Das passt, wenn Elementnamen und wiederverwendbare Elementdeklarationen im Vordergrund stehen. Russian Doll geht den umgekehrten Weg und verschachtelt die Struktur weitgehend lokal in einem globalen Root-Element. Das ist übersichtlich für kleine, kompakte Schemata, bietet aber weniger Wiederverwendung.

Problematisch wird es, wenn diese Stile unkontrolliert gemischt werden. Dann enthält ein Schema zugleich globale Typen, globale Elemente, lokale Inline-Typen und referenzierte Elemente, ohne dass klar ist, welche Modellierungsentscheidung dahintersteht. Für Wartung, Review, Erweiterung und Dokumentation ist das ungünstig, weil man jedes Schema erneut interpretieren muss. Genau hier setzt der XSD Guide an: Er macht den gewählten Stil explizit und führt den Anwender durch die dazu passenden nächsten Schritte.

Der XSD Guide löst das in zwei Schritten. Erstens prüft Schematron, ob das Schema zum gewählten Pattern passt. Zweitens erzeugen SQF-Aktionen die passenden XSD-Strukturen. Der Anwender trifft fachliche Entscheidungen, etwa welches Root-Element entstehen soll. Der QuickFix erzeugt daraus die technische XML-Struktur.

Der Nutzen liegt also nicht darin, XSD-Wissen vollständig zu ersetzen. Vielmehr wird der Einstieg standardisiert. Wiederkehrende Entscheidungen werden geführt, typische Flüchtigkeitsfehler vermieden und die Projektkonvention wird direkt in ausführbare Editor-Aktionen übersetzt. Gerade bei Teams mit unterschiedlicher XSD-Erfahrung sorgt das für konsistentere Schemata und für weniger Abstimmungsaufwand im Review.

Aktivierung über Konfiguration im XSD

Ausgangspunkt ist ein leeres Schema:

Der Guide meldet zunächst, dass er inaktiv ist. Der angebotene QuickFix ergänzt eine Konfiguration innerhalb von xs:annotation/xs:appinfo:

Damit wird der Bearbeitungszustand nicht außerhalb des Dokuments, sondern direkt im XSD festgehalten. Das Schematron kann darauf reagieren:

Das leere <sch:rule>-Element ist hier ein Steuermechanismus: Ist der Guide inaktiv, werden die übrigen Regeln dieses Patterns nicht wirksam. SQF verändert also das Dokument so, dass das Schematron anschließend anders arbeitet.

Dieses Prinzip ist wichtig: Der Guide arbeitet zustandsbasiert. Sämtliche Meta-Informationen, die erfasst werden (z.B. ob der Guide aktiv ist und welches Design-Pattern gewählt wurde), werden im Dokument selbst abgelegt. Verwendet wird hierzu das Annotations-Modell von XSD — das XSD-Schema ist also stets valide und trotzdem bleibt der Bearbeitungszustand immer erhalten und nachvollziehbar, auch wenn die Datei an eine andere Person weitergegeben oder später erneut geöffnet wird. Es ist keine separate Editor-Einstellung und kein Wissen im Kopf des Bearbeiters erforderlich.

Auswahl eines Design-Patterns

Nach der Aktivierung muss der Anwender ein Grundmuster wählen. Damit diese Information nicht manuell in eine Konfiguration geschrieben werden muss, bietet das Schematron zwei QuickFixes an:

Nach der Aktivierung bietet der XSD Guide die Auswahl des Design-Patterns direkt als QuickFix an. In der Beispiel-Abbildung ist „Venetian Blind wählen“ markiert. Der Hilfetext erklärt, dass globale Typen erzeugt und lokale Elemente diese Typen referenzieren.

Die Auswahl wird als @mode gespeichert:

Danach lassen sich Pattern-spezifische Regeln ein- und ausblenden:

Für den Anwender bleibt die Entscheidung einfach: Er wählt ein Pattern aus dem QuickFix-Menü. Für das Schematron ist diese Entscheidung anschließend auswertbar. Regeln und QuickFixes können abhängig von @mode unterschiedlich reagieren. Ein und dieselbe fachliche Aktion, zum Beispiel „Root-Element definieren“, kann intern also unterschiedliche XML-Strukturen erzeugen, je nachdem welches Architekturmodell gewählt wurde.

Freitext-Eingaben und generierte XSD-Strukturen

Nicht jede Entscheidung ist eine Auswahl aus festen Werten. Für den Namen eines Root-Elements wird ein sqf:user-entry verwendet. Der Anwender gibt den Namen ein, SQF erzeugt die passende Struktur:

Damit wird aus einer Styleguide-Regel ein geführter Dialog: Der Anwender entscheidet fachlich, der QuickFix erzeugt konsistenten XSD-Code.

Für Venetian Blind kann der QuickFix beispielsweise ein globales Element mit @type und zusätzlich einen globalen xs:complexType erzeugen. Für Salami Slice kann derselbe Arbeitsschritt stattdessen ein globales Element mit inline-definiertem Inhaltsmodell erzeugen. Aus Sicht des Anwenders ist beides eine Entscheidung über das Root-Element. Aus Sicht des Styleguides sind es zwei unterschiedliche, aber regelkonforme Code-Templates.

Ist ein Design-Pattern gewählt, meldet das Schematron den nächsten sinnvollen Schritt: Es fehlt ein Root-Element. Der Dialog zeigt den praktischen Nutzen von sqf:user-entry: Der Anwender trifft eine fachliche Namensentscheidung, während SQF daraus die passende XSD-Struktur für das gewählte Pattern erzeugt.

Bei Salami Slice bleibt die Oberfläche ähnlich, aber der Hilfetext und der erzeugte Code unterscheiden sich. Der QuickFix erzeugt hier ein globales Element mit lokalem Inhaltsmodell statt eines globalen Elements mit referenziertem Typ.

Warum der XSD Guide hilfreich ist

Der XSD Guide macht die gewünschte Modellierungsweise explizit und ausführbar. Das hat mehrere praktische Vorteile:

• Neue Projektmitglieder können produktiv arbeiten, ohne zuerst alle XSD-Konventionen im Detail zu kennen.
• Reviews werden entlastet, weil der Guide einfache Strukturentscheidungen bereits während der Bearbeitung absichert.
• Die erzeugten Strukturen sind einheitlicher, weil sie aus denselben QuickFix-Templates stammen.
• Die gewählte Modellierungsstrategie bleibt im Dokument sichtbar und kann später wieder ausgewertet werden.
• Der Styleguide wird nicht erst am Ende geprüft, sondern begleitet die Entstehung des Schemas Schritt für Schritt.

Besonders interessant ist dabei die Kombination aus Kontrolle und Generierung. Schematron erkennt, dass ein nächster Modellierungsschritt fehlt. SQF bietet eine konkrete Aktion an. Nach dem Ausführen ändert sich der Dokumentzustand, und das Schematron kann den nächsten sinnvollen Hinweis anzeigen. Dadurch entsteht eine einfache, aber wirkungsvolle Form der Benutzerführung.

Demo-Dateien für Oxygen

Für eine kurze Vorführung liegen Beispiel-Dateien zum Download bereit. Sie zeigen den Ablauf vom leeren XSD über die Aktivierung bis zu den erzeugten Root-Elementen in zwei Design-Patterns:

• beispiele/xsd-guide/01-start.xsd ist der Einstieg für die SQF-Demo in Oxygen.
• beispiele/xsd-guide/sch/xsd-guide-demo.sch enthält eine kleine Demo-Implementierung der QuickFix-Führung.
• beispiele/xsd-guide/03-venetian-blind-mit-root.xsd zeigt das erwartete Ergebnis für Venetian Blind.
• beispiele/xsd-guide/04-salami-slice-mit-root.xsd zeigt das erwartete Ergebnis für Salami Slice.

Die Demo-Dateien zeigen nur einen stark vereinfachten Ausschnitt.

Eine weiterführende Implementierung des XSD Guides ist als Open-Source-Projekt verfügbar: github.com/nkutsche/xsdguide. Dort liegt eine einsetzbare Implementierung aus Schematron, Schematron QuickFix und XSLT, die sich über die Add-on-Funktion von Oxygen XML Editor oder über das Escali-Oxygen-Plugin installieren lässt.

Beispiel 2: Konfigurierbares DITA-Menü für Redaktionen

Das zweite Beispiel überträgt dasselbe Prinzip auf redaktionelle Arbeit in DITA. Redakteure sollen nicht jedes gewünschte Konstrukt von Hand schreiben müssen. Stattdessen tippen sie ein Kürzel in den Text, etwa ###, und Oxygen bietet über Schematron QuickFix passende Einfügeaktionen an:

• Bild mit Textumfluss, 
• Boxen, 
• mehrspaltige Bereiche oder 
• Tabellen.

Die Motivation ist hier eine andere als beim XSD Guide, aber das Grundproblem ist ähnlich. In redaktionellen DITA-Umgebungen müssen häufig komplexe, aber wiederkehrende Strukturen eingefügt werden: 

• Tabellen mit bestimmtem Aufbau, 
• Boxen mit definierten Titeln, 
• Abbildungscontainer, 
• Processing Instructions für den Umbruch oder
• projektabhängige Layoutbausteine. 

Ohne Führung müssten Redakteure viele einzelne Elemente nacheinander auswählen, verschachteln und mit den richtigen Attributen versehen. Das ist fehleranfällig und lenkt von der eigentlichen redaktionellen Arbeit ab.

Natürlich könnte man dafür auch den Oxygen XML Editor selbst anpassen, etwa über Framework-Erweiterungen, Author Actions oder Plugins. Der hier gezeigte Ansatz ist bewusst leichtgewichtiger: Die Funktionalität steckt in Schematron QuickFix und einer Konfigurationsdatei. Damit kann man komplexen Strukturen fachliche Namen geben und sie als Menüeinträge anbieten, ohne eine editor-spezifische Erweiterung programmieren zu müssen.

Im Beispieldokument ist das Schematron direkt per Oxygen Processing Instruction eingebunden:

<?oxygen SCHSchema="sqf_dita_template_generator/sch/shortcut.sch"?>

Im folgenden Screenshot sieht man die Wirkung: Beim Kürzel ### öffnet Oxygen ein QuickFix-Menü mit redaktionellen Optionen wie „Bildpositionierung links“, „Boxen“ oder „Einfügen Box: Aufgabe“.

Das DITA-Beispiel zeigt die Benutzerführung im Redaktionsalltag: Aus einem Kürzel im Text entsteht ein QuickFix-Menü mit fachlich benannten Aktionen. Die Redakteurin wählt etwa eine Bildpositionierung oder eine Box aus; das dahinterliegende DITA-Fragment wird durch SQF eingefügt.

Der redaktionelle Vorteil liegt auf der Hand: Redakteure müssen nicht wissen, welche DITA-Struktur hinter einem bestimmten Layout- oder Inhaltsbaustein steht. Sie wählen die fachlich benannte Aktion aus. Das XML bleibt trotzdem strukturiert, kontrollierbar und wiederverwendbar.

Ein weiterer Vorteil ist die geringere Versionsabhängigkeit. Die Lösung hängt nicht an einer bestimmten Oxygen-Version oder an einer proprietären Plugin-Schnittstelle, sondern nutzt den QuickFix-Standard, den Oxygen unterstützt. Prinzipiell ist ein solcher Ansatz damit auch in andere Editoren übertragbar, sofern diese Schematron QuickFix oder vergleichbare Mechanismen unterstützen.

Die technische Lösung: Schematron liest eine externe Konfiguration

Der zentrale Punkt ist, dass die Menüeinträge nicht fest in die Schematron-Regeln programmiert sind. Das Schematron lädt eine externe Konfigurationsdatei:

Eine Schematron-Rule prüft Textknoten, ob eines der konfigurierten Kürzel vorkommt. Für jede gefundene Option erzeugt @use-for-each einen eigenen QuickFix:

Die Logik ist generisch: Das Kürzel wird durch den XML-Inhalt aus <insert-fragment> ersetzt. Der angezeigte Menütext kommt aus <description>. Hilfetexte kommen aus <about>. Verschachtelte Optionen werden über die berechnete Ebene mit --- sichtbar gemacht.

Damit wird das Schematron zu einer Art Laufzeit für konfigurierte Redaktionsaktionen. Es muss nicht für jede Box, Tabelle oder Processing Instruction eine eigene Rule geschrieben werden. Die Rule beschreibt nur den Mechanismus: Kürzel erkennen, passende Optionen suchen, Beschreibung anzeigen, Fragment einsetzen.

Konfiguration statt Programmieraufwand

Ein Menüpunkt für Bildpositionierung ist in der Konfiguration als Datenstruktur beschrieben:

Ein weiteres Beispiel sind Boxen. Die Redaktionsoberfläche kann eine ganze Gruppe von Bausteinen anbieten, ohne dass für „Aufgabe“, „Beispiel“, „Definition“ oder „Übung“ jeweils neue Schematron-Programmierung nötig ist:

Die Platzhalter ##Box-Titel## und ##Box-Pfad## lösen anschließend weitere Schematron-Meldungen mit entsprechenden QuickFixen aus. So entsteht eine mehrstufige Benutzerführung: Zuerst wird die Box eingefügt, danach fordert Oxygen den Redakteur auf, Titel oder Bildpfad zu klären.

Generisch erweiterbar

Der entscheidende Vorteil dieses DITA-Menüs ist seine Erweiterbarkeit. Soll ein neuer Baustein angeboten werden, muss in vielen Fällen nur ein weiterer <option>-Eintrag in der Konfiguration ergänzt werden. Die Schematron-Regel bleibt gleich, weil sie alle passenden Optionen generisch verarbeitet.

Ein zusätzlicher Menüpunkt könnte zum Beispiel so aussehen:

Damit wird aus einem Schematron-Schema ein konfigurierbares Redaktionswerkzeug. Fachliche Vorgaben können von Projekt zu Projekt angepasst werden, ohne den QuickFix-Mechanismus neu zu programmieren.

Das ist gerade für Redaktionsumgebungen wertvoll, in denen sich Vorgaben ändern. Neue Boxentypen, projektabhängige Layoutbausteine oder erlaubte Processing Instructions können in der Konfiguration ergänzt werden. Die Anwender sehen danach neue Menüeinträge im Oxygen XML Editor, ohne dass sie ihre Arbeitsweise ändern müssen.

Damit wird die Konfiguration zur fachlichen Oberfläche des Systems. Ein Baustein bekommt einen verständlichen Namen, eine kurze Beschreibung und ein einzufügendes XML-Fragment. Die technische Struktur bleibt kontrolliert, aber die Pflege ist näher an der fachlichen Vorgabe als an der Editor-Programmierung. Für Projekte, die ihre redaktionellen Muster regelmäßig anpassen, ist das ein erheblicher Vorteil.

Dynamische Tabellen per Muster

Neben statischen Fragmenten zeigt das Beispiel auch dynamische Erzeugung. Gibt der Redakteur ein Muster wie ##3x4## ein, kann daraus automatisch eine Tabelle mit drei Zeilen und vier Spalten entstehen:

Hier wird SQF mit XSLT-Logik kombiniert, um aus einer kompakten redaktionellen Eingabe eine vollständige DITA-Tabellenstruktur zu erzeugen.

Was beide Beispiele gemeinsam zeigen

Beide Ansätze nutzen Schematron nicht nur als Kontrollinstanz, sondern als Interaktionsschicht im Editor. Die Regel erkennt einen Zustand im Dokument. SQF bietet dazu eine passende Aktion. Die Aktion verändert das Dokument. Anschließend bewertet Schematron den neuen Zustand erneut.

Dadurch entsteht eine leichte, dokumentennahe Benutzerführung:

• Styleguide-Regeln werden unmittelbar am relevanten Kontext sichtbar.
• Anwender müssen technische Details wie Namespaces, Attribute oder XML-Fragmente nicht auswendig kennen.
• Entscheidungen werden im Dokument oder in einer Konfiguration festgehalten.
• Wiederkehrende Strukturen entstehen konsistent, nachvollziehbar und mit erheblich weniger redaktionellem Aufwand.
• Das DITA-Menü lässt sich über Konfiguration erweitern, ohne die generische Schematron-Logik anzufassen.

Aus organisatorischer Sicht entsteht dadurch eine Brücke zwischen Regelwerk und Werkzeug. Der Styleguide bleibt nicht abstrakt, sondern wird als konkrete Handlung angeboten. Das reduziert Schulungsaufwand, weil die relevanten Optionen im Moment der Bearbeitung sichtbar sind. Es reduziert Fehler, weil wiederkehrende XML-Fragmente nicht jedes Mal von Hand gebaut werden. Und es erleichtert die Pflege, weil fachliche Änderungen an einer zentralen Stelle umgesetzt werden können.

Technisch ist der Ansatz leichtgewichtig. Es wird kein eigenes Editor-Plugin benötigt, solange die gewünschte Interaktion mit Schematron und SQF abbildbar ist. Die Lösung nutzt Mechanismen, die im Oxygen XML Editor bereits vorhanden sind: 

• Schematron-Validierung, 
• QuickFix-Menüs, 
• User-Entries und 
• XPath/XSLT-Ausdrücke. 

Dadurch bleibt sie transparent und gut wartbar.

Gerade für Teams, die XML-Strukturen fachlich beherrschen müssen, aber nicht jeden Tag Schematron, SQF oder XSD programmieren, ist das ein pragmatischer Weg: Der Styleguide bleibt formal prüfbar, wird aber zugleich zu einem Werkzeug, das beim Schreiben und Modellieren aktiv hilft.