Aller au contenu
Base de connaissances

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.

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).
qmlVersion: "2.0"
questionnaire:
title: "Survey Title"
codeInit: |
# Python initialization code
blocks:
- id: b_section
kind: Group # Optional, defaults to Group. Group | Roster
precondition: # Optional: gates every item in the block (branching)
- predicate: condition
items:
- id: q_item
kind: Question
precondition:
- predicate: condition
postcondition:
- predicate: validation
input:
control: ControlType

qmlVersion 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.

  • 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
  • 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]

Les préconditions déterminent la visibilité :

precondition:
- predicate: q_age.outcome >= 18

Les 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: true

Un 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 != 3

Le 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 = 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

Chaque 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.

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.

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 comme math.sqrt, statistics.mean ou random.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’écrit 100 * part // total, une moyenne en dixièmes 10 * total // n, et un tirage aléatoire random.randint(1, 6).
  • Fonctions, classes, imports
  • Boucles while, break, continue
  • Dictionnaires, méthodes de chaînes

Cette section illustre tous les types d’items et de contrôles par des exemples fonctionnels.

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 == 1

Questions à résultat unique, avec différents types de contrôles.

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: 0

off / 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.

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: 1

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"

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 = 16

Sélectionner « Reading » et « Music » produit le résultat : 1 | 4 = 5

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"

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: 500

Propriétés facultatives :

  • placeholder : texte indicatif affiché lorsque la zone de texte est vide
  • minLength : nombre minimal de caractères attendus (enregistré, non imposé)
  • maxLength : nombre maximal de caractères autorisés

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: 5

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: Textarea

Aucune 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].

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.

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.

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.

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: Textarea

Le 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: 120

Le répondant indique 3 → le codeBlock calcule family_mask = 2 ** 3 - 1 = 7 → le moteur parcourt les bits 1, 2 et 4.

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: 120

subjectFrom 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())
  • iterateOver est strictement une expression entière : les types liste/séquence ne sont pas acceptés.
  • Les clés de labels doivent ê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 - 1 pour « 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) et maxEntries ne 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.

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_notes

S’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.

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.

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 un count né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.