QML-Syntax
QML (Questionnaire Markup Language) ist eine YAML-basierte Sprache zum Erstellen formal verifizierter Fragebögen. Diese Seite gibt einen kurzen technischen Überblick.
Überblick
Abschnitt betitelt „Ü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)
Zentrale Bestandteile
Abschnitt betitelt „Zentrale Bestandteile“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: ControlTypeqmlVersion
Abschnitt betitelt „qmlVersion“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.
Itemtypen
Abschnitt betitelt „Itemtypen“- Comment: Zeigt Text an, ohne Antworten zu erfassen
- Question: Ein einzelnes ganzzahliges Ergebnis
- QuestionGroup: Vektor ganzzahliger Ergebnisse
- MatrixQuestion: Matrix ganzzahliger Ergebnisse
Eingabesteuerelemente
Abschnitt betitelt „Eingabesteuerelemente“- 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]
Bedingungslogik
Abschnitt betitelt „Bedingungslogik“Vorbedingungen bestimmen die Sichtbarkeit:
precondition: - predicate: q_age.outcome >= 18Nachbedingungen 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: trueEin 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 != 3Der 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 = 0blocks: - 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 wayJede 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.
Externe Eingaben (Vorbelegung)
Abschnitt betitelt „Externe Eingaben (Vorbelegung)“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.
Codeblöcke
Abschnitt betitelt „Codeblöcke“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 wiemath.sqrt,statistics.meanoderrandom.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 ist100 * part // total, ein Durchschnitt in Zehnteln ist10 * total // n, und eine Zufallsziehung istrandom.randint(1, 6). - Funktionen, Klassen, Importe
- While-Schleifen, break, continue
- Dictionaries, String-Methoden
Vollständige Beispiele
Abschnitt betitelt „Vollständige Beispiele“Dieser Abschnitt zeigt alle Itemarten und Steuerelementtypen an funktionierenden Beispielen.
Itemart: Comment
Abschnitt betitelt „Itemart: Comment“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 == 1Itemart: Question
Abschnitt betitelt „Itemart: Question“Fragen mit einem einzelnen Ergebnis und verschiedenen Steuerelementtypen.
Steuerelement: Switch
Abschnitt betitelt „Steuerelement: Switch“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: 0off / on beschriften die beiden Seiten; left / right beschriften dieselben Seiten,
wenn off / on nicht angegeben sind.
Steuerelement: Radio
Abschnitt betitelt „Steuerelement: Radio“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: 1Steuerelement: Dropdown
Abschnitt betitelt „Steuerelement: Dropdown“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"Steuerelement: Checkbox
Abschnitt betitelt „Steuerelement: Checkbox“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 = 16Die Auswahl von „Reading“ und „Music“ ergibt 1 | 4 = 5
Steuerelement: Editbox
Abschnitt betitelt „Steuerelement: Editbox“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"Steuerelement: Textarea
Abschnitt betitelt „Steuerelement: Textarea“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: 500Optionale Eigenschaften:
placeholder: Hinweistext, der angezeigt wird, solange die Textarea leer istminLength: Erwartete Mindestanzahl an Zeichen (wird gespeichert, nicht erzwungen)maxLength: Höchstzahl zulässiger Zeichen
Steuerelement: Slider
Abschnitt betitelt „Steuerelement: Slider“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: 5Steuerelement: Range
Abschnitt betitelt „Steuerelement: Range“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: TextareaEine 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].
Itemart: QuestionGroup
Abschnitt betitelt „Itemart: QuestionGroup“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.
Itemart: MatrixQuestion
Abschnitt betitelt „Itemart: MatrixQuestion“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.
Komplexes Beispiel mit Codeblöcken
Abschnitt betitelt „Komplexes Beispiel mit Codeblöcken“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
Blockarten
Abschnitt betitelt „Blockarten“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: TextareaDie 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: 120Die 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.
Jede Iteration benennen (subjectFrom)
Abschnitt betitelt „Jede Iteration benennen (subjectFrom)“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: 120subjectFrom ä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).
Roster-Ergebnisse außerhalb des Rosters lesen
Abschnitt betitelt „Roster-Ergebnisse außerhalb des Rosters lesen“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())Einschränkungen (v1)
Abschnitt betitelt „Einschränkungen (v1)“iterateOverist ausschließlich ein ganzzahliger Ausdruck – Listen- oder Sequenztypen werden nicht akzeptiert.- Die Schlüssel von
labelsmü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
iterateOverfließ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 - 1fü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) undmaxEntrieswerden 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.
Form des Bronze-Exports
Abschnitt betitelt „Form des Bronze-Exports“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_notesDazu 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.
Wann QuestionGroup und wann Roster
Abschnitt betitelt „Wann QuestionGroup und wann Roster“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.
Begrenzung einer Group mit count
Abschnitt betitelt „Begrenzung einer Group mit count“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 positivescountausdrü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.