Tovább a tartalomhoz
Tudástár

A QML szintaxisa

A QML (Questionnaire Markup Language) YAML-alapú nyelv formálisan ellenőrzött kérdőívek készítésére. Ez az oldal rövid technikai áttekintést ad róla.

A QML a következőket nyújtja:

  • a kérdőív logikájának formális ellenőrzését SMT-megoldókkal;
  • a feltételes elágazást elő- és utófeltételekkel;
  • egész értékű kimenetet minden válaszra, így a kérdőív matematikailag elemezhető;
  • beágyazott Python-kód használatát számításokhoz (az ellenőrizhetőség érdekében korlátozott részhalmazzal).
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

A qmlVersion azt a legalacsonyabb QML-sémaverziót adja meg Major.Minor.Patch alakban, amelyet a dokumentum igényel:

  • A MAJOR változások visszafelé nem kompatibilisek: egy régebbi főverzióhoz írt dokumentum érvénytelenné válhat, vagy egy meglévő szerkezet másként viselkedhet.
  • A MINOR változások csak új, opcionális képességeket hoznak: ugyanazon főverzió egy korábbi alverziójához írt minden dokumentum érvényes marad.
  • A PATCH változások sosem módosítják a szerződést (megfogalmazás, pontosítások, javítások).

A séma jelenlegi verziója 2.7.0. A 2.0.0 kiadás visszafelé nem kompatibilis főverzió volt, amely a blokktípusokat két fajtára vonta össze: Group (az alapértelmezett, egyszeri végrehajtású fajta, amely count értékkel korlátozható) és Roster; a korábbi főverzióhoz írt (a megszűnt Sequence/Sample fajtákat használó) dokumentumokat át kell alakítani. A 2.1.0 alverzió a Roster blokkokhoz hozzáadta az opcionális subjectFrom kulcsot (lásd: Roster), a 2.1.1 szigorító javítás volt, a 2.2.0 alverzió pedig az elemekhez az opcionális external jelzőt hozta (lásd: Külső bemenetek) – mindegyik visszafelé kompatibilis bővítés, így minden 2.0.0-s dokumentum érvényes marad. A betöltéshez elegendő a qmlVersion: "2.0" megadása; ha az external jelzőt használja, adja meg a "2.2" értéket. A 2.5.0 alverzióban a Range válasza és annak default értéke [low, high] pár lett (lásd: Vezérlő: Range); ha Range-nek default értéket ad, használja a "2.5" értéket. A 2.6.0 alverzió elutasít minden olyan input kulcsot, amelyet a vezérlő nem deklarál, így az elgépelt lables hibát vált ki, ahelyett hogy a rendszer csendben figyelmen kívül hagyná; emellett deklarálja a Textarea minLength, valamint a Switch left / right kulcsát. A 2.6.1 javítás elutasítja azt az id elemazonosítót, amely nem egyszerű név (betűk, számjegyek és aláhúzásjelek, nem kezdődhet számjeggyel, és nem lehet Python-kulcsszó vagy beépített név, például len, sum vagy math), mivel egy feltétel az elemet <id>.outcome formában olvassa. A 2.6.2 javítás a QML aritmetikáját egész számokon tartja: a kérdőív betöltésekor a rendszer elutasít minden olyan szerzői kódot, amely törtet eredményezhet (/, tizedes literál, float); helyette használja a // operátort. A 2.6.3 javítás a Range default értékét egész számpárrá teszi, ahogyan minden Range-válasz is az. A 2.6.4 javítás elutasítja az elem értékkészletén kívül eső default értéket: az a kérdőív, amelynek alapértelmezett értékével egyetlen válasz sem egyezhet, nem tölthető be. A 2.7.0 alverzió az utófeltételekhez hozzáadja az opcionális invented jelzőt (lásd: Feltételes logika); ha használja, adja meg a "2.7" értéket. A sémaverzió független a platform belső kiadási verziójától.

  • Comment: szöveget jelenít meg, választ nem gyűjt
  • Question: egyetlen egész értékű kimenet
  • QuestionGroup: egész értékű kimenetek vektora
  • MatrixQuestion: egész értékű kimenetek mátrixa
  • Switch: bináris (0/1)
  • Radio: egyetlen választás címkézett lehetőségek közül
  • Checkbox: többszörös választás (bitmaszkos kódolás)
  • Dropdown: egyetlen választás elő- és utótaggal
  • Editbox: szabadon megadott egész szám a [min, max] tartományban
  • Textarea: szabad szöveg – a kimenet karakterlánc, ezért kimarad a formális ellenőrzésből
  • Slider: egész szám vizuális kiválasztása
  • Range: intervallum kiválasztása – a kimenet egy [low, high] pár

