Zum Inhalt springen
Wissensdatenbank

QML-Syntax

QML (Questionnaire Markup Language) ist eine YAML-basierte Sprache zum Erstellen formal verifizierter Fragebögen. Diese Seite gibt einen kurzen technischen Überblick.

QML ermöglicht:

  • Formale Verifikation der Fragebogenlogik mit SMT-Solvern
  • Bedingte Verzweigung mit Vor- und Nachbedingungen
  • Ganzzahlige Ergebnisse für alle Antworten, die eine mathematische Analyse ermöglichen
  • Eingebetteten Python-Code für Berechnungen (eingeschränkte Teilmenge für die Verifikation)
qmlVersion: "2.0"
questionnaire:
title: "Survey Title"
codeInit: |
# Python initialization code
blocks:
- id: b_section
kind: Group # Optional, defaults to Group. Group | Roster
precondition: # Optional: gates every item in the block (branching)
- predicate: condition
items:
- id: q_item
kind: Question
precondition:
- predicate: condition
postcondition:
- predicate: validation
input:
control: ControlType

qmlVersion gibt die QML-Schemaversion an, die Ihr Dokument mindestens benötigt, im Format Major.Minor.Patch:

  • MAJOR-Änderungen sind inkompatibel – ein Dokument, das für eine ältere Major-Version geschrieben wurde, ist möglicherweise nicht mehr gültig, oder ein vorhandenes Konstrukt verhält sich anders.
  • MINOR-Änderungen ergänzen nur optionale Möglichkeiten – jedes Dokument, das für eine frühere Minor-Version derselben Major-Version geschrieben wurde, bleibt gültig.
  • PATCH-Änderungen ändern den Vertrag nie (Formulierungen, Klarstellungen, Korrekturen).

Die aktuelle Schemaversion ist 2.7.0. Das Release 2.0.0 war eine inkompatible Major-Version, die die Blockarten auf Group (die standardmäßige Art mit einem Durchlauf, optional mit count begrenzt) und Roster reduziert hat; Dokumente, die für eine frühere Major-Version geschrieben wurden (mit den entfernten Arten Sequence/Sample), müssen migriert werden. Die Minor-Version 2.1.0 hat den optionalen Schlüssel subjectFrom für Roster-Blöcke hinzugefügt (siehe Roster), 2.1.1 war eine verschärfende Patch-Version, und die Minor-Version 2.2.0 hat das optionale Flag external für Items eingeführt (siehe Externe Eingaben) – alles abwärtskompatible Ergänzungen, sodass jedes 2.0.0-Dokument gültig bleibt. Die Angabe qmlVersion: "2.0" genügt zum Laden; verwenden Sie "2.2", wenn Sie external nutzen. Die Minor-Version 2.5.0 hat eine Range-Antwort und ihren default zu einem Paar [low, high] gemacht (siehe Steuerelement: Range); verwenden Sie "2.5", wenn Sie einer Range einen default geben. Die Minor-Version 2.6.0 lehnt einen input-Schlüssel ab, den ein Steuerelement nicht deklariert, sodass ein falsch geschriebenes lables ein Fehler ist, statt stillschweigend ignoriert zu werden, und deklariert für Textarea minLength und für Switch left / right. Die Patch-Version 2.6.1 lehnt eine Item-id ab, die kein einfacher Name ist (Buchstaben, Ziffern und Unterstriche, nicht mit einer Ziffer beginnend und weder ein Python-Schlüsselwort noch ein eingebauter Name wie len, sum oder math), da eine Bedingung ein Item als <id>.outcome liest. Die Patch-Version 2.6.2 hält die QML-Arithmetik ganzzahlig: Autorencode, der einen Bruch ergeben kann (/, ein Dezimalliteral, float), wird beim Laden des Fragebogens abgelehnt; verwenden Sie stattdessen //. Die Patch-Version 2.6.3 macht einen Range-default zu einem Paar ganzer Zahlen, wie es jede Range-Antwort ist. Die Patch-Version 2.6.4 lehnt einen default außerhalb des Antwortbereichs des Items ab: Ein Fragebogen, dessen Standardwert keiner möglichen Antwort entspricht, wird nicht geladen. Die Minor-Version 2.7.0 fügt das optionale Flag invented für eine Nachbedingung hinzu (siehe Bedingungslogik); verwenden Sie "2.7", wenn Sie es schreiben. Die Schemaversion ist unabhängig von der internen Release-Version der Plattform.

  • Comment: Zeigt Text an, ohne Antworten zu erfassen
  • Question: Ein einzelnes ganzzahliges Ergebnis
  • QuestionGroup: Vektor ganzzahliger Ergebnisse
  • MatrixQuestion: Matrix ganzzahliger Ergebnisse
  • Switch: Binär (0/1)
  • Radio: Einfachauswahl aus beschrifteten Optionen
  • Checkbox: Mehrfachauswahl (Kodierung als Bitmaske)
  • Dropdown: Einfachauswahl mit Präfix/Suffix
  • Editbox: Freie Eingabe einer ganzen Zahl innerhalb von [min, max]
  • Textarea: Freitext – das Ergebnis ist ein String und von der formalen Verifikation ausgenommen
  • Slider: Visuelle Auswahl einer ganzen Zahl
  • Range: Auswahl eines Intervalls – das Ergebnis ist ein Paar [low, high]

