Umfragen mit QML erstellen
Diese Anleitung erklärt, wie Sie Umfragen mit QML (Questionnaire Markup Language) erstellen, einer YAML-basierten Sprache für anspruchsvolle Fragebögen mit formaler Verifikation, dynamischer Ablaufsteuerung und Datenvalidierung.

Der Browser-Editor von Armiger: links der Projekt-Explorer und der Chat KI-Generierung, in der Mitte der QML-Code, rechts das Ablaufdiagramm und eine Live-Vorschau der ausgewählten Frage.
Schnellstart
Abschnitt betitelt „Schnellstart“Jeder QML-Fragebogen beginnt mit dieser Struktur:
qmlVersion: "2.0"questionnaire: title: "Your Survey Title" blocks: - id: b_first_section title: "First Section" items: - id: q_first_question kind: Question title: "Your first question" input: control: Radio labels: 1: "Option 1" 2: "Option 2"Das Feld qmlVersion gibt die QML-Hauptversion an, für die Ihr Dokument geschrieben ist. Die aktuelle Hauptversion ist 2; schreiben Sie also "2.0" (oder "2.1", um die neuesten optionalen Funktionen zu nutzen). Dokumente für die alte 1.x-Grammatik werden nicht mehr geladen und müssen migriert werden. Die vollständige Grammatik, alle Item-Arten und die erweiterten Blöcke finden Sie in der QML-Syntaxreferenz.
Grundbegriffe
Abschnitt betitelt „Grundbegriffe“Blöcke: Ihre Umfrage gliedern
Abschnitt betitelt „Blöcke: Ihre Umfrage gliedern“Ein Block hat drei Aufgaben:
- Gruppieren: Er fasst zusammengehörige Fragen zu einem Abschnitt zusammen.
- Verzweigen: Seine Vorbedingung steuert jede Frage darin, sodass eine einzige Bedingung entscheidet, ob eine befragte Person den gesamten Abschnitt sieht.
- Wiederholen: Ein
Roster-Block stellt seine Fragen einmal pro ausgewählter Einheit (siehe Erweiterte Blockarten).
Die einfachste Verwendung ist das Gruppieren:
blocks: - id: b_demographics title: "About You" items: # Questions about the respondent
- id: b_preferences title: "Your Preferences" items: # Questions about preferencesVorbedingungen auf Blockebene
Abschnitt betitelt „Vorbedingungen auf Blockebene“Blöcke können eigene Vorbedingungen haben. Hat ein Block eine Vorbedingung, gilt sie automatisch für jedes Item in diesem Block; Sie müssen dieselbe Bedingung also nicht bei jeder Frage wiederholen.
blocks: - id: b_employment title: "Employment Details" precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50In diesem Beispiel erben sowohl q_job_title als auch q_years_employed die Blockvorbedingung q_employed.outcome == 1. Items können zusätzlich eigene Vorbedingungen festlegen; die Blockvorbedingung wird dann mit den Vorbedingungen auf Item-Ebene kombiniert.
Bewährte Vorgehensweisen:
- Verwenden Sie aussagekräftige IDs, die mit
b_beginnen (z. B.b_demographics,b_experience) - Gruppieren Sie thematisch zusammengehörige Fragen
- Halten Sie Abhängigkeiten nach Möglichkeit innerhalb von Blöcken
- Teilen sich zwei oder mehr Fragen eine Sichtbarkeitsbedingung, legen Sie sie in einen eigenen Block und schreiben Sie die Bedingung einmal an den Block; eine Vorbedingung auf Item-Ebene behalten Sie nur für eine Bedingung, die allein diese Frage betrifft
- Eine Blockvorbedingung liest Antworten und Variablen aus Fragen vor dem Block; platzieren Sie den Block daher nach der Frage, die über ihn entscheidet
Erweiterte Blockarten
Abschnitt betitelt „Erweiterte Blockarten“Standardmäßig ist ein Block eine Group, die jedes ihrer Items einmal stellt. Zwei optionale Varianten decken dynamischere Umfragen ab:
- Wiederholte Abschnitte (
Roster): Eine Gruppe von Fragen wird einmal pro ausgewähltem Eintrag wiederholt (zum Beispiel dieselben Angaben zu jeder Mahlzeit, die eine befragte Person gegessen hat, oder zu jedem Familienmitglied). - Adaptive Auswahl (
count): EineGroupwird so begrenzt, dass sie nur die ersten N zulässigen Items stellt (zum Beispiel 3 Fragen aus einem größeren Pool).
Beide werden ausführlich und mit Beispielen in der QML-Syntaxreferenz behandelt.
Items: Arten von Fragen
Abschnitt betitelt „Items: Arten von Fragen“QML unterstützt vier Item-Typen:
1. Comment (Hinweise)
Abschnitt betitelt „1. Comment (Hinweise)“Zeigt Text an, ohne Antworten zu erfassen:
- id: q_intro kind: Comment title: "Please answer honestly. Your responses are confidential."2. Question (eine Antwort)
Abschnitt betitelt „2. Question (eine Antwort)“Stellt eine Frage und erfasst eine Antwort:
- id: q_age kind: Question title: "What is your age?" input: control: Editbox min: 18 max: 1203. QuestionGroup (mehrere zusammengehörige Fragen)
Abschnitt betitelt „3. QuestionGroup (mehrere zusammengehörige Fragen)“Stellt mehrere Fragen mit demselben Antwortformat:
- id: q_satisfaction kind: QuestionGroup title: "Rate your satisfaction with:" questions: - "Customer service" - "Product quality" - "Delivery speed" input: control: Radio labels: 1: "Very Dissatisfied" 2: "Dissatisfied" 3: "Neutral" 4: "Satisfied" 5: "Very Satisfied"4. MatrixQuestion (Raster)
Abschnitt betitelt „4. MatrixQuestion (Raster)“Erfasst Antworten in einem Format aus Zeilen und Spalten:
- id: q_skills kind: MatrixQuestion title: "Rate your proficiency in:" rows: - "Python" - "JavaScript" - "SQL" columns: - "Beginner" - "Intermediate" - "Advanced" input: control: Radio labels: 1: "No experience" 2: "Some experience" 3: "Proficient"Eingabeelemente
Abschnitt betitelt „Eingabeelemente“Jede Frage muss angeben, wie Antworten erfasst werden.
Switch (Ja/Nein)
Abschnitt betitelt „Switch (Ja/Nein)“Binäre Auswahl:
input: control: Switch on: "Yes" off: "No"Radio (eine Option wählen)
Abschnitt betitelt „Radio (eine Option wählen)“Auswahl genau einer Option aus mehreren:
input: control: Radio labels: 1: "Option A" 2: "Option B" 3: "Option C"Checkbox (mehrere Optionen wählen)
Abschnitt betitelt „Checkbox (mehrere Optionen wählen)“Auswahl beliebig vieler Optionen, auch keiner:
input: control: Checkbox labels: 1: "Feature A" 2: "Feature B" 4: "Feature C" 8: "Feature D"Dropdown (aus einer Liste wählen)
Abschnitt betitelt „Dropdown (aus einer Liste wählen)“Platzsparende Auswahl aus vielen Optionen:
input: control: Dropdown labels: 1: "High School" 2: "Bachelor's" 3: "Master's" 4: "PhD" left: "Education:"Editbox (Zahleneingabe)
Abschnitt betitelt „Editbox (Zahleneingabe)“Freie Eingabe einer Zahl:
input: control: Editbox min: 0 max: 1000000 left: "Annual income: $"Slider (visuelle Skala)
Abschnitt betitelt „Slider (visuelle Skala)“Visuelle Auswahl entlang einer Skala:
input: control: Slider min: 0 max: 10 step: 1 labels: 0: "Not at all" 5: "Somewhat" 10: "Extremely"Range (Intervallauswahl)
Abschnitt betitelt „Range (Intervallauswahl)“Auswahl eines Intervalls mit zwei Reglern (von–bis). Die Antwort ist ein Paar [low, high] mit min <= low <= high <= max.
input: control: Range min: 0 max: 100 step: 5 labels: 0: "Minimum" 50: "Mid" 100: "Maximum" default: [20, 80]Textarea (Freitext)
Abschnitt betitelt „Textarea (Freitext)“Für offene, qualitative Antworten verwenden Sie Textarea. Anders als bei allen anderen Eingabeelementen ist das Ergebnis ein String und keine ganze Zahl; es steht daher weder für Verzweigungslogik noch für die formale Verifikation zur Verfügung (wer ein Textarea-Ergebnis in einer Vorbedingung, einer Nachbedingung oder einem Codeblock verwendet, macht einen Entwurfsfehler). Nutzen Sie es für Kommentare, Vorschläge oder Erläuterungen, die Sie später lesen oder codieren wollen.
input: control: Textarea placeholder: "Tell us more..." maxLength: 500Sowohl placeholder (Hinweistext, solange das Feld leer ist) als auch maxLength (Zeichengrenze) sind optional.
Bedingte Logik
Abschnitt betitelt „Bedingte Logik“Fragen bedingt anzeigen (Vorbedingungen)
Abschnitt betitelt „Fragen bedingt anzeigen (Vorbedingungen)“Mit Vorbedingungen zeigen Sie Fragen abhängig von früheren Antworten an:
- id: q_has_car kind: Question title: "Do you own a car?" input: control: Switch
- id: q_car_brand kind: Question title: "What brand is your car?" precondition: - predicate: q_has_car.outcome == 1 input: control: Dropdown labels: 1: "Toyota" 2: "Honda" 3: "Ford"Die Frage q_car_brand erscheint nur, wenn die befragte Person die Frage nach einem eigenen Auto mit „Ja“ beantwortet hat.
Komplexe Vorbedingungen:
precondition: - predicate: q_age.outcome >= 25 and q_employment.outcome in [1, 2, 3]Die Verzweigungen sehen: die Baumansicht des Diagramms
Abschnitt betitelt „Die Verzweigungen sehen: die Baumansicht des Diagramms“Das Ablaufdiagramm neben Ihrem QML hat zwei Ansichten, zwischen denen Sie oben links mit Ablauf und Baum umschalten.
- Ablauf (Standard) zeigt jede Frage in der Reihenfolge, in der das Interview sie stellt, mit ihren Bedingungen daneben.
- Baum zeigt dieselben Fragen als Verzweigungen. Fragen mit derselben Bedingung, ob sie nun an ihrem Block steht oder bei jeder Frage wiederholt wird, bilden einen Zweig, und ein Zweig, dessen Bedingung nur innerhalb eines anderen gelten kann, wird in diesem dargestellt. Die Ja- und Nein-Pfade einer Screening-Frage erscheinen nebeneinander, und eine Folgefrage, die nur auf dem Ja-Pfad gestellt wird, ist darin verschachtelt.
Die Beziehungen werden mit Z3 bewiesen, nicht aus dem Text erraten. Der Baum wird berechnet, wenn Sie zu ihm wechseln; das erste Umschalten dauert daher einen Moment. Lässt er sich nicht berechnen, bleibt das Diagramm in der Ansicht Ablauf und nennt den Grund. Jeder Zweig ist mit dem beschriftet, was Z3 festgestellt hat:
| Markierung | Bedeutung |
|---|---|
| entweder/oder | Dieser Zweig und sein Nachbar können nie beide zutreffen: Die befragte Person nimmt den einen oder den anderen Pfad |
| parallel | Beide können für dieselbe befragte Person zutreffen: optionale Abschnitte, die beide gestellt werden können |
| ? exklusiv, ? verschachtelt, ? erfüllt | Z3 konnte nicht entscheiden (zum Beispiel bei einer Bedingung, die es nicht vollständig ausdrücken kann, oder bei einer, die eine Antwort oder einen berechneten Wert zu zwei verschiedenen Zeitpunkten des Interviews betrifft): Der Zweig wird dort angezeigt, wo er bewiesen ist, und die Markierung nennt, was offen ist |
| nie / immer | Die Bedingung des Zweigs kann nie zutreffen bzw. trifft immer zu |
Zwei Fragen mit demselben Bedingungstext bilden nur dann einen Zweig, wenn die Bedingung für beide dasselbe bedeutet: Ändert ein Codeblock zwischen ihnen eine Variable, die die Bedingung liest, erhält jede ihren eigenen Zweig.
Nachbedingungen verzweigen nicht; sie bleiben daher in beiden Ansichten neben ihren Fragen.
Antworten validieren (Nachbedingungen)
Abschnitt betitelt „Antworten validieren (Nachbedingungen)“Mit Nachbedingungen stellen Sie logische Konsistenz sicher:
- id: q_household_size kind: Question title: "How many people live in your household?" input: control: Editbox min: 1 max: 20
- id: q_children kind: Question title: "How many children under 18 live in your household?" postcondition: - predicate: q_children.outcome < q_household_size.outcome hint: "Number of children must be less than household size" input: control: Editbox min: 0 max: 15Gibt eine befragte Person ungültige Daten ein (z. B. 5 Kinder in einem Haushalt mit 3 Personen), wird der Hinweistext angezeigt.
Codeblöcke und Variablen
Abschnitt betitelt „Codeblöcke und Variablen“QML erlaubt eingebetteten Python-Code für Berechnungen und dynamische Logik.
Variablen initialisieren
Abschnitt betitelt „Variablen initialisieren“Mit codeInit legen Sie Hilfsvariablen an, etwa Zähler:
questionnaire: codeInit: | total_score = 0 risk_level = 0Nach Antworten berechnen
Abschnitt betitelt „Nach Antworten berechnen“Hängen Sie Codeblöcke an Items, um Berechnungen auszuführen:
- id: q_satisfaction kind: Question title: "Rate your overall satisfaction (0-10)" codeBlock: | # Calculate satisfaction category if q_satisfaction.outcome >= 9: satisfaction_category = 3 # Promoter elif q_satisfaction.outcome >= 7: satisfaction_category = 2 # Passive else: satisfaction_category = 1 # Detractor
# Add to running total total_score += q_satisfaction.outcome input: control: Slider min: 0 max: 10Unterstützter Python-Sprachumfang
Abschnitt betitelt „Unterstützter Python-Sprachumfang“QML-Code läuft in einer Sandbox, aber nur ein Teil von Python lässt sich in das formale (Z3-)Modell übersetzen, das Ihren Fragebogen verifiziert. Bleiben Sie innerhalb dieser Teilmenge, damit Ihre Logik von der Verifikation abgedeckt ist:
✓ Verifizierte Teilmenge:
- Arithmetik:
+,-,*,//,% - Vergleiche:
<,<=,>,>=,==,!=(auch verkettet, z. B.0 < x < 10) - Zugehörigkeit:
in,not in(z. B.q_x.outcome in [1, 2, 3]) - Boolesche Logik:
and,or,not - Bedingungen:
if,elif,else - Ternäre Ausdrücke:
x = 1 if condition else 0 - For-Schleifen:
for i in range(n)(n ≤ 20) - Literale für Listen, Tupel und Mengen (≤ 20 Elemente)
- Tupel-Entpacken:
a, b = 1, 0 - Variablenzuweisung:
x = value,x += value - Integrierte Funktionen:
range(),abs(),int(),bool() - Zugriff auf Ergebnisse:
q_age.outcome
✗ Außerhalb der verifizierten Teilmenge (siehe Hinweis unten):
- Importe, Funktionen, Klassen
- While-Schleifen,
break,continue - Operationen mit Dictionaries
- String-Methoden
- List Comprehensions
- Print-Anweisungen (werden stillschweigend ignoriert)
Häufige Muster
Abschnitt betitelt „Häufige Muster“Schrittweises Einblenden
Abschnitt betitelt „Schrittweises Einblenden“Zeigen Sie Fragen schrittweise abhängig von früheren Antworten an. Mit Vorbedingungen auf Blockebene vermeiden Sie, dieselbe Bedingung bei jedem Item zu wiederholen:
- id: b_screening items: - id: q_employed kind: Question title: "Are you currently employed?" input: control: Switch
- id: b_employment precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50Sowohl q_job_title als auch q_years_employed erben automatisch die Vorbedingung des Blocks; sie erscheinen nur, wenn die befragte Person erwerbstätig ist.
Punktwertung und Kategorisierung
Abschnitt betitelt „Punktwertung und Kategorisierung“Berechnen Sie Punktwerte und ordnen Sie Befragte Kategorien zu:
questionnaire: codeInit: | risk_score = 0
blocks: - id: b_assessment items: - id: q_factor1 kind: Question title: "Do you smoke?" codeBlock: | if q_factor1.outcome == 1: risk_score += 20 input: control: Switch
- id: q_factor2 kind: Question title: "Do you exercise regularly?" codeBlock: | if q_factor2.outcome == 0: risk_score += 15 input: control: Switch
- id: q_result kind: Comment title: "Assessment complete" codeBlock: | if risk_score >= 30: risk_category = "high" elif risk_score >= 15: risk_category = "moderate" else: risk_category = "low"Validierung der Datenqualität
Abschnitt betitelt „Validierung der Datenqualität“Sichern Sie die Antwortqualität durch Validierung über mehrere Items hinweg:
- id: q_age kind: Question title: "Your age" input: control: Editbox min: 18 max: 100
- id: q_work_experience kind: Question title: "Years of work experience" postcondition: - predicate: q_work_experience.outcome <= (q_age.outcome - 16) hint: "Work experience cannot exceed your potential working years" input: control: Editbox min: 0 max: 60Bewährte Vorgehensweisen
Abschnitt betitelt „Bewährte Vorgehensweisen“Fragengestaltung
Abschnitt betitelt „Fragengestaltung“- Seien Sie konkret: „Wie hoch ist Ihr jährliches Haushaltseinkommen?“ statt „Einkommen?“
- Wählen Sie passende Eingabeelemente: Editbox für genaue Zahlen, Slider für subjektive Bewertungen
- Legen Sie realistische Wertebereiche fest: min/max sollten reale Gegebenheiten widerspiegeln
- Geben Sie Kontext: Nutzen Sie Text in
left/rightfür Einheiten und Erläuterungen
Abhängigkeiten verwalten
Abschnitt betitelt „Abhängigkeiten verwalten“- Halten Sie zusammengehörige Items zusammen im selben Block
- Die Reihenfolge zählt: Fragen müssen erscheinen, bevor auf sie verwiesen wird
- Testen Sie alle Pfade: Stellen Sie sicher, dass jede Frage erreichbar ist
Validierungsstrategie
Abschnitt betitelt „Validierungsstrategie“- Legen Sie Wertebereiche über min/max des Eingabeelements fest
- Verwenden Sie Nachbedingungen für logische Konsistenz
- Geben Sie hilfreiche Hinweise: Klare Fehlermeldungen leiten Befragte an
- Denken Sie an Grenzfälle: Was passiert, wenn jemand Extremwerte eingibt?
Richtlinien für Codeblöcke
Abschnitt betitelt „Richtlinien für Codeblöcke“- Initialisieren Sie früh: Legen Sie Variablen in
codeInitan - Halten Sie es einfach: Komplexe Berechnungen sind schwer zu debuggen
- Denken Sie an den Gültigkeitsbereich: Alle Variablen sind global
- Testen Sie gründlich: Lassen Sie den Fragebogen-Validator laufen
Formale Verifikation
Abschnitt betitelt „Formale Verifikation“QML-Fragebögen werden automatisch geprüft auf:
- Erreichbarkeit: Lässt sich jede Frage erreichen?
- Konsistenz: Sind die Validierungsregeln erfüllbar?
- Zyklen: Bilden Abhängigkeiten Zyklen?
- Vollständigkeit: Gibt es mindestens einen gültigen Pfad bis zum Abschluss?
Der Validator nutzt mathematische Analyse (SMT-Solving), um Entwurfsfehler vor dem Einsatz zu erkennen.
Mathematische Einzelheiten finden Sie im Theorieteil.
Wollen Sie denselben Fragebogen in mehreren Sprachen durchführen, fügen Sie Übersetzungen hinzu, statt ihn zu kopieren: Eine Übersetzung ersetzt nur Text, sodass Validierung, Verzweigungen und Antwortcodes die des Fragebogens bleiben, den Sie geschrieben haben.
Vollständiges Beispiel
Abschnitt betitelt „Vollständiges Beispiel“qmlVersion: "2.0"questionnaire: title: "Customer Feedback Survey" codeInit: | nps_score = 0 follow_up_needed = 0
blocks: - id: b_intro title: "Welcome" items: - id: q_welcome kind: Comment title: "Thank you for taking our survey. It will take about 3 minutes."
- id: b_experience title: "Your Experience" items: - id: q_nps kind: Question title: "How likely are you to recommend us? (0 = Not at all, 10 = Extremely likely)" codeBlock: | nps_score = q_nps.outcome if nps_score <= 6: follow_up_needed = 1 input: control: Slider min: 0 max: 10 labels: 0: "Not likely" 5: "Maybe" 10: "Very likely"
- id: q_reason kind: Question title: "What is the primary reason for your score?" precondition: - predicate: follow_up_needed == 1 input: control: Dropdown labels: 1: "Product quality" 2: "Customer service" 3: "Pricing" 4: "Other"
- id: q_aspects kind: QuestionGroup title: "Please rate these aspects:" questions: - "Product quality" - "Customer service" - "Value for money" input: control: Radio labels: 1: "Poor" 2: "Fair" 3: "Good" 4: "Excellent"
- id: b_closing title: "Thank You" items: - id: q_comments kind: Comment title: "Thank you for your valuable feedback!"