Zum Inhalt springen
Wissensdatenbank

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.

Fragebogeneditor in Armiger

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.

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.

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 preferences

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

In 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

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): Eine Group wird 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.

QML unterstützt vier Item-Typen:

Zeigt Text an, ohne Antworten zu erfassen:

- id: q_intro
kind: Comment
title: "Please answer honestly. Your responses are confidential."

Stellt eine Frage und erfasst eine Antwort:

- id: q_age
kind: Question
title: "What is your age?"
input:
control: Editbox
min: 18
max: 120
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"

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"

Jede Frage muss angeben, wie Antworten erfasst werden.

Binäre Auswahl:

input:
control: Switch
on: "Yes"
off: "No"

Auswahl genau einer Option aus mehreren:

input:
control: Radio
labels:
1: "Option A"
2: "Option B"
3: "Option C"

Auswahl beliebig vieler Optionen, auch keiner:

input:
control: Checkbox
labels:
1: "Feature A"
2: "Feature B"
4: "Feature C"
8: "Feature D"

Platzsparende Auswahl aus vielen Optionen:

input:
control: Dropdown
labels:
1: "High School"
2: "Bachelor's"
3: "Master's"
4: "PhD"
left: "Education:"

Freie Eingabe einer Zahl:

input:
control: Editbox
min: 0
max: 1000000
left: "Annual income: $"

Visuelle Auswahl entlang einer Skala:

input:
control: Slider
min: 0
max: 10
step: 1
labels:
0: "Not at all"
5: "Somewhat"
10: "Extremely"

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]

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

Sowohl placeholder (Hinweistext, solange das Feld leer ist) als auch maxLength (Zeichengrenze) sind optional.

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.

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

Gibt eine befragte Person ungültige Daten ein (z. B. 5 Kinder in einem Haushalt mit 3 Personen), wird der Hinweistext angezeigt.

QML erlaubt eingebetteten Python-Code für Berechnungen und dynamische Logik.

Mit codeInit legen Sie Hilfsvariablen an, etwa Zähler:

questionnaire:
codeInit: |
total_score = 0
risk_level = 0

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

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)

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

Sowohl q_job_title als auch q_years_employed erben automatisch die Vorbedingung des Blocks; sie erscheinen nur, wenn die befragte Person erwerbstätig ist.

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"

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: 60
  • 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/right für Einheiten und Erläuterungen
  • 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
  • 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?
  • Initialisieren Sie früh: Legen Sie Variablen in codeInit an
  • 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

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.

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!"