Vorbedingungen bestimmen die Sichtbarkeit:

precondition:
- predicate: q_age.outcome >= 18

Nachbedingungen erzwingen Bedingungen an die Antwort:

postcondition:
- predicate: q_children.outcome < q_household.outcome
hint: "Children must be fewer than household size"

Eine Nachbedingung kann invented: true tragen. Der Import eines Fragebogens setzt das Flag bei einer Prüfung, die die Quelle nicht als feste Regel formuliert hat, etwa bei einer weichen Plausibilitätsprüfung oder einer Prüfung, die aus einer Interviewer-Anweisung übernommen wurde („nachfragen, wenn Stunden > 80“). So können Sie die Prüfung vor der Veröffentlichung bestätigen oder ändern. Das Flag ändert nichts an der Umfrage oder am Validator, und Befragte sehen es nie; der Editor markiert jede solche Prüfung. Entfernen Sie das Flag, sobald Sie die Prüfung bestätigt haben. Bei Vorbedingungen ist das Flag nicht zulässig.

postcondition:
- predicate: q_hours.outcome <= 80
hint: "More than 80 hours a week: please check the number"
invented: true

Ein Block hat drei Aufgaben. Er gruppiert zusammengehörige Items zu einem Abschnitt; er verzweigt, weil eine precondition auf Blockebene jedes Item im Block steuert; und als Roster wiederholt er seine Items einmal pro ausgewählter Entität. Block- und Item-Bedingungen werden bei der Durchführung der Umfrage kombiniert (zuerst die des Blocks, dann die des Items, und alle müssen erfüllt sein), und der Validator kombiniert sie auf dieselbe Weise.

Steuern Sie eine Verzweigung am Block. Eine Folge von zwei oder mehr Items mit derselben Bedingung gehört in einen eigenen Block, der diese Bedingung trägt; ein Item behält eine eigene Vorbedingung nur für das, was nur für dieses Item gilt. Schreiben Sie die Bedingung einmal, nicht an jedes Item:

- id: b_employment
precondition:
- predicate: q_employed.outcome == 1 # gates every item below
items:
- id: q_job_title
kind: Question
title: "What is your job title?"
input: {control: Radio, labels: {1: "Manager", 2: "Professional", 3: "Technician"}}
- id: q_team_size
kind: Question
title: "How many people do you manage?"
precondition:
- predicate: q_job_title.outcome == 1 # specific to this item
input: {control: Editbox, min: 0, max: 500}

Eine Blockbedingung liest Antworten und Variablen von Items vor dem Block. Sie wird vor jedem Item erneut geprüft. Liest sie eine Variable, die ein Codeblock innerhalb desselben Blocks zuweist, ändert sie sich also mitten im Block, und sobald zwei Items die Variable zuweisen, meldet der Validator einen Abhängigkeitszyklus. Blöcke folgen der Dateireihenfolge; setzen Sie einen bedingten Block daher hinter das Item, das über ihn entscheidet. Blöcke lassen sich nicht verschachteln; eine Verzweigung innerhalb einer Verzweigung ist eine Blockbedingung plus eine Item-Vorbedingung oder ein weiterer Block. Die Vorbedingung eines Items gilt nie für das nächste Item mit, daher gibt ein bedingtes Item außerhalb eines bedingten Blocks seine eigene vollständige Bedingung an.

Eine Frage, die die befragte Person übersprungen hat. Wird einer befragten Person eine Frage angezeigt und lässt sie sie leer, entscheidet sich eine Bedingung, die diese Antwort liest, anhand der vorhandenen Antworten. So gilt q_a.outcome == 1 or q_b.outcome == 1 weiterhin, wenn nur q_a mit 1 beantwortet wurde. Könnte die fehlende Antwort das Ergebnis noch ändern, blendet eine Vorbedingung ihre Frage aus, und eine Nachbedingung lässt die Antwort durch. In beiden Fällen hält die Umfrage eine Warnung fest, und diese bleibt in Ihrem Datensatz. Um Personen mit fehlender Antwort gezielt weiterzuleiten, prüfen Sie das ausdrücklich:

precondition:
- predicate: q_marital.outcome is None or q_marital.outcome != 3

Der Validator versteht diese Prüfung: Eine Bedingung, die prüft, ob eine einfache Frage beantwortet wurde, wird wie jeder andere Vergleich verifiziert, solange die Prüfung vor den anderen Verwendungen dieser Antwort in der Bedingung steht, wie hier.

