Syntaxe QML
QML (Questionnaire Markup Language) est un langage fondé sur YAML qui sert à créer des questionnaires vérifiés formellement. Cette page en donne un bref aperçu technique.
Présentation
Section intitulée « Présentation »QML permet :
- la vérification formelle de la logique du questionnaire à l’aide de solveurs SMT ;
- le branchement conditionnel au moyen de préconditions et de postconditions ;
- des résultats entiers pour toutes les réponses, ce qui ouvre la voie à l’analyse mathématique ;
- l’intégration de code Python pour les calculs (sous-ensemble restreint, compatible avec la vérification).
Composants clés
Section intitulée « Composants clés »Structure
Section intitulée « Structure »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
Section intitulée « qmlVersion »qmlVersion indique la version minimale du schéma QML dont votre document
a besoin, sous la forme Major.Minor.Patch :
- une version MAJEURE introduit des changements incompatibles : un document écrit pour une version majeure antérieure peut ne plus être valide, ou une construction existante peut se comporter autrement ;
- une version MINEURE ne fait qu’ajouter des possibilités facultatives : tout document écrit pour une version mineure antérieure de la même version majeure reste valide ;
- une version CORRECTIVE (PATCH) ne modifie jamais le contrat (formulation, précisions, corrections).
La version actuelle du schéma est la 2.7.0. La version 2.0.0 était une version
majeure incompatible qui a ramené les types de blocs à Group (le type par défaut, parcouru une seule fois,
éventuellement plafonné par count) et Roster ; les documents écrits pour une
version majeure antérieure (qui utilisaient les types Sequence/Sample, supprimés) doivent être
migrés. La version mineure 2.1.0 a ajouté la clé facultative subjectFrom sur les blocs
Roster (voir Roster), la 2.1.1 était un correctif qui resserrait les règles, et la version mineure 2.2.0
a ajouté l’indicateur facultatif external sur un item (voir
Entrées externes) : autant d’ajouts rétrocompatibles,
si bien que tout document 2.0.0 reste valide. Déclarer qmlVersion: "2.0"
suffit pour le chargement ; utilisez "2.2" si vous vous appuyez sur external. La version mineure 2.5.0
a fait d’une réponse Range et de son default une paire [low, high] (voir
Contrôle : Range) ; utilisez "2.5" si vous donnez un default à un Range.
La version mineure 2.6.0 refuse une clé input qu’un contrôle ne déclare pas, de sorte qu’une
faute de frappe comme lables devient une erreur au lieu d’être ignorée en silence, et elle déclare
minLength pour Textarea et left / right pour Switch.
Le correctif 2.6.1 refuse un id d’item qui n’est pas un nom simple
(lettres, chiffres et traits de soulignement, sans chiffre en tête, et qui n’est ni un
mot-clé Python ni un nom intégré comme len, sum ou math), car une
condition lit un item sous la forme <id>.outcome.
Le correctif 2.6.2 maintient l’arithmétique QML dans les nombres entiers : tout code d’auteur
susceptible de produire une fraction (/, un littéral décimal, float) est refusé au
chargement du questionnaire ; utilisez // à la place.
Le correctif 2.6.3 fait du default d’un Range une paire de nombres entiers, comme toute
réponse Range.
Le correctif 2.6.4 refuse un default situé hors du domaine de réponse de l’item : un
questionnaire dont la valeur par défaut ne correspond à aucune réponse possible ne se charge pas.
La version mineure 2.7.0 ajoute l’indicateur facultatif invented sur une postcondition (voir
Logique conditionnelle) ; utilisez "2.7" si vous l’écrivez.
La version du schéma est
indépendante de la version interne de la plateforme.
Types d’items
Section intitulée « Types d’items »- Comment : affiche du texte sans recueillir de réponse
- Question : un seul résultat entier
- QuestionGroup : un vecteur de résultats entiers
- MatrixQuestion : une matrice de résultats entiers
Contrôles de saisie
Section intitulée « Contrôles de saisie »- Switch : binaire (0/1)
- Radio : choix unique parmi des options libellées
- Checkbox : choix multiple (codage en masque de bits)
- Dropdown : choix unique avec préfixe/suffixe
- Editbox : nombre entier libre compris dans [min, max]
- Textarea : texte libre ; le résultat est une chaîne, exclue de la vérification formelle
- Slider : sélection visuelle d’un entier
- Range : sélection d’un intervalle ; le résultat est une paire
[low, high]
Logique conditionnelle
Section intitulée « Logique conditionnelle »Les préconditions déterminent la visibilité :
precondition: - predicate: q_age.outcome >= 18Les postconditions imposent des contraintes :
postcondition: - predicate: q_children.outcome < q_household.outcome hint: "Children must be fewer than household size"Une postcondition peut porter invented: true. L’import d’un questionnaire
la pose sur une vérification que la source n’énonçait pas comme une règle stricte, par exemple une vérification
non bloquante ou une règle tirée d’une consigne destinée à l’enquêteur (« relancer si heures > 80 »), afin que vous
puissiez la confirmer ou la modifier avant publication. L’indicateur ne change rien à
l’enquête ni au validateur, et les répondants ne le voient jamais ; l’éditeur signale chacune
de ces vérifications. Retirez-le une fois la vérification confirmée. Les préconditions ne
l’acceptent pas.
postcondition: - predicate: q_hours.outcome <= 80 hint: "More than 80 hours a week: please check the number" invented: trueUn bloc remplit trois fonctions. Il regroupe des items liés en une section ; il crée un branchement,
car une precondition au niveau du bloc conditionne tous les items du bloc ; et, en tant que
Roster, il répète ses items une fois par entité sélectionnée. Les conditions du bloc et
de l’item sont combinées pendant l’enquête (celles du bloc d’abord, puis celles de l’item, et toutes
doivent être vraies), et le validateur les combine de la même manière.
Conditionnez une branche au niveau du bloc. Une suite d’au moins deux items qui partagent une même condition a sa place dans un bloc à part qui porte cette condition ; un item ne garde sa propre précondition que pour ce qui lui est spécifique. Écrivez la condition une seule fois, et non sur chaque 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}Une condition de bloc lit les réponses et les variables des items situés avant le bloc. Elle est réévaluée avant chaque item : si elle lit une variable qu’un bloc de code situé dans ce même bloc affecte, elle change en cours de bloc, et dès que deux items affectent cette variable, le validateur signale un cycle de dépendances. Les blocs suivent l’ordre du fichier : placez donc un bloc conditionnel après l’item qui en décide. Les blocs ne s’imbriquent pas ; une branche dans une branche s’écrit avec une condition de bloc plus une précondition d’item, ou avec un bloc supplémentaire. La précondition d’un item ne s’applique jamais à l’item suivant : un item conditionnel situé hors d’un bloc conditionnel énonce donc sa propre condition complète.
Une question laissée sans réponse. Lorsqu’une question est présentée au répondant et qu’il la laisse
vide, une condition qui lit sa réponse est tranchée par les réponses disponibles : ainsi,
q_a.outcome == 1 or q_b.outcome == 1 reste vraie si seule q_a a reçu la réponse 1. Si
la réponse manquante pouvait encore changer le résultat, une précondition masque sa question et
une postcondition laisse passer la réponse. Dans les deux cas, l’enquête enregistre un avertissement, qui
reste dans votre jeu de données. Pour orienter les personnes dont une réponse manque vers un endroit précis, testez
explicitement ce cas :
precondition: - predicate: q_marital.outcome is None or q_marital.outcome != 3Le validateur comprend ce test : une condition qui vérifie si une question simple a reçu une réponse est vérifiée comme n’importe quelle autre comparaison, pourvu que le test précède les autres utilisations de cette réponse dans la condition, comme c’est le cas ici.
Le validateur tient aussi compte des réponses vides lorsqu’il classe une question. Une précondition qui lit une réponse que le répondant peut laisser vide est signalée comme atteinte sous condition, et non comme toujours atteinte, car une réponse vide masque la question. Pour rendre une réponse obligatoire, donnez à cette question sa propre postcondition q_marital.outcome is not None ; le validateur sait alors qu’elle n’est jamais laissée vide.
Une question qui n’a jamais été présentée parce que sa propre précondition l’a masquée est un cas différent : sa
réponse est simplement vide, et une condition comme q_pregnant.outcome != 1 la traite comme telle.
Compter d’un bout à l’autre d’un bloc. La précondition d’un bloc est réévaluée avant chacune de ses questions ; un compteur que les questions mettent à jour peut donc mettre fin au bloc de façon anticipée :
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 wayChaque question voit le compteur tel que l’ont laissé les questions qui la précèdent dans le fichier ; son
propre bloc de code s’exécute après ses propres conditions. Le validateur le lit de la même manière : une condition
que le compteur ne peut jamais satisfaire (negative_count < 0) est signalée comme inatteignable, et il en va
de même pour un compteur lu par la propre précondition d’une question. Une question laissée vide rend le
compteur inconnu (son bloc de code a lu une réponse manquante) ; le reste du bloc est alors
sauté : tel qu’il est écrit, seule la première question est toujours posée. Donnez à chaque question la
postcondition q_concept_1.outcome is not None (et ainsi de suite) pour exiger une réponse ; le
validateur signale alors les trois premières questions comme toujours posées et les suivantes comme
conditionnelles.
Entrées externes (préremplissage)
Section intitulée « Entrées externes (préremplissage) »Les instruments réels s’appuient souvent, pour leurs branchements, sur une valeur qu’aucune question ne recueille : un indicateur
de sortie de panel, un groupe de split-ballot, le sexe ou l’état matrimonial issus d’un fichier
d’échantillon, une réponse d’une vague précédente. Marquez un tel item external: true (schéma
2.2.0+) pour le déclarer éligible au préremplissage :
- id: q_rotate_out kind: Question title: "Is this respondent rotating out this wave?" external: true input: control: Radio labels: 0: "No" 1: "Yes"Pour le reste, un item externe est une question tout à fait normale : il possède un véritable
domaine input: et peut avoir des préconditions, des postconditions et un bloc de
code, et Z3 le vérifie exactement comme le même item sans l’indicateur
(l’indicateur n’ajoute aucune logique à prouver). À l’initialisation de l’enquête, la plateforme tente de
répondre d’avance à cet item à partir de l’enregistrement du répondant (données démographiques et attributs
importés), relié pour chaque campagne par une correspondance que configure un opérateur. Lorsqu’une
valeur est trouvée et qu’elle est valide pour le domaine de l’item, l’item reçoit automatiquement sa réponse et
est masqué ; en l’absence de valeur (ou si elle sort du domaine), l’item est simplement
posé dans le déroulement normal : le préremplissage est une optimisation, jamais un obstacle.
La correspondance des sources item par item est une propriété administrative configurée par campagne (dans Targetor), et non dans le fichier QML : un même questionnaire peut ainsi fonctionner avec un câblage de préremplissage différent selon la campagne. Une valeur renseignée automatiquement est signalée dans les données comme fournie de l’extérieur, ce qui permet à l’analyse de la distinguer d’une réponse donnée par le répondant lui-même.
external: true est la manière officielle de conditionner sur une valeur extérieure : elle
remplace les anciens contournements (un nom non défini, une constante codeInit
figée, ou une question de préambule intitulée ADMIN:) que le validateur
signale désormais.
Blocs de code
Section intitulée « Blocs de code »Sous-ensemble restreint de Python, compatible avec la vérification formelle :
Pris en charge :
- Arithmétique sur des nombres entiers :
+,-,*,//(division entière),%,**avec un exposant positif ou nul - Comparaisons :
<,<=,>,>=,==,!= - Booléens :
and,or,not - Structures de contrôle :
if/elif/else,for(limité) - Opérateur ternaire :
x = 1 if condition else 0 - Dépaquetage de tuples :
a, b = 1, 0 - Fonctions intégrées :
range(),abs(),int(),bool() - Accès aux résultats :
item.outcome
Non pris en charge :
- Tout ce qui produit une fraction :
/, un nombre décimal (0.5),float(), un exposant négatif (2 ** -1), ou une fonction à résultat fractionnaire commemath.sqrt,statistics.meanourandom.random. Chaque réponse est un nombre entier et chaque condition est vérifiée sur les nombres entiers ; un questionnaire qui utilise l’un de ces éléments ne se charge donc pas, et le message indique où il se trouve. Changez plutôt d’échelle : un pourcentage s’écrit100 * part // total, une moyenne en dixièmes10 * total // n, et un tirage aléatoirerandom.randint(1, 6). - Fonctions, classes, imports
- Boucles while, break, continue
- Dictionnaires, méthodes de chaînes
Exemples complets
Section intitulée « Exemples complets »Cette section illustre tous les types d’items et de contrôles par des exemples fonctionnels.
Type d’item : Comment
Section intitulée « Type d’item : Comment »Affiche un texte d’information sans recueillir de réponse :
- id: intro_comment kind: Comment title: "Welcome to our demographic survey. Your responses help us understand our community better."L’affichage d’un commentaire peut être conditionnel :
- id: parent_notice kind: Comment title: "The following questions are about your children." precondition: - predicate: q_has_children.outcome == 1Type d’item : Question
Section intitulée « Type d’item : Question »Questions à résultat unique, avec différents types de contrôles.
Contrôle : Switch
Section intitulée « Contrôle : Switch »Choix binaire (0 = désactivé, 1 = activé) :
- id: q_has_children kind: Question title: "Do you have children?" input: control: Switch off: "No" on: "Yes" default: 0off / on légendent les deux côtés ; left / right légendent les mêmes côtés
lorsque off / on ne sont pas fournis.
Contrôle : Radio
Section intitulée « Contrôle : Radio »Choix unique parmi des options libellées :
- 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: 1Contrôle : Dropdown
Section intitulée « Contrôle : Dropdown »Choix unique avec texte de préfixe/suffixe facultatif :
- 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"Contrôle : Checkbox
Section intitulée « Contrôle : Checkbox »Choix multiple (codage en masque de bits) :
- 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 = 16Sélectionner « Reading » et « Music » produit le résultat : 1 | 4 = 5
Contrôle : Editbox
Section intitulée « Contrôle : Editbox »Saisie libre d’un nombre entier, avec bornes. Une réponse hors de l’intervalle min..max, ou comportant une partie décimale, est refusée, et le répondant est invité à saisir un nombre entier dans l’intervalle. Un Editbox n’accepte pas de step ; pour recueillir une valeur décimale, changez d’échelle (demandez des centimes plutôt que des euros).
- 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"Contrôle : Textarea
Section intitulée « Contrôle : Textarea »Saisie de texte libre (question ouverte). Le résultat est une chaîne (et non un entier) ; il est donc ignoré par l’analyse Z3 : faire référence au résultat d’un Textarea dans une précondition, une postcondition ou un bloc de code est une erreur de conception que le validateur signale. Utilisez ce contrôle pour des retours qualitatifs, des suggestions ou des commentaires qui appellent une réponse rédigée.
- id: q_feedback kind: Question title: "Describe your experience with our service." input: control: Textarea placeholder: "Type your answer here..." maxLength: 500Propriétés facultatives :
placeholder: texte indicatif affiché lorsque la zone de texte est videminLength: nombre minimal de caractères attendus (enregistré, non imposé)maxLength: nombre maximal de caractères autorisés
Contrôle : Slider
Section intitulée « Contrôle : Slider »Sélection visuelle d’un entier :
- 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: 5Contrôle : Range
Section intitulée « Contrôle : Range »Sélection d’un intervalle à l’aide de deux curseurs. Le résultat est une liste de deux éléments [low, high] telle que 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]Sélectionner de 100 à 500 enregistre [100, 500]. Un default, s’il est fourni, est lui aussi une paire de nombres entiers : les positions de repos des deux curseurs.
Lisez les bornes par leur nom : q_price_range.outcome.low est la borne inférieure et q_price_range.outcome.high la borne supérieure. Un indice comme outcome[0], ou la comparaison de la réponse avec une liste (outcome == [100, 500]), n’est pas accepté.
- 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: TextareaAucune garde is not None n’est nécessaire : un Range sans réponse laisse la condition indéterminée à l’exécution, si bien qu’une précondition qui le lit fait sauter son item. Dans un QuestionGroup doté d’un contrôle Range, le résultat est une liste d’intervalles ; dans une MatrixQuestion, c’est un tableau lignes × colonnes d’intervalles, chacun lu sous la forme m.outcome[j][k].low / m.outcome[j][k].high. Un bloc de code affecte une réponse Range avec une paire, q.outcome = [low, high].
Type d’item : QuestionGroup
Section intitulée « Type d’item : QuestionGroup »Vecteur de résultats, avec un contrôle identique pour chaque sous-question :
- 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"Accédez aux résultats par indice : qg_family_ages.outcome[0], qg_family_ages.outcome[1], etc.
Le validateur statique prouve les conditions qui lisent une seule réponse, qg.outcome[i]. Tant que le groupe n’a pas reçu de réponse, son résultat vaut None (groupe exclu par une condition, ou présenté et laissé vide) : toute lecture qg.outcome[i] fait alors échouer une précondition et lève une postcondition ; testez d’abord qg.outcome is not None pour conditionner sur le groupe lui-même. Dans un groupe qui a reçu une réponse, les réponses manquantes valent None : qg.outcome[0] != 1 est vraie pour une réponse vide, qg.outcome[0] > 1 ne l’est pas. La comparaison de la liste entière (qg.outcome == 1), un ensemble de réponses, un groupe placé dans un Roster ou dans un Group plafonné, et un bloc de code qui écrit dans un groupe sont appliqués à l’exécution mais non vérifiés, et sont signalés par des avertissements skipped_condition.
Type d’item : MatrixQuestion
Section intitulée « Type d’item : MatrixQuestion »Matrice de résultats (lignes × colonnes) :
- 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"Accédez aux résultats par indice de ligne et de colonne : mq_language_proficiency.outcome[0][1] pour la première langue (anglais) et le deuxième membre de la famille (conjoint).
La matrice crée une grille dont chaque cellule représente la maîtrise d’une langue par un membre de la famille. Cet exemple produit une matrice 5×4 (5 langues × 4 membres de la famille), soit 20 résultats individuels.
Exemple complexe avec blocs de code
Section intitulée « Exemple complexe avec blocs de code »Illustration des préconditions, des postconditions et des blocs de code :
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"Cet exemple illustre :
- la visibilité conditionnelle : les questions sur les revenus se trouvent dans un bloc conditionné par l’emploi, écrit une seule fois ;
- les blocs de code : suivi du revenu cumulé d’une question à l’autre ;
- la validation par postcondition : vérifier que le revenu du ménage est cohérent avec les revenus individuels ;
- les dépendances en chaîne : chaque question dépend des réponses précédentes.
Types de blocs
Section intitulée « Types de blocs »kind est facultatif et vaut Group par défaut. Valeurs reconnues :
| Type | Sémantique |
|---|---|
Group (par défaut) |
Pose une fois chaque item interne applicable, dans l’ordre canonique (topologique). Un count: N facultatif plafonne le bloc aux N premiers items éligibles (voir plus bas). |
Roster |
Répète les items internes pour chaque bit à 1 d’un masque de bits iterateOver (voir plus bas). |
Les blocs de tout type peuvent aussi porter des listes facultatives precondition et postcondition qui s’appliquent à chaque item interne (les règles du bloc s’appliquent avant celles de l’item). Un Roster dont la précondition est fausse est sauté en entier ; si elle est vraie, il itère sur iterateOver comme d’habitude. La validation statique (Z3) tient compte du type : un Roster est déroulé par clé de libellé en copies gardées par bit ; un Group plafonné par count traite ses items internes comme présents sous condition, avec un tirage de N items au plus.
Un bloc Roster (kind: Roster) répète ses items internes une fois par clé de libellé active. L’auteur déclare :
iterateOver: une expression Python dont la valeur doit être un entier positif ou nul, traité comme un masque de bits ;labels: une table qui associe des clés entières puissances de 2 (1, 2, 4, 8, 16, …) à des chaînes d’affichage ; elle déclare l’univers des itérations possibles.
Le moteur parcourt les bits à 1 de iterateOver, du bit de poids faible au bit de poids fort. Pour chaque bit à 1 dont la clé figure dans labels, les items internes sont exécutés une fois, avec la valeur de ce bit comme identité propre de l’itération.
Chaque réponse à un item de Roster appartient à une itération. Une réponse envoyée par l’API (submit_survey_response) à un item de Roster qui n’a jamais été posé, alors qu’aucune itération du Roster n’est en cours (avant que l’enquête n’atteigne le Roster, ou après qu’elle l’a quitté), est refusée, tout comme un saut vers un tel item dans la liste des étapes. Une réponse que le Roster détient déjà peut toujours être modifiée : elle est rouverte dans l’itération où elle a été donnée.
La v1 propose deux formes de rédaction :
1. Piloté par un choix multiple (la Checkbox alimente directement le roster)
Section intitulée « 1. Piloté par un choix multiple (la Checkbox alimente directement le roster) »Le résultat d’une Checkbox EST le masque de bits lui-même, sous forme d’entier (somme des clés puissances de 2 sélectionnées). Il passe directement dans iterateOver, sans code intermédiaire :
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: TextareaLe répondant coche Breakfast + Dinner → q_meals_eaten.outcome = 5 (bit 1 + bit 4) → le moteur parcourt deux itérations : bit 1 (Breakfast), puis bit 4 (Dinner).
2. Question numérique « Combien ? » (un calcul simple construit le masque)
Section intitulée « 2. Question numérique « Combien ? » (un calcul simple construit le masque) »Pour un nombre saisi, un codeBlock en amont construit un masque des « N premiers bits » par un calcul simple (2 ** n - 1). Aucun opérateur de décalage de bits (<<) n’est nécessaire :
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: 120Le répondant indique 3 → le codeBlock calcule family_mask = 2 ** 3 - 1 = 7 → le moteur parcourt les bits 1, 2 et 4.
Nommer chaque itération (subjectFrom)
Section intitulée « Nommer chaque itération (subjectFrom) »Par défaut, chaque itération prend pour titre son entrée statique dans labels (« Member 1 », « Member 2 »…). Lorsque le répondant fournit un nom plus parlant au sein de l’itération (le prénom d’un membre de la famille, un produit qu’il possède), faites pointer la clé facultative subjectFrom du bloc vers l’id de cet item interne : sa réponse pour chaque itération devient le sujet affiché de l’itération. Tant que cet item n’a pas reçu de réponse, l’affichage revient à l’entrée statique de labels.
- 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 ne change que le libellé affiché : la clé de bit canonique (puissance de 2) reste l’identité de l’itération pour le stockage, l’export et les références entre itérations. Elle nécessite qmlVersion: "2.1" (ou supérieure).
Lire les résultats d’un roster depuis l’extérieur
Section intitulée « Lire les résultats d’un roster depuis l’extérieur »À l’intérieur d’une itération du roster, q_satisfaction.outcome renvoie la valeur de l’itération courante (instantané/restauration). À l’extérieur du roster (blocs de code postérieurs au roster, préconditions d’items ultérieurs), utilisez la forme dictionnaire 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"Ou agrégez sur les itérations :
total_satisfaction = sum(q_satisfaction.outcomes.values())Contraintes (v1)
Section intitulée « Contraintes (v1) »iterateOverest strictement une expression entière : les types liste/séquence ne sont pas acceptés.- Les clés de
labelsdoivent être des puissances de 2 positives (1, 2, 4, 8, 16, …) ; le chargeur rejette toute autre valeur avec un message d’erreur clair. - Les contrôles Checkbox imposent eux aussi des clés de libellé puissances de 2, ce qui aligne la sémantique de Checkbox sur celle de Roster : le résultat d’une Checkbox passe ainsi directement dans
iterateOver. - Pas d’interpolation de chaînes dans les titres. Les titres des items s’affichent tels quels ; l’habillage propre à chaque itération (par exemple « 2 of 4 · Lunch ») est rendu par l’interface de l’enquête à partir de la table
labels[<bit>]. - Pas d’opérateurs de décalage de bits
<</>>dans les blocs de code d’auteur : utilisez un calcul simple (2 ** n - 1pour « les N premiers bits »). L’opérateur**est autorisé. - Pas de listes en compréhension dans les blocs de code d’auteur (coût de traduction pour Z3).
as(liaison d’une variable d’itération) etmaxEntriesne sont pas pris en charge en v1 : la conception par masque de bits rend les deux inutiles.- Les rosters imbriqués (un Roster dans un Roster) ne sont pas pris en charge en v1.
- L’autoréférence dans iterateOver (référence à un item situé dans le même Roster) est rejetée au chargement.
Forme de l’export Bronze
Section intitulée « Forme de l’export Bronze »Chaque Roster produit un nombre fixe de colonnes : len(labels) × len(inner items). Nommage des colonnes : {block_id}_{bit_key}_{item_id}. Les cellules des clés de libellé inactives dans une enquête valent NULL. Le schéma est entièrement déterminé par la seule déclaration QML.
Exemple (per_meal avec 4 libellés × 2 items internes = 8 colonnes) :
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_notesS’y ajoute la colonne externe q_meals_eaten.
Un export Gold au format long est disponible en tant que transformation facultative : il remodèle le jeu de données Bronze, au format large, en un jeu de données parent (sans les colonnes du roster) plus un jeu de données enfant par Roster, avec les colonnes survey_id, iteration_key, <inner_item>..., une forme naturelle pour les analyses qui regroupent par itération.
Quand utiliser QuestionGroup ou Roster
Section intitulée « Quand utiliser QuestionGroup ou Roster »Utilisez QuestionGroup pour plusieurs questions sur une même page (un seul attribut répété, nombre fixe, sans habillage de titre par itération).
Utilisez Roster pour des questions par élément, chacune sur sa propre page : nombre déterminé à l’exécution (numérique ou choix multiple), un item interne par page, parcours en profondeur itération par itération.
Plafonnement d’un Group par count
Section intitulée « Plafonnement d’un Group par count »Un bloc Group accepte un count: N facultatif qui le plafonne aux N premiers items internes éligibles, tirés de façon déterministe dans l’ordre canonique. Sans count, un Group pose tous ses items applicables.
count: le N, un littéral entier positif facultatif. Absent → tous les items sont posés. Présent → le chargeur rejette explicitement uncountnégatif ou nul ; il n’y a pas de valeur par défaut implicite.
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"Avec count: 3, le moteur pose les 3 premiers des 5 items dans l’ordre canonique (topologique) : un tirage déterministe des N premiers, et non une sélection aléatoire. Les items dont la précondition vaut false sont sautés sans rien coûter (la place n’est PAS consommée), si bien que moins de N items peuvent être présentés lorsque les préconditions épuisent le réservoir.
Un item que le plafond écarte est absent : il n’est pas considéré comme ayant reçu une réponse. Une fois que le Group a posé ses N items, un saut vers un item écarté dans la liste des étapes de l’enquête est refusé, tout comme une réponse qui lui est envoyée par l’API (submit_survey_response). Un item que le Group a posé peut toujours être modifié. Un item qui reçoit une réponse par l’API, ou qui est atteint par un saut, alors que le Group dispose encore d’une place libre, occupe cette place : le Group ne pose donc jamais plus de N items au total. Il conserve la place lorsque le répondant revient avant le Group puis avance de nouveau sans rien modifier : l’item est présenté de nouveau avec sa réponse, au lieu d’être remplacé par un item antérieur.
Items internes indépendants obligatoires : les items internes d’un Group plafonné par count doivent être indépendants ; aucun item interne ne peut dépendre d’un autre item interne du même Group (directement ou par une variable partagée). Le plafond peut écarter n’importe quel item, de sorte qu’une dépendance interne au Group pourrait lire la réponse d’un item voisin non tiré. La plateforme rejette un tel Group à la validation. (Un Group sans count, ainsi que les dépendances entre blocs, ne sont soumis à aucune restriction.)
Résultats : les items internes d’un Group plafonné passent par le chemin outcome normal, à valeur unique. Un item interne non tiré (sauté par sa précondition ou au-delà du plafond N) a outcome: null et est absent de l’export Bronze.