Az előfeltételek a láthatóságot határozzák meg:

precondition:
- predicate: q_age.outcome >= 18

Az utófeltételek megszorításokat érvényesítenek:

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

Egy utófeltétel invented: true jelzőt is kaphat. A kérdőív importálása olyan ellenőrzést jelöl meg vele, amelyet a forrás nem fogalmazott meg kötelező szabályként – például egy puha ellenőrzést vagy egy kérdezői utasításból átvett ellenőrzést („kérdezzen rá, ha az óraszám > 80”) –, hogy közzététel előtt megerősíthesse vagy módosíthassa. A jelző semmit sem változtat a kitöltésen vagy a validátoron, a válaszadók soha nem látják; a szerkesztő minden ilyen ellenőrzést megjelöl. Ha megerősítette az ellenőrzést, távolítsa el a jelzőt. Előfeltételre nem tehető.

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

A blokknak három feladata van. Csoportosítja az összetartozó elemeket egy szakaszba; elágaztat, mivel a blokkszintű precondition a blokk minden elemét feltételhez köti; és Rosterként megismétli elemeit minden kiválasztott entitásra. A blokk- és elemfeltételek a kitöltés során összekapcsolódnak (előbb a blokké, majd az elemé, és mindnek teljesülnie kell), és a validátor is ugyanígy kapcsolja össze őket.

Az elágazást a blokknál kösse feltételhez. Ha két vagy több egymást követő elem ugyanazon a feltételen osztozik, azok egy saját blokkba valók, amely ezt a feltételt viseli; egy elem csak azt tartja meg saját előfeltételként, ami csak rá vonatkozik. A feltételt egyszer írja le, ne minden elemnél:

- 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}

A blokkfeltétel a blokk előtti elemek válaszait és változóit olvassa. Minden elem előtt a rendszer újra kiértékeli, ezért ha olyan változót olvas, amelyet ugyanazon blokk egyik kódblokkja állít be, akkor a blokk közepén megváltozik, és amint két elem is beállítja, a validátor függőségi ciklust jelez. A blokkok a fájlbeli sorrendet követik, ezért a feltételhez kötött blokkot az azt eldöntő elem után helyezze el. A blokkok nem ágyazhatók egymásba; az elágazáson belüli elágazás egy blokkfeltétel és egy elem-előfeltétel együttese, vagy egy további blokk. Egy elem előfeltétele sosem öröklődik át a következő elemre, ezért egy feltételhez kötött blokkon kívüli feltételes elem a saját, teljes feltételét adja meg.

Kihagyott kérdés. Ha a válaszadó lát egy kérdést, de üresen hagyja, akkor az erre a válaszra hivatkozó feltételt a meglévő válaszok döntik el, így a q_a.outcome == 1 or q_b.outcome == 1 akkor is teljesül, ha csak a q_a kapott választ, 1-et. Ha a hiányzó válasz még megváltoztathatná az eredményt, az előfeltétel elrejti a kérdését, az utófeltétel pedig átengedi a választ. A kitöltés mindkét esetben figyelmeztetést rögzít, amely az adatkészletben is megmarad. Ha azokat a válaszadókat, akiknek a válasza hiányzik, meghatározott helyre szeretné irányítani, vizsgálja ezt kifejezetten:

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

A validátor felismeri ezt a vizsgálatot: azt a feltételt, amely azt ellenőrzi, hogy egy egyszerű kérdésre érkezett-e válasz, ugyanúgy ellenőrzi, mint bármely más összehasonlítást, feltéve, hogy a vizsgálat megelőzi a válasz többi felhasználását a feltételben, ahogyan itt is.