Der Validator berücksichtigt leere Antworten auch bei der Einstufung einer Frage. Eine Vorbedingung, die eine Antwort liest, die die befragte Person leer lassen kann, wird als bedingt erreichbar gemeldet, nicht als immer erreichbar, da eine leere Antwort die Frage ausblendet. Um eine Antwort verpflichtend zu machen, geben Sie dieser Frage die eigene Nachbedingung q_marital.outcome is not None; der Validator weiß dann, dass sie nie leer bleibt.

Anders ist es bei einer Frage, die nie angezeigt wurde, weil ihre eigene Vorbedingung sie ausgeblendet hat: Ihre Antwort ist einfach leer, und eine Bedingung wie q_pregnant.outcome != 1 behandelt sie entsprechend.

Zählen über einen Block hinweg. Die Vorbedingung eines Blocks wird vor jeder seiner Fragen erneut geprüft, sodass ein Zähler, den die Fragen aktualisieren, den Block vorzeitig beenden kann:

codeInit: |
negative_count = 0
blocks:
- id: b_concepts
precondition:
- predicate: negative_count < 3 # stop after the third "No"
items:
- id: q_concept_1
codeBlock: |
if q_concept_1.outcome == 0:
negative_count = negative_count + 1
# ... q_concept_2, q_concept_3, ... the same way

Jede Frage sieht den Zähler so, wie ihn die Fragen vor ihr in der Datei hinterlassen haben; ihr eigener Codeblock läuft nach ihren eigenen Bedingungen. Der Validator liest ihn genauso: Eine Bedingung, die der Zähler nie erfüllen kann (negative_count < 0), wird als unerreichbar gemeldet, und dasselbe gilt für einen Zähler, den die eigene Vorbedingung einer Frage liest. Eine leer gelassene Frage macht den Zähler unbekannt (ihr Codeblock hat eine fehlende Antwort gelesen), daher wird der Rest des Blocks übersprungen: In der gezeigten Form wird nur die erste Frage immer gestellt. Geben Sie jeder Frage die Nachbedingung q_concept_1.outcome is not None (und so weiter), um eine Antwort zu verlangen; der Validator meldet dann die ersten drei Fragen als immer gestellt und die späteren als bedingt.

Echte Erhebungsinstrumente verzweigen oft anhand eines Werts, den keine Frage erhebt – ein Rotations-Flag, eine Split-Ballot-Gruppe, Geschlecht oder Familienstand aus einer Stichprobendatei, eine Antwort aus einer früheren Welle. Kennzeichnen Sie ein solches Item mit external: true (Schema 2.2.0+), um es als vorbelegbar zu deklarieren:

- id: q_rotate_out
kind: Question
title: "Is this respondent rotating out this wave?"
external: true
input:
control: Radio
labels:
0: "No"
1: "Yes"

Ansonsten ist ein externes Item eine ganz normale Frage – es hat einen echten input:-Wertebereich, kann Vor- und Nachbedingungen sowie einen Codeblock haben und wird von Z3 genauso verifiziert wie dasselbe Item ohne das Flag (das Flag fügt keine neue zu beweisende Logik hinzu). Beim Start der Umfrage versucht die Plattform, das Item aus dem Datensatz der befragten Person (Demografie + importierte Attribute) vorab zu beantworten, verknüpft pro Kampagne über eine Zuordnung, die ein Operator konfiguriert. Ergibt sich ein Wert und ist er für den Wertebereich des Items gültig, wird das Item automatisch beantwortet und ausgeblendet; gibt es keinen Wert (oder liegt er außerhalb des Wertebereichs), wird das Item einfach im normalen Ablauf gestellt – die Vorbelegung ist eine Optimierung, nie ein Hindernis.

Die Quellzuordnung pro Item ist eine administrative Eigenschaft, die pro Kampagne (in Targetor) konfiguriert wird, nicht in der QML-Datei. Derselbe Fragebogen kann daher in verschiedenen Kampagnen mit unterschiedlicher Vorbelegung laufen. Ein automatisch beantworteter Wert wird in den Daten als extern geliefert gekennzeichnet, sodass die Analyse ihn von einer eigenen Antwort der befragten Person unterscheiden kann.

external: true ist der vorgesehene Weg, auf einen externen Wert zu verzweigen – es ersetzt die älteren Umgehungslösungen (ein bloßer undefinierter Name, eine eingefrorene codeInit-Konstante oder eine Vorab-Frage mit ADMIN: im Titel), die der Validator inzwischen markiert.

Eingeschränkte Python-Teilmenge für die formale Verifikation:

Unterstützt:

  • Arithmetik mit ganzen Zahlen: +, -, *, // (ganzzahlige Division), %, ** mit nicht negativem Exponenten
  • Vergleiche: <, <=, >, >=, ==, !=
  • Boolesche Operatoren: and, or, not
  • Kontrollfluss: if/elif/else, for (eingeschränkt)
  • Ternärer Ausdruck: x = 1 if condition else 0
  • Tupel-Entpacken: a, b = 1, 0
  • Eingebaute Funktionen: range(), abs(), int(), bool()
  • Zugriff auf Ergebnisse: item.outcome

