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.
Áttekintés
Szekció neve “Áttekintés”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).
Fő összetevők
Szekció neve “Fő összetevők”Szerkezet
Szekció neve “Szerkezet”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
Szekció neve “qmlVersion”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.
Elemtípusok
Szekció neve “Elemtípusok”- 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
Beviteli vezérlők
Szekció neve “Beviteli vezérlők”- 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
Feltételes logika
Szekció neve “Feltételes logika”Az előfeltételek a láthatóságot határozzák meg:
precondition: - predicate: q_age.outcome >= 18Az 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: trueA 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 != 3A 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 = 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 wayMinden 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.
Külső bemenetek (előtöltés)
Szekció neve “Külső bemenetek (előtöltés)”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.
Kódblokkok
Szekció neve “Kódblokkok”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áulmath.sqrt,statistics.meanvagyrandom.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ék100 * part // total, a tizedekben kifejezett átlag10 * total // n, a véletlen húzás pedigrandom.randint(1, 6). - Függvények, osztályok, importok
- While ciklusok, break, continue
- Szótárak, karakterlánc-metódusok
Teljes példák
Szekció neve “Teljes példák”Ez a szakasz működő példákon mutatja be az összes elemtípust és vezérlőtípust.
Elemtípus: Comment
Szekció neve “Elemtípus: Comment”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 == 1Elemtípus: Question
Szekció neve “Elemtípus: Question”Egyetlen kimenetű kérdések különféle vezérlőtípusokkal.
Vezérlő: Switch
Szekció neve “Vezérlő: Switch”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: 0Az off / on a két oldal felirata; a left / right ugyanezeket az oldalakat feliratozza,
ha az off / on nincs megadva.
Vezérlő: Radio
Szekció neve “Vezérlő: Radio”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: 1Vezérlő: Dropdown
Szekció neve “Vezérlő: Dropdown”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"Vezérlő: Checkbox
Szekció neve “Vezérlő: Checkbox”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 = 16A „Reading” és a „Music” kiválasztása ezt a kimenetet adja: 1 | 4 = 5
Vezérlő: Editbox
Szekció neve “Vezérlő: Editbox”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"Vezérlő: Textarea
Szekció neve “Vezérlő: Textarea”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: 500Opcionális tulajdonságok:
placeholder: az üres szövegmezőben megjelenő segédszövegminLength: a várt legkisebb karakterszám (a rendszer rögzíti, de nem kényszeríti ki)maxLength: a megengedett legnagyobb karakterszám
Vezérlő: Slider
Szekció neve “Vezérlő: Slider”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: 5Vezérlő: Range
Szekció neve “Vezérlő: Range”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: TextareaNincs 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].
Elemtípus: QuestionGroup
Szekció neve “Elemtípus: QuestionGroup”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.
Elemtípus: MatrixQuestion
Szekció neve “Elemtípus: MatrixQuestion”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.
Összetett példa kódblokkokkal
Szekció neve “Összetett példa kódblokkokkal”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.
Blokktípusok
Szekció neve “Blokktípusok”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.
Roster
Szekció neve “Roster”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: TextareaA 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: 120A 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: 120A 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())Megszorítások (v1)
Szekció neve “Megszorítások (v1)”- Az
iterateOverszigorúan egész értékű kifejezés – lista- és szekvenciatípusok nem elfogadottak. - A
labelskulcsainak 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 - 1az „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 amaxEntriesaz 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.
A Bronz export alakja
Szekció neve “A Bronz export alakja”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_notesEhhez 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 darabszám-korlátja
Szekció neve “A Group darabszám-korlátja”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ívcounté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.