A validátor a kérdések besorolásakor is számol az üres válaszokkal. Ha egy előfeltétel olyan választ olvas, amelyet a válaszadó üresen hagyhat, a kérdést feltételesen elérhetőként jelzi, nem mindig elérhetőként, hiszen az üres válasz elrejti a kérdést. Ha egy választ kötelezővé szeretne tenni, adjon a kérdésnek saját q_marital.outcome is not None utófeltételt; a validátor ekkor tudja, hogy sosem marad üresen.

Más a helyzet azzal a kérdéssel, amely azért nem jelent meg, mert a saját előfeltétele elrejtette: annak válasza egyszerűen üres, és egy q_pregnant.outcome != 1 jellegű feltétel ennek megfelelően kezeli.

Számlálás egy blokkon át. A rendszer a blokk előfeltételét a blokk minden kérdése előtt újra kiértékeli, így egy, a kérdések által frissített számláló idő előtt lezárhatja a blokkot:

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

Minden kérdés olyan állapotban látja a számlálót, ahogyan a fájlban előtte álló kérdések hagyták; a saját kódblokkja a saját feltételei után fut le. A validátor ugyanígy értelmezi: a feltételt, amelyet a számláló sosem teljesíthet (negative_count < 0), elérhetetlenként jelzi, és ugyanez érvényes egy kérdés saját előfeltétele által olvasott számlálóra is. Egy üresen hagyott kérdés ismeretlenné teszi a számlálót (a kódblokkja hiányzó választ olvasott), ezért a blokk többi része kimarad: a fenti formában csak az első kérdés kerül mindig sorra. Ha minden kérdéshez megadja a q_concept_1.outcome is not None (és így tovább) utófeltételt, a válasz kötelező lesz; a validátor ekkor az első három kérdést mindig sorra kerülőként, a későbbieket pedig feltételesként jelzi.

A valódi kérdőívek gyakran olyan érték alapján ágaznak el, amelyet egyetlen kérdés sem gyűjt be – ilyen egy kirotálási jelző, egy osztott kérdőíves (split-ballot) csoport, a mintafájlból átvett nem vagy családi állapot, egy korábbi hullám válasza. Jelölje az ilyen elemet external: true értékkel (2.2.0+ séma), hogy előtölthetőnek nyilvánítsa:

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

A külső elem egyébként teljesen szokványos kérdés: valódi input: értékkészlete van, lehetnek elő- és utófeltételei, valamint kódblokkja, és a Z3 pontosan úgy ellenőrzi, mint ugyanezt az elemet a jelző nélkül (a jelző nem ad hozzá bizonyítandó logikát). A kitöltés indulásakor a platform megpróbálja a válaszadó rekordjából (demográfiai adatok + importált attribútumok) előre megválaszolni, egy operátor által kampányonként beállított leképezés alapján. Ha az érték előáll, és beletartozik az elem értékkészletébe, a rendszer automatikusan megválaszolja az elemet, és elrejti; ha nincs érték (vagy kívül esik az értékkészleten), az elem egyszerűen a szokásos módon kerül sorra – az előtöltés optimalizálás, soha nem akadály.

Az elemenkénti forrásleképezés adminisztratív tulajdonság, amelyet kampányonként (a Targetorban) kell beállítani, nem a QML-fájlban, így ugyanaz a kérdőív különböző kampányokban különböző előtöltési beállításokkal futhat. Az automatikusan megválaszolt érték az adatokban kívülről származóként szerepel, így az elemzés meg tudja különböztetni a válaszadó saját válaszától.

Az external: true a jóváhagyott módja annak, hogy egy külső értéktől tegyen függővé valamit – felváltja a korábbi kerülőutakat (egy definiálatlan név, egy rögzített codeInit konstans vagy egy ADMIN: címkéjű bevezető kérdés), amelyeket a validátor most megjelöl.

A formális ellenőrzéshez a Python korlátozott részhalmaza használható:

Támogatott:

  • Aritmetika egész számokon: +, -, *, // (egészosztás), %, ** nemnegatív kitevővel
  • Összehasonlítások: <, <=, >, >=, ==, !=
  • Logikai műveletek: and, or, not
  • Vezérlési szerkezetek: if/elif/else, for (korlátozottan)
  • Feltételes kifejezés: x = 1 if condition else 0
  • Tuple-kibontás: a, b = 1, 0
  • Beépített függvények: range(), abs(), int(), bool()
  • Kimenet elérése: item.outcome