Nicht unterstützt:

  • Alles, was einen Bruch ergibt: /, eine Dezimalzahl (0.5), float(), ein negativer Exponent (2 ** -1) oder eine Funktion mit gebrochenem Ergebnis wie math.sqrt, statistics.mean oder random.random. Jede Antwort ist eine ganze Zahl, und jede Bedingung wird über ganzen Zahlen verifiziert; ein Fragebogen, der eines davon verwendet, wird daher nicht geladen, und die Meldung nennt die Stelle. Skalieren Sie stattdessen: Ein Prozentsatz ist 100 * part // total, ein Durchschnitt in Zehnteln ist 10 * total // n, und eine Zufallsziehung ist random.randint(1, 6).
  • Funktionen, Klassen, Importe
  • While-Schleifen, break, continue
  • Dictionaries, String-Methoden

Dieser Abschnitt zeigt alle Itemarten und Steuerelementtypen an funktionierenden Beispielen.

Zeigt Informationstext an, ohne Antworten zu erfassen:

- id: intro_comment
kind: Comment
title: "Welcome to our demographic survey. Your responses help us understand our community better."

Kommentare können bedingt angezeigt werden:

- id: parent_notice
kind: Comment
title: "The following questions are about your children."
precondition:
- predicate: q_has_children.outcome == 1

Fragen mit einem einzelnen Ergebnis und verschiedenen Steuerelementtypen.

Binäre Auswahl (0 = aus, 1 = ein):

- id: q_has_children
kind: Question
title: "Do you have children?"
input:
control: Switch
off: "No"
on: "Yes"
default: 0

off / on beschriften die beiden Seiten; left / right beschriften dieselben Seiten, wenn off / on nicht angegeben sind.

Einfachauswahl aus beschrifteten Optionen:

- id: q_education
kind: Question
title: "What is your highest level of education?"
input:
control: Radio
labels:
1: "High School"
2: "Bachelor's Degree"
3: "Master's Degree"
4: "Doctorate"
default: 1

Einfachauswahl mit optionalem Präfix-/Suffixtext:

- id: q_country
kind: Question
title: "Country of residence"
input:
control: Dropdown
left: "I live in"
right: ""
labels:
1: "United States"
2: "Canada"
3: "United Kingdom"
4: "Germany"
5: "Other"

Mehrfachauswahl (Kodierung als Bitmaske):

- id: q_interests
kind: Question
title: "Select all that apply:"
input:
control: Checkbox
labels:
1: "Reading" # Bit 0: value 2^0 = 1
2: "Sports" # Bit 1: value 2^1 = 2
4: "Music" # Bit 2: value 2^2 = 4
8: "Travel" # Bit 3: value 2^3 = 8
16: "Cooking" # Bit 4: value 2^4 = 16

Die Auswahl von „Reading“ und „Music“ ergibt 1 | 4 = 5

Freie Eingabe einer ganzen Zahl mit Grenzen. Eine Antwort außerhalb von min..max oder mit Nachkommastellen wird abgelehnt, und die befragte Person wird gebeten, eine ganze Zahl im zulässigen Bereich einzugeben. Ein step ist bei einer Editbox nicht zulässig; um einen Dezimalwert zu erheben, skalieren Sie ihn (fragen Sie nach Cent statt nach Euro).

- id: q_age
kind: Question
title: "What is your age?"
input:
control: Editbox
min: 0
max: 120
left: ""
right: "years old"
default: 25
postcondition:
- predicate: q_age.outcome >= 18
hint: "You must be 18 or older to participate"

Offene Freitexteingabe. Das Ergebnis ist ein String (keine ganze Zahl) und wird daher von der Z3-Analyse ignoriert – ein Bezug auf das Ergebnis einer Textarea in einer Vorbedingung, einer Nachbedingung oder einem Codeblock ist ein Entwurfsfehler, den der Validator meldet. Verwenden Sie sie für qualitatives Feedback, Vorschläge oder Kommentare, die Textantworten brauchen.

- id: q_feedback
kind: Question
title: "Describe your experience with our service."
input:
control: Textarea
placeholder: "Type your answer here..."
maxLength: 500

Optionale Eigenschaften:

  • placeholder: Hinweistext, der angezeigt wird, solange die Textarea leer ist
  • minLength: Erwartete Mindestanzahl an Zeichen (wird gespeichert, nicht erzwungen)
  • maxLength: Höchstzahl zulässiger Zeichen

Visuelle Auswahl einer ganzen Zahl:

- id: q_satisfaction
kind: Question
title: "How satisfied are you with our service?"
input:
control: Slider
min: 0
max: 10
step: 1
left: "Not satisfied"
right: "Very satisfied"
labels:
0: "0"
5: "5"
10: "10"
default: 5

Auswahl eines Intervalls mit zwei Reglern. Das Ergebnis ist eine Liste mit zwei Einträgen [low, high] mit min <= low <= high <= max:

- id: q_price_range
kind: Question
title: "What is your acceptable price range?"
input:
control: Range
min: 0
max: 1000
step: 50
left: "$"
right: ""
default: [200, 600]