Nem támogatott:

  • Minden, ami törtet eredményez: /, tizedes szám (0.5), float(), negatív kitevő (2 ** -1), vagy törtet adó függvény, például math.sqrt, statistics.mean vagy random.random. Minden válasz egész szám, és minden feltétel ellenőrzése egész számokon történik, ezért az ezeket használó kérdőív nem tölthető be; az üzenet megnevezi a helyet. Skálázzon helyettük: a százalék 100 * part // total, a tizedekben kifejezett átlag 10 * total // n, a véletlen húzás pedig random.randint(1, 6).
  • Függvények, osztályok, importok
  • While ciklusok, break, continue
  • Szótárak, karakterlánc-metódusok

Ez a szakasz működő példákon mutatja be az összes elemtípust és vezérlőtípust.

Tájékoztató szöveget jelenít meg, választ nem gyűjt:

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

A megjegyzések feltételesen is megjeleníthetők:

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

Egyetlen kimenetű kérdések különféle vezérlőtípusokkal.

Bináris választás (0 = ki, 1 = be):

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

Az off / on a két oldal felirata; a left / right ugyanezeket az oldalakat feliratozza, ha az off / on nincs megadva.

Egyetlen választás címkézett lehetőségek közül:

- 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

Egyetlen választás opcionális elő- és utótaggal:

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

Többszörös választás (bitmaszkos kódolás):

- 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

A „Reading” és a „Music” kiválasztása ezt a kimenetet adja: 1 | 4 = 5

Szabadon megadható, korlátok közé szorított egész szám. A min..max tartományon kívüli vagy tizedesjegyet tartalmazó választ a rendszer elutasítja, és arra kéri a válaszadót, hogy a tartományba eső egész számot adjon meg. Az Editbox nem fogad step értéket; tizedes érték gyűjtéséhez skálázzon (euró helyett centet kérjen).

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

Nyitott, szabad szöveges bevitel. A kimenet karakterlánc (nem egész szám), ezért a Z3-elemzés figyelmen kívül hagyja – ha egy előfeltétel, utófeltétel vagy kódblokk Textarea-kimenetre hivatkozik, az tervezési hiba, amelyet a validátor jelez. Kvalitatív visszajelzéshez, javaslatokhoz vagy szöveges választ igénylő megjegyzésekhez használja.

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

Opcionális tulajdonságok:

  • placeholder: az üres szövegmezőben megjelenő segédszöveg
  • minLength: a várt legkisebb karakterszám (a rendszer rögzíti, de nem kényszeríti ki)
  • maxLength: a megengedett legnagyobb karakterszám

Egész szám vizuális kiválasztása:

- 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

Intervallum kiválasztása két csúszkafogóval. A kimenet egy kételemű [low, high] lista, ahol 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]

A 100-tól 500-ig tartó kiválasztás [100, 500] értéket tárol. Ha megad default értéket, az is egész számpár: a két fogó nyugalmi helyzete.

A végpontokat név szerint olvassa: q_price_range.outcome.low az alsó, q_price_range.outcome.high a felső végpont. Index (például outcome[0]), illetve a válasz listával való összehasonlítása (outcome == [100, 500]) nem elfogadott.

- 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

Nincs szükség is not None védelemre: a megválaszolatlan Range futás közben eldöntetlenül hagyja a feltételt, így az azt olvasó előfeltétel kihagyja az elemét. Range vezérlőjű QuestionGroup esetén a kimenet tartományok listája; MatrixQuestion esetén sorok × oszlopok tartományai, amelyek mindegyike m.outcome[j][k].low / m.outcome[j][k].high formában olvasható. Kódblokk egy párral állítja be a Range-választ: q.outcome = [low, high].

Kimenetek vektora, minden alkérdéshez azonos vezérlővel:

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

A kimenetek indexeléssel érhetők el: qg_family_ages.outcome[0], qg_family_ages.outcome[1] stb.