Die Auswahl von 100 bis 500 speichert [100, 500]. Ein default ist, falls angegeben, ebenfalls ein Paar ganzer Zahlen: die Ausgangspositionen der beiden Regler.

Lesen Sie die Enden über ihren Namen: q_price_range.outcome.low ist das untere Ende und q_price_range.outcome.high das obere. Ein Index wie outcome[0] oder der Vergleich der Antwort mit einer Liste (outcome == [100, 500]) wird nicht akzeptiert.

- id: q_narrow_range_followup
kind: Question
title: "Why is your acceptable range so narrow?"
precondition:
- predicate: q_price_range.outcome.high - q_price_range.outcome.low <= 100
input:
control: Textarea

Eine Absicherung mit is not None ist nicht nötig: Eine unbeantwortete Range lässt die Bedingung zur Laufzeit unentschieden, sodass eine Vorbedingung, die sie liest, ihr Item überspringt. In einer QuestionGroup mit einem Range-Steuerelement ist das Ergebnis eine Liste von Intervallen; in einer MatrixQuestion sind es Zeilen × Spalten von Intervallen, jeweils gelesen als m.outcome[j][k].low / m.outcome[j][k].high. Ein Codeblock setzt eine Range-Antwort mit einem Paar, q.outcome = [low, high].

Vektor von Ergebnissen mit demselben Steuerelement für jede Teilfrage:

- id: qg_family_ages
kind: QuestionGroup
title: "Please enter the age of each family member:"
questions:
- "Yourself"
- "Spouse"
- "First child"
- "Second child"
precondition:
- predicate: q_household_size.outcome >= 2
input:
control: Editbox
min: 0
max: 120
right: "years"
postcondition:
- predicate: qg_family_ages.outcome[0] >= 18
hint: "Primary respondent must be 18 or older"

Greifen Sie per Index auf die Ergebnisse zu: qg_family_ages.outcome[0], qg_family_ages.outcome[1] usw.

Der statische Validator beweist Bedingungen, die eine Antwort lesen, qg.outcome[i]. Bis die Gruppe beantwortet ist, ist ihr Ergebnis None (ausgeblendet oder angezeigt und leer gelassen), sodass jeder Zugriff qg.outcome[i] dann eine Vorbedingung scheitern lässt und eine Nachbedingung übergeht; prüfen Sie zuerst qg.outcome is not None, um auf die Gruppe selbst zu verzweigen. In einer beantworteten Gruppe sind leer gelassene Einzelantworten None: qg.outcome[0] != 1 gilt für eine leere Antwort, qg.outcome[0] > 1 nicht. Der Vergleich der ganzen Liste (qg.outcome == 1), eine Menge von Antworten, eine Gruppe innerhalb eines Rosters oder einer begrenzten Group und ein Codeblock, der in eine Gruppe schreibt, werden zur Laufzeit angewendet, aber nicht verifiziert, und als skipped_condition-Warnungen gemeldet.

Matrix von Ergebnissen (Zeilen × Spalten):

- id: mq_language_proficiency
kind: MatrixQuestion
title: "Please indicate the language proficiency level for each family member:"
rows:
- "English"
- "Spanish"
- "French"
- "German"
- "Mandarin"
columns:
- "Yourself"
- "Spouse"
- "First Child"
- "Second Child"
input:
control: Dropdown
labels:
0: "None"
1: "Beginner"
2: "Intermediate"
3: "Advanced"
4: "Native"

Greifen Sie per Zeilen-/Spaltenindex auf die Ergebnisse zu: mq_language_proficiency.outcome[0][1] für die erste Sprache (English) und das zweite Familienmitglied (Spouse).

Die Matrix erzeugt ein Raster, in dem jede Zelle die Kenntnisse eines Familienmitglieds in einer Sprache darstellt. Dieses Beispiel ergibt eine 5×4-Matrix (5 Sprachen × 4 Familienmitglieder) = 20 einzelne Ergebnisse.

Zeigt Vorbedingungen, Nachbedingungen und Codeblöcke:

qmlVersion: "2.0"
questionnaire:
title: "Income Survey"
codeInit: |
total_income = 0
blocks:
- id: b_demographics
items:
- id: q_employment
kind: Question
title: "Are you currently employed?"
input:
control: Switch
off: "No"
on: "Yes"
- id: b_employed
precondition:
- predicate: q_employment.outcome == 1
items:
- id: q_income
kind: Question
title: "What is your annual income?"
input:
control: Editbox
min: 0
max: 1000000
left: "$"
right: "per year"
codeBlock: |
total_income = q_income.outcome
- id: q_spouse_employed
kind: Question
title: "Is your spouse employed?"
input:
control: Switch
off: "No"
on: "Yes"
- id: q_spouse_income
kind: Question
title: "What is your spouse's annual income?"
precondition:
- predicate: q_spouse_employed.outcome == 1
input:
control: Editbox
min: 0
max: 1000000
left: "$"
right: "per year"
codeBlock: |
total_income = total_income + q_spouse_income.outcome
- id: b_household
items:
- id: q_household_income
kind: Question
title: "What is your total household income?"
input:
control: Editbox
min: 0
max: 2000000
left: "$"
right: "per year"
postcondition:
- predicate: q_household_income.outcome >= total_income
hint: "Household income cannot be less than reported individual incomes"

Dieses Beispiel zeigt:

  • Bedingte Sichtbarkeit: Die Einkommensfragen stehen in einem Block, der einmal an die Erwerbstätigkeit geknüpft ist
  • Codeblöcke: Summieren das Einkommen über mehrere Fragen
  • Validierung per Nachbedingung: Stellt sicher, dass das Haushaltseinkommen zu den Einzeleinkommen passt
  • Verkettete Abhängigkeiten: Jede Frage hängt von vorherigen Antworten ab

kind ist optional, Standard ist Group. Zulässige Werte:

Art Bedeutung
Group (Standard) Stellt jedes zutreffende innere Item einmal in kanonischer (topologischer) Reihenfolge. Ein optionales count: N begrenzt den Block auf die ersten N infrage kommenden Items (siehe unten).
Roster Wiederholt die inneren Items für jedes gesetzte Bit einer iterateOver-Bitmaske (siehe unten).

Blöcke jeder Art können außerdem optionale Listen precondition und postcondition tragen, die für jedes innere Item gelten (Regeln auf Blockebene greifen vor Regeln auf Itemebene). Ein Roster mit falscher Vorbedingung wird ganz übersprungen; mit wahrer Vorbedingung iteriert er wie üblich über iterateOver. Die statische Validierung (Z3) berücksichtigt die Art: Ein Roster wird pro Label-Schlüssel in Kopien ausgerollt, die jeweils an ihr Bit gebunden sind; eine mit count begrenzte Group behandelt ihre inneren Items als bedingt vorhanden, mit einer Ziehung von bis zu N.

Ein Roster-Block (kind: Roster) wiederholt seine inneren Items einmal pro aktivem Label-Schlüssel. Sie deklarieren:

  • iterateOver: einen Python-Ausdruck, der zu einer nicht negativen ganzen Zahl ausgewertet werden muss, die als Bitmaske behandelt wird.
  • labels: eine Zuordnung von ganzzahligen Schlüsseln, die Zweierpotenzen sind (1, 2, 4, 8, 16, …), zu Anzeigetexten – sie legt die Menge möglicher Iterationen fest.

Die Engine durchläuft die gesetzten Bits in iterateOver vom niedrigsten zum höchsten. Für jedes gesetzte Bit, dessen Schlüssel in labels vorkommt, laufen die inneren Items einmal, mit diesem Bitwert als eigentlicher Identität der Iteration.

Jede Antwort auf ein Roster-Item gehört zu einer Iteration. Eine Antwort, die über die API (submit_survey_response) an ein Roster-Item gesendet wird, das nie gestellt wurde, während keine Iteration des Rosters läuft (bevor die Umfrage den Roster erreicht oder nachdem sie ihn verlassen hat), wird abgelehnt, ebenso ein Sprung zu einem solchen Item in der Schrittliste. Eine Antwort, die der Roster bereits enthält, kann weiterhin geändert werden: Sie wird in der Iteration wieder geöffnet, in der sie gegeben wurde.

Zwei Schreibweisen gibt es in v1:

1. Gesteuert durch Mehrfachauswahl (Checkbox speist den Roster direkt)

Abschnitt betitelt „1. Gesteuert durch Mehrfachauswahl (Checkbox speist den Roster direkt)“

Das Ergebnis einer Checkbox IST die ganzzahlige Bitmaske (Summe der ausgewählten Zweierpotenz-Schlüssel). Es fließt ohne Zwischencode direkt in iterateOver:

qmlVersion: "2.0"
questionnaire:
title: "Daily Meal Tracker"
blocks:
- id: meal_selection
kind: Group
items:
- id: q_meals_eaten
kind: Question
title: "Which meals did you eat today?"
input:
control: Checkbox
labels:
1: "Breakfast"
2: "Lunch"
4: "Dinner"
8: "Snack"
- id: per_meal
kind: Roster
title: "Per-meal details"
iterateOver: q_meals_eaten.outcome
labels:
1: "Breakfast"
2: "Lunch"
4: "Dinner"
8: "Snack"
items:
- id: q_satisfaction
kind: Question
title: "How satisfied were you?"
input:
control: Slider
min: 1
max: 5
- id: q_notes
kind: Question
title: "Any notes?"
input:
control: Textarea

Die befragte Person kreuzt Breakfast + Dinner an → q_meals_eaten.outcome = 5 (Bit 1 + Bit 4) → die Engine durchläuft zwei Iterationen: Bit 1 (Breakfast), dann Bit 4 (Dinner).

2. Numerisches „Wie viele?“ (einfache Arithmetik bildet die Maske)

Abschnitt betitelt „2. Numerisches „Wie viele?“ (einfache Arithmetik bildet die Maske)“

Für eine numerische Anzahl bildet ein vorgelagerter codeBlock mit einfacher Arithmetik (2 ** n - 1) eine Maske der „ersten N Bits“. Ein Bitverschiebungsoperator (<<) ist nicht nötig:

qmlVersion: "2.0"
questionnaire:
title: "Family Roster"
blocks:
- id: count_block
kind: Group
items:
- id: q_family_count
kind: Question
title: "How many family members do you have?"
input:
control: Editbox
min: 1
max: 4
codeBlock: |
family_mask = 2 ** q_family_count.outcome - 1
- id: per_member
kind: Roster
title: "Family member details"
iterateOver: family_mask
labels:
1: "Member 1"
2: "Member 2"
4: "Member 3"
8: "Member 4"
items:
- id: q_member_name
kind: Question
title: "Name?"
input:
control: Editbox
min: 0
max: 100
- id: q_member_age
kind: Question
title: "Age?"
input:
control: Editbox
min: 0
max: 120

Die befragte Person gibt als Anzahl 3 an → der codeBlock berechnet family_mask = 2 ** 3 - 1 = 7 → die Engine durchläuft die Bits 1, 2, 4.

Standardmäßig erhält jede Iteration ihren Titel aus dem statischen labels-Eintrag („Member 1“, „Member 2“, …). Gibt die befragte Person innerhalb der Iteration einen aussagekräftigeren Namen an – den Namen eines Familienmitglieds, ein Produkt, das sie besitzt –, verweisen Sie mit dem optionalen subjectFrom des Blocks auf die id dieses inneren Items; seine Antwort pro Iteration wird dann als Gegenstand der Iteration angezeigt. Bis dieses Item beantwortet ist, fällt die Anzeige auf den statischen labels-Eintrag zurück.

- id: per_member
kind: Roster
title: "Family member details"
iterateOver: family_mask
subjectFrom: q_member_name # inner item whose answer names the iteration
labels:
1: "Member 1"
2: "Member 2"
4: "Member 3"
8: "Member 4"
items:
- id: q_member_name
kind: Question
title: "Name?"
input:
control: Textarea
- id: q_member_age
kind: Question
title: "Age?"
input:
control: Editbox
min: 0
max: 120

subjectFrom ändert nur das angezeigte Label – der kanonische Zweierpotenz-Bitschlüssel bleibt die Identität der Iteration für Speicherung, Export und Bezüge zwischen Iterationen. Es erfordert qmlVersion: "2.1" (oder höher).

Innerhalb einer Roster-Iteration liefert q_satisfaction.outcome den Wert der aktuellen Iteration (Snapshot/Wiederherstellung). Außerhalb des Rosters (Codeblöcke nach dem Roster, Vorbedingungen späterer Items) verwenden Sie das als Dict aufgebaute q_satisfaction.outcomes[<bit>]:

- id: q_summary
kind: Question
title: "..."
precondition:
# Show only if Dinner satisfaction was high.
- predicate: "q_satisfaction.outcomes.get(4, 0) >= 4"

Oder fassen Sie über die Iterationen hinweg zusammen:

total_satisfaction = sum(q_satisfaction.outcomes.values())
  • iterateOver ist ausschließlich ein ganzzahliger Ausdruck – Listen- oder Sequenztypen werden nicht akzeptiert.
  • Die Schlüssel von labels müssen positive Zweierpotenzen sein (1, 2, 4, 8, 16, …); der Loader weist alles andere mit einer klaren Fehlermeldung zurück.
  • Auch Checkbox-Steuerelemente verlangen Zweierpotenzen als Label-Schlüssel – das gleicht die Semantik von Checkbox und Roster an, sodass ein Checkbox-Ergebnis direkt in iterateOver fließt.
  • Keine String-Interpolation in Titeln. Item-Titel werden unverändert dargestellt; die Anzeige pro Iteration (z. B. „2 of 4 · Lunch“) rendert die Umfrageoberfläche aus der Zuordnung labels[<bit>].
  • Keine Bitverschiebungsoperatoren << / >> in Codeblöcken der Autoren – verwenden Sie einfache Arithmetik (2 ** n - 1 für die „ersten N Bits“). Der Operator ** ist erlaubt.
  • Keine List Comprehensions in Codeblöcken der Autoren (Aufwand der Z3-Übersetzung).
  • as (Bindung einer Iteratorvariablen) und maxEntries werden in v1 nicht unterstützt – das Bitmasken-Design macht beides überflüssig.
  • Verschachtelte Roster (Roster innerhalb eines Rosters) werden in v1 nicht unterstützt.
  • Selbstbezug in iterateOver (Bezug auf ein Item innerhalb desselben Rosters) wird beim Laden abgelehnt.

Jeder Roster erzeugt eine feste Anzahl von Spalten: len(labels) × len(inner items). Spaltenbenennung: {block_id}_{bit_key}_{item_id}. Zellen für Label-Schlüssel, die in einer Umfrage nicht aktiv sind, sind NULL. Das Schema ist allein durch die QML-Deklaration vollständig bestimmt.

Beispiel (per_meal mit 4 Labels × 2 inneren Items = 8 Spalten):

per_meal_1_q_satisfaction, per_meal_2_q_satisfaction, per_meal_4_q_satisfaction, per_meal_8_q_satisfaction,
per_meal_1_q_notes, per_meal_2_q_notes, per_meal_4_q_notes, per_meal_8_q_notes

Dazu kommt die äußere Spalte q_meals_eaten.

Ein Gold-Export im Langformat ist als optionale Transformation verfügbar. Sie formt den breiten Bronze-Datensatz in einen übergeordneten Datensatz (ohne Roster-Spalten) und einen untergeordneten Datensatz pro Roster mit den Spalten survey_id, iteration_key, <inner_item>... um – das bietet sich für Analyse-Workflows an, die nach Iteration gruppieren.

Verwenden Sie QuestionGroup für mehrere Fragen auf derselben Seite (ein einzelnes wiederholtes Merkmal, feste Anzahl, keine Titelanzeige pro Iteration).

Verwenden Sie Roster für Fragen pro Gegenstand, jede auf einer eigenen Seite – zur Laufzeit gezählt (numerisch oder per Mehrfachauswahl), ein inneres Item pro Seite, mit Tiefendurchlauf, bei dem die Iteration die äußere Schleife bildet.

Ein Group-Block akzeptiert ein optionales count: N, das ihn auf die ersten N infrage kommenden inneren Items begrenzt, deterministisch in kanonischer Reihenfolge gezogen. Ohne count stellt eine Group alle ihre zutreffenden Items.

  • count: das N – ein optionales positives ganzzahliges Literal. Fehlt es, werden alle Items gestellt. Ist es angegeben, weist der Loader ein nicht positives count ausdrücklich zurück; es gibt keinen stillen Standardwert.
qmlVersion: "2.0"
questionnaire:
title: "Adaptive Knowledge Check"
blocks:
- id: knowledge_pool
kind: Group
count: 3
items:
- id: q_topic_a
kind: Question
title: "Question about topic A"
input:
control: Radio
labels:
1: "Correct"
2: "Incorrect"
- id: q_topic_b
kind: Question
title: "Question about topic B"
input:
control: Radio
labels:
1: "Correct"
2: "Incorrect"
- id: q_topic_c
kind: Question
title: "Question about topic C"
input:
control: Radio
labels:
1: "Correct"
2: "Incorrect"
- id: q_topic_d
kind: Question
title: "Question about topic D"
input:
control: Radio
labels:
1: "Correct"
2: "Incorrect"
- id: q_topic_e
kind: Question
title: "Question about topic E"
input:
control: Radio
labels:
1: "Correct"
2: "Incorrect"

Mit count: 3 stellt die Engine die ersten 3 der 5 Items in kanonischer (topologischer) Reihenfolge – eine deterministische Ziehung der ersten N, keine Zufallsauswahl. Items, deren Vorbedingung false ergibt, werden einfach übergangen (der Slot wird NICHT verbraucht), sodass weniger als N Items angezeigt werden können, wenn nach den Vorbedingungen nicht genug Items übrig bleiben.

Ein Item, das wegen der Begrenzung ausgelassen wird, fehlt; es gilt nicht als beantwortet. Sobald die Group ihre N Items gestellt hat, wird ein Sprung zu einem ausgelassenen Item in der Schrittliste der Umfrage abgelehnt, ebenso eine Antwort, die über die API (submit_survey_response) dafür gesendet wird. Ein Item, das die Group gestellt hat, kann weiterhin geändert werden. Ein Item, das über die API beantwortet oder angesprungen wird, solange die Group noch einen freien Slot hat, belegt diesen Slot, sodass die Group insgesamt nie mehr als N Items stellt. Es behält den Slot, wenn die befragte Person vor die Group zurückgeht und ohne Änderung wieder vorwärts geht: Das Item wird mit seiner Antwort erneut angezeigt, statt durch ein früheres Item ersetzt zu werden.

Unabhängige innere Items erforderlich: Die inneren Items einer mit count begrenzten Group müssen unabhängig sein – kein inneres Item darf von einem anderen inneren Item derselben Group abhängen (weder direkt noch über eine gemeinsame Variable). Die Begrenzung kann jedes Item auslassen, sodass eine Abhängigkeit innerhalb der Group die Antwort eines nicht gezogenen Geschwister-Items lesen könnte. Die Plattform weist eine solche Group bei der Validierung zurück. (Eine Group ohne count und blockübergreifende Abhängigkeiten unterliegen keiner Einschränkung.)

Ergebnisse: Innere Items einer begrenzten Group nutzen den normalen einwertigen outcome-Pfad. Ein nicht gezogenes inneres Item (per Vorbedingung übersprungen oder jenseits der Begrenzung N) hat outcome: null und fehlt im Bronze-Export.