A statikus validátor azokat a feltételeket bizonyítja, amelyek egyetlen választ olvasnak (qg.outcome[i]). Amíg a csoport nincs megválaszolva, a kimenete None (a feltétel kizárta, vagy megjelent, de üresen maradt), így ilyenkor minden qg.outcome[i] olvasás meghiúsít egy előfeltételt, és felment egy utófeltétel alól; ha magától a csoporttól szeretne függővé tenni valamit, előbb vizsgálja a qg.outcome is not None feltételt. A megválaszolt csoportban az üresen maradt részválaszok értéke None marad: a qg.outcome[0] != 1 üres válasz esetén teljesül, a qg.outcome[0] > 1 nem. A teljes lista összehasonlítása (qg.outcome == 1), a válaszok halmaza, a Rosterben vagy korlátozott Groupban lévő csoport, illetve a csoportot író kódblokk futás közben érvényesül, de nincs ellenőrizve, és skipped_condition figyelmeztetésként jelenik meg.

Kimenetek mátrixa (sorok × oszlopok):

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

A kimenetek sor- és oszlopindexeléssel érhetők el: a mq_language_proficiency.outcome[0][1] az első nyelvet (angol) és a második családtagot (házastárs) jelenti.

A mátrix olyan rácsot hoz létre, amelyben minden cella egy családtag egy nyelven való jártasságát jelöli. Ez a példa 5×4-es mátrixot ad (5 nyelv × 4 családtag) = 20 egyedi kimenet.

Elő- és utófeltételek, valamint kódblokkok bemutatása:

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"

A példa bemutatja:

  • a feltételes láthatóságot: a jövedelemre vonatkozó kérdések egyetlen, a foglalkoztatottságtól függő blokkban vannak, a feltétel egyszer van leírva;
  • a kódblokkokat: a jövedelem göngyölítése kérdésről kérdésre;
  • az utófeltételes ellenőrzést: a háztartás jövedelme összhangban legyen az egyéni jövedelmekkel;
  • a láncolt függőségeket: minden kérdés a korábbi válaszoktól függ.

A kind opcionális, alapértéke Group. Elfogadott értékek:

Fajta Jelentés
Group (alapértelmezett) Minden hatókörbe eső belső elemet egyszer kérdez meg, kanonikus (topologikus) sorrendben. Az opcionális count: N a blokkot az első N szóba jövő elemre korlátozza (lásd lent).
Roster A belső elemeket az iterateOver bitmaszk minden beállított bitjére megismétli (lásd lent).

Bármely fajtájú blokk kaphat opcionális precondition és postcondition listát is, amely minden belső elemre vonatkozik (a blokkszintű szabályok az elemszintűek előtt érvényesülnek). A hamis előfeltételű Roster teljes egészében kimarad; igaz előfeltétel esetén szokás szerint végigiterál az iterateOver értékén. A statikus ellenőrzés (Z3) figyelembe veszi a blokk fajtáját: a Rostert címkekulcsonként bitfeltételes másolatokra bontja ki; a count értékkel korlátozott Group belső elemeit feltételesen jelenlévőként, legfeljebb N elemes húzással kezeli.

A Roster blokk (kind: Roster) a belső elemeit minden aktív címkekulcsra egyszer megismétli. A szerző a következőket adja meg:

  • iterateOver: Python-kifejezés, amelynek értéke kötelezően nemnegatív egész szám; ezt a rendszer bitmaszkként kezeli.
  • labels: leképezés, amely kettőhatvány értékű egész kulcsokhoz (1, 2, 4, 8, 16, …) megjelenítendő szöveget rendel – a lehetséges iterációk teljes körét deklarálja.

A motor alulról felfelé halad végig az iterateOver beállított bitjein. Minden olyan beállított bitre, amelynek kulcsa szerepel a labels között, a belső elemek egyszer lefutnak, és az iteráció belső azonosítója ez a bitérték lesz.

Egy Roster-elemre adott minden válasz egy iterációhoz tartozik. Ha az API-n (submit_survey_response) keresztül olyan Roster-elemre küldenek választ, amelyet még nem kérdeztek meg, miközben a Rosternek egyetlen iterációja sincs folyamatban (mielőtt a kitöltés elérné a Rostert, vagy miután elhagyta), a rendszer elutasítja a választ, és ugyanígy azt is, ha a lépéslistában valaki ilyen elemre ugrana. A Rosterben már meglévő válasz továbbra is módosítható: abban az iterációban nyílik meg újra, amelyben megadták.

Az első verzió két megadási formát kínál:

1. Többszörös választásra épülő forma (a Checkbox közvetlenül táplálja a Rostert)

Szekció neve “1. Többszörös választásra épülő forma (a Checkbox közvetlenül táplálja a Rostert)”

A Checkbox kimenete MAGA a bitmaszk: egy egész szám (a kiválasztott kettőhatvány kulcsok összege). Köztes kód nélkül, közvetlenül az iterateOver értékébe kerül:

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

A válaszadó bejelöli a Breakfast + Dinner lehetőséget → q_meals_eaten.outcome = 5 (1-es bit + 4-es bit) → a motor két iteráción halad végig: az 1-es biten (Breakfast), majd a 4-es biten (Dinner).

2. Számszerű „Hány?” kérdés (egyszerű matematika építi a maszkot)

Szekció neve “2. Számszerű „Hány?” kérdés (egyszerű matematika építi a maszkot)”

Ha a darabszámot egy szám típusú válasz adja, egy korábbi codeBlock egyszerű matematikával (2 ** n - 1) építi fel az „első N bit” maszkot. Biteltoló operátorra (<<) nincs szükség:

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

A válaszadó 3-at ad meg darabszámként → a codeBlock kiszámítja: family_mask = 2 ** 3 - 1 = 7 → a motor az 1-es, 2-es és 4-es biten halad végig.

Az iterációk elnevezése (subjectFrom)

Szekció neve “Az iterációk elnevezése (subjectFrom)”

Alapértelmezés szerint minden iteráció a statikus labels bejegyzéséből kapja a címét („Member 1”, „Member 2”, …). Ha a válaszadó az iteráción belül beszédesebb nevet ad meg – egy családtag nevét, egy saját termékét –, adja meg a blokk opcionális subjectFrom kulcsában ennek a belső elemnek az azonosítóját, és az iteráció megjelenített alanya az elem adott iterációban kapott válasza lesz. Amíg ez az elem nincs megválaszolva, a felület a statikus labels bejegyzést mutatja.

- 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

A subjectFrom csak a megjelenített címkét változtatja meg – a tároláshoz, az exporthoz és az iterációk közötti hivatkozásokhoz továbbra is a kanonikus kettőhatvány bitkulcs az iteráció azonosítója. Használatához qmlVersion: "2.1" (vagy magasabb) szükséges.

Roster-kimenetek olvasása a Rosteren kívülről

Szekció neve “Roster-kimenetek olvasása a Rosteren kívülről”

A Roster egy iterációján belül a q_satisfaction.outcome az aktuális iteráció értékét adja (pillanatkép/visszaállítás). A Rosteren kívül (a Roster utáni kódblokkokban, későbbi elemek előfeltételeiben) használja a szótár alakú q_satisfaction.outcomes[<bit>] formát:

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

Vagy összesítsen az iterációkon át:

total_satisfaction = sum(q_satisfaction.outcomes.values())
  • Az iterateOver szigorúan egész értékű kifejezés – lista- és szekvenciatípusok nem elfogadottak.
  • A labels kulcsainak pozitív kettőhatványoknak kell lenniük (1, 2, 4, 8, 16, …); a betöltő minden mást egyértelmű hibaüzenettel elutasít.
  • A Checkbox vezérlők is kettőhatvány címkekulcsokat követelnek meg – ez összehangolja a Checkbox jelentését a Rosterrel, így a Checkbox kimenete közvetlenül az iterateOver értékébe kerülhet.
  • A címekben nincs karakterlánc-behelyettesítés. Az elemcímek szó szerint jelennek meg; az iterációnkénti megjelenítési keretet (pl. „2 / 4 · Lunch”) a kitöltési felület állítja elő a labels[<bit>] leképezésből.
  • A szerzői kódblokkokban nincs << / >> biteltoló operátor – használjon egyszerű matematikát (2 ** n - 1 az „első N bithez”). A ** operátor megengedett.
  • A szerzői kódblokkokban nincs listaértelmezés (list comprehension) (a Z3-fordítás költsége miatt).
  • Az as (iterátorváltozó-kötés) és a maxEntries az első verzióban nem támogatott – a bitmaszkos megoldás mindkettőt szükségtelenné teszi.
  • Egymásba ágyazott Rosterek (Roster a Rosterben) az első verzióban nem támogatottak.
  • Az iterateOver önhivatkozását (ugyanabban a Rosterben lévő elemre való hivatkozást) a rendszer betöltéskor elutasítja.

Minden Roster rögzített számú oszlopot hoz létre: len(labels) × len(inner items). Oszlopnevek: {block_id}_{bit_key}_{item_id}. Azoknak a címkekulcsoknak a cellái, amelyek egy kitöltésben nem aktívak, NULL értékűek. A séma kizárólag a QML-deklarációból teljesen determinisztikusan következik.

Példa (per_meal, 4 címke × 2 belső elem = 8 oszlop):

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

Ehhez jön még a külső q_meals_eaten oszlop.

A hosszú formátumú Arany export választható átalakításként érhető el: a széles Bronz adatokat egy szülő adatkészletre (Roster-oszlopok nélkül) és Rosterenként egy gyermek adatkészletre alakítja, amelynek oszlopai survey_id, iteration_key, <inner_item>... – ez jól illik az iterációk szerint csoportosító elemzői munkafolyamatokhoz.

Mikor használjon QuestionGroupot és mikor Rostert

Szekció neve “Mikor használjon QuestionGroupot és mikor Rostert”

A QuestionGroup ugyanazon az oldalon lévő több kérdéshez való (egyetlen ismételt jellemző, rögzített darabszám, iterációnkénti címkeret nélkül).

A Roster tételenkénti kérdésekhez való, mindegyik a saját oldalán – futás közben meghatározott darabszám (szám vagy többszörös választás alapján), oldalanként egy belső elem, iterációelsődleges, mélységi bejárással.

A Group blokk opcionális count: N értéket fogad, amely az első N szóba jövő belső elemre korlátozza, kanonikus sorrendben, determinisztikusan kiválasztva. count nélkül a Group minden hatókörébe eső elemét megkérdezi.

  • count: az N – opcionális pozitív egész literál. Ha hiányzik → minden elem sorra kerül. Ha meg van adva → a betöltő a nem pozitív count értéket hibaüzenettel elutasítja; hallgatólagos alapértelmezés nincs.
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"

count: 3 esetén a motor az 5 elemből az első 3-at kérdezi meg kanonikus (topologikus) sorrendben – ez determinisztikus kiválasztás (az első N elem), nem véletlenszerű. A false értékű előfeltételű elemeket a motor költség nélkül átugorja (a hely NEM fogy el), így N-nél kevesebb elem is megjelenhet, ha az előfeltételek kimerítik a készletet.

Az az elem, amelyet a korlát kihagy, hiányzónak számít, nem megválaszoltnak. Ha a Group már megkérdezte az N elemét, a rendszer elutasítja, ha a kitöltés lépéslistájában valaki egy kihagyott elemre ugrana, és ugyanígy az API-n (submit_survey_response) keresztül az elemnek küldött választ is. A Group által megkérdezett elem továbbra is módosítható. Az az elem, amelyre az API-n keresztül érkezik válasz, vagy amelyre a válaszadó ugrik, miközben a Groupban még van szabad hely, elfoglalja ezt a helyet, így a Group összesen sosem kérdez meg N-nél több elemet. A helyét akkor is megtartja, ha a válaszadó visszalép a Group elé, majd változtatás nélkül ismét előrehalad: az elem újra megjelenik a válaszával, ahelyett, hogy egy korábbi elem lépne a helyébe.

Független belső elemek szükségesek: a count értékkel korlátozott Group belső elemeinek függetleneknek kell lenniük – egyetlen belső elem sem függhet ugyanazon Group egy másik belső elemétől (sem közvetlenül, sem közös változón keresztül). A korlát bármelyik elemet kiszoríthatja, így a Groupon belüli függőség egy ki nem választott testvérelem válaszát olvashatná. A platform az ilyen Groupot az ellenőrzéskor elutasítja. (A count nélküli Group és a blokkok közötti függőségek nincsenek korlátozva.)

Kimenetek: a korlátozott Group belső elemei a szokásos, egyértékű outcome utat használják. A ki nem választott belső elem (előfeltétel miatt kihagyott, vagy az N korláton túli) kimenete outcome: null, és nem szerepel a Bronz exportban.