Créer des enquêtes avec QML
Ce guide explique comment créer des enquêtes avec QML (Questionnaire Markup Language), un langage fondé sur YAML et conçu pour des questionnaires élaborés, avec vérification formelle, contrôle dynamique du parcours et validation des données.

L’éditeur d’Armiger dans le navigateur : l’explorateur de projet et le chat Génération par IA (à gauche), le code QML (au centre), le diagramme de parcours et un aperçu en direct de la question sélectionnée (à droite).
Démarrage rapide
Section intitulée « Démarrage rapide »Tout questionnaire QML commence par cette structure :
qmlVersion: "2.0"questionnaire: title: "Your Survey Title" blocks: - id: b_first_section title: "First Section" items: - id: q_first_question kind: Question title: "Your first question" input: control: Radio labels: 1: "Option 1" 2: "Option 2"Le champ qmlVersion déclare la version majeure de QML visée par votre document. La version majeure actuelle est la 2 : écrivez donc "2.0" (ou "2.1" pour utiliser les fonctionnalités facultatives les plus récentes). Les documents écrits pour l’ancienne grammaire 1.x ne se chargent plus et doivent être migrés. Pour la grammaire complète, les types d’items et les blocs avancés, consultez la référence de la syntaxe QML.
Notions de base
Section intitulée « Notions de base »Les blocs : organiser votre enquête
Section intitulée « Les blocs : organiser votre enquête »Un bloc remplit trois fonctions :
- Regroupement : il rassemble des questions liées dans une section.
- Branchement : sa précondition conditionne chacune de ses questions, si bien qu’une seule condition décide si le répondant voit l’ensemble de la séquence.
- Répétition : un bloc
Rosterpose ses questions une fois par entité sélectionnée (voir Types de blocs avancés).
L’usage le plus simple est le regroupement :
blocks: - id: b_demographics title: "About You" items: # Questions about the respondent
- id: b_preferences title: "Your Preferences" items: # Questions about preferencesPréconditions au niveau du bloc
Section intitulée « Préconditions au niveau du bloc »Les blocs peuvent avoir leurs propres préconditions. Lorsqu’un bloc a une précondition, elle s’applique automatiquement à chaque item du bloc — inutile de répéter la même condition sur chaque question.
blocks: - id: b_employment title: "Employment Details" precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50Dans cet exemple, q_job_title et q_years_employed héritent tous deux de la précondition du bloc q_employed.outcome == 1. Les items peuvent aussi définir leurs propres préconditions supplémentaires — la précondition du bloc est alors combinée avec celles des items.
Bonnes pratiques :
- Utilisez des identifiants explicites commençant par
b_(par ex.b_demographics,b_experience) - Regroupez les questions liées par leur thème
- Gardez autant que possible les dépendances à l’intérieur des blocs
- Lorsque deux questions ou plus partagent une même condition d’affichage, placez-les dans leur propre bloc et écrivez la condition une seule fois, sur le bloc ; ne gardez une précondition au niveau de l’item que pour une condition propre à cette question
- Une précondition de bloc lit les réponses et les variables des questions situées avant le bloc : placez donc le bloc après la question qui en décide
Types de blocs avancés
Section intitulée « Types de blocs avancés »Par défaut, un bloc est un Group qui pose chacun de ses items une fois. Deux variantes facultatives permettent des enquêtes plus dynamiques :
- Sections répétées (
Roster) — répètent un ensemble de questions une fois par élément sélectionné (par exemple, poser les mêmes questions sur chaque repas pris par le répondant, ou sur chaque membre de la famille). - Tirages adaptatifs (
count) — plafonnent unGrouppour qu’il ne pose que les N premiers items éligibles (par exemple, afficher 3 questions tirées d’un ensemble plus large).
Les deux sont détaillées, avec des exemples, dans la référence de la syntaxe QML.
Les items : types de questions
Section intitulée « Les items : types de questions »QML prend en charge quatre types d’items :
1. Comment (consignes)
Section intitulée « 1. Comment (consignes) »Affiche du texte sans recueillir de réponse :
- id: q_intro kind: Comment title: "Please answer honestly. Your responses are confidential."2. Question (réponse unique)
Section intitulée « 2. Question (réponse unique) »Pose une question et recueille une réponse :
- id: q_age kind: Question title: "What is your age?" input: control: Editbox min: 18 max: 1203. QuestionGroup (plusieurs questions liées)
Section intitulée « 3. QuestionGroup (plusieurs questions liées) »Pose plusieurs questions avec le même format de réponse :
- id: q_satisfaction kind: QuestionGroup title: "Rate your satisfaction with:" questions: - "Customer service" - "Product quality" - "Delivery speed" input: control: Radio labels: 1: "Very Dissatisfied" 2: "Dissatisfied" 3: "Neutral" 4: "Satisfied" 5: "Very Satisfied"4. MatrixQuestion (grille)
Section intitulée « 4. MatrixQuestion (grille) »Recueille des réponses sous forme de lignes et de colonnes :
- id: q_skills kind: MatrixQuestion title: "Rate your proficiency in:" rows: - "Python" - "JavaScript" - "SQL" columns: - "Beginner" - "Intermediate" - "Advanced" input: control: Radio labels: 1: "No experience" 2: "Some experience" 3: "Proficient"Contrôles de saisie
Section intitulée « Contrôles de saisie »Chaque question doit préciser comment les réponses sont recueillies.
Switch (oui/non)
Section intitulée « Switch (oui/non) »Choix binaire :
input: control: Switch on: "Yes" off: "No"Radio (un seul choix)
Section intitulée « Radio (un seul choix) »Sélection d’une option parmi plusieurs :
input: control: Radio labels: 1: "Option A" 2: "Option B" 3: "Option C"Checkbox (choix multiples)
Section intitulée « Checkbox (choix multiples) »Sélection de zéro, une ou plusieurs options :
input: control: Checkbox labels: 1: "Feature A" 2: "Feature B" 4: "Feature C" 8: "Feature D"Dropdown (choix dans une liste)
Section intitulée « Dropdown (choix dans une liste) »Sélection compacte parmi de nombreuses options :
input: control: Dropdown labels: 1: "High School" 2: "Bachelor's" 3: "Master's" 4: "PhD" left: "Education:"Editbox (saisie numérique)
Section intitulée « Editbox (saisie numérique) »Saisie libre d’un nombre :
input: control: Editbox min: 0 max: 1000000 left: "Annual income: $"Slider (échelle visuelle)
Section intitulée « Slider (échelle visuelle) »Sélection visuelle le long d’une échelle :
input: control: Slider min: 0 max: 10 step: 1 labels: 0: "Not at all" 5: "Somewhat" 10: "Extremely"Range (sélection d’un intervalle)
Section intitulée « Range (sélection d’un intervalle) »Sélection d’un intervalle à l’aide de deux curseurs (de… à…). La réponse est une paire [low, high] avec min <= low <= high <= max.
input: control: Range min: 0 max: 100 step: 5 labels: 0: "Minimum" 50: "Mid" 100: "Maximum" default: [20, 80]Textarea (texte libre)
Section intitulée « Textarea (texte libre) »Pour les réponses ouvertes et qualitatives, utilisez Textarea. Contrairement à tous les autres contrôles, son résultat est une chaîne de caractères, pas un entier — il n’est donc pas utilisable dans la logique de branchement ni dans la vérification formelle (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). Utilisez-le pour les commentaires, suggestions ou explications que vous comptez lire ou coder plus tard.
input: control: Textarea placeholder: "Tell us more..." maxLength: 500placeholder (texte indicatif affiché tant que le champ est vide) et maxLength (nombre maximal de caractères) sont tous deux facultatifs.
Logique conditionnelle
Section intitulée « Logique conditionnelle »Afficher des questions sous condition (préconditions)
Section intitulée « Afficher des questions sous condition (préconditions) »Utilisez les préconditions pour afficher des questions en fonction des réponses précédentes :
- id: q_has_car kind: Question title: "Do you own a car?" input: control: Switch
- id: q_car_brand kind: Question title: "What brand is your car?" precondition: - predicate: q_has_car.outcome == 1 input: control: Dropdown labels: 1: "Toyota" 2: "Honda" 3: "Ford"La question q_car_brand n’apparaît que si le répondant a répondu « Oui » à la question sur la possession d’une voiture.
Préconditions complexes :
precondition: - predicate: q_age.outcome >= 25 and q_employment.outcome in [1, 2, 3]Voir les branches : la vue en arbre du diagramme
Section intitulée « Voir les branches : la vue en arbre du diagramme »Le diagramme de parcours, à côté de votre QML, propose deux vues, entre lesquelles on bascule avec Séquence et Arbre, dans son coin supérieur gauche.
- Séquence (la vue par défaut) montre chaque question dans l’ordre où l’entretien la pose, avec ses conditions à côté.
- Arbre montre les mêmes questions sous forme de branches. Les questions qui partagent une même condition, qu’elle soit écrite sur leur bloc ou répétée sur chaque question, forment une seule branche, et une branche dont la condition ne peut être vraie qu’à l’intérieur d’une autre est dessinée à l’intérieur de celle-ci. Les chemins « oui » et « non » d’une question filtre apparaissent côte à côte, et une question de suivi posée uniquement sur le chemin « oui » y est imbriquée.
Ces relations sont démontrées avec Z3, et non devinées à partir du texte. L’arbre est calculé quand vous basculez vers lui : le premier basculement prend donc un instant ; s’il ne peut pas être calculé, le diagramme reste sur la séquence et en indique la raison. Chaque branche porte une étiquette qui indique ce que Z3 a établi :
| Marque | Signification |
|---|---|
| exclusif | Cette branche et sa voisine ne peuvent jamais s’appliquer toutes les deux : le répondant prend l’un ou l’autre chemin |
| parallèle | Les deux peuvent s’appliquer au même répondant : des séquences facultatives qui peuvent toutes deux être posées |
| ? exclusif, ? imbriqué, ? vraie | Z3 n’a pas pu trancher (par exemple pour une condition qu’il ne peut pas exprimer entièrement, ou une condition portant sur une réponse ou une valeur calculée à deux moments différents de l’entretien) : la branche est placée là où c’est démontré, et la marque indique ce qui reste indécis |
| jamais / toujours | La condition de la branche ne peut jamais être vraie, ou l’est toujours |
Deux questions dont la condition a le même texte ne forment une seule branche que si la condition a le même sens pour les deux : si un bloc de code situé entre elles modifie une variable que lit la condition, chacune obtient sa propre branche.
Les postconditions ne créent pas de branches : elles restent à côté de leurs questions dans les deux vues.
Valider les réponses (postconditions)
Section intitulée « Valider les réponses (postconditions) »Utilisez les postconditions pour garantir la cohérence logique :
- id: q_household_size kind: Question title: "How many people live in your household?" input: control: Editbox min: 1 max: 20
- id: q_children kind: Question title: "How many children under 18 live in your household?" postcondition: - predicate: q_children.outcome < q_household_size.outcome hint: "Number of children must be less than household size" input: control: Editbox min: 0 max: 15Si un répondant saisit des données incohérentes (par ex. 5 enfants dans un ménage de 3 personnes), le message d’aide s’affiche.
Blocs de code et variables
Section intitulée « Blocs de code et variables »QML permet d’intégrer du code Python pour les calculs et la logique dynamique.
Initialiser des variables
Section intitulée « Initialiser des variables »Utilisez codeInit pour mettre en place des variables de suivi :
questionnaire: codeInit: | total_score = 0 risk_level = 0Calculer après les réponses
Section intitulée « Calculer après les réponses »Rattachez des blocs de code aux items pour effectuer des calculs :
- id: q_satisfaction kind: Question title: "Rate your overall satisfaction (0-10)" codeBlock: | # Calculate satisfaction category if q_satisfaction.outcome >= 9: satisfaction_category = 3 # Promoter elif q_satisfaction.outcome >= 7: satisfaction_category = 2 # Passive else: satisfaction_category = 1 # Detractor
# Add to running total total_score += q_satisfaction.outcome input: control: Slider min: 0 max: 10Fonctionnalités Python prises en charge
Section intitulée « Fonctionnalités Python prises en charge »Le code QML s’exécute dans un bac à sable, mais seul un sous-ensemble de Python peut être traduit dans le modèle formel (Z3) qui vérifie votre questionnaire. Restez dans ce sous-ensemble pour que votre logique soit couverte par la vérification :
✓ Sous-ensemble vérifié :
- Arithmétique :
+,-,*,//,% - Comparaisons :
<,<=,>,>=,==,!=(y compris enchaînées, par ex.0 < x < 10) - Appartenance :
in,not in(par ex.q_x.outcome in [1, 2, 3]) - Logique booléenne :
and,or,not - Conditions :
if,elif,else - Expressions ternaires :
x = 1 if condition else 0 - Boucles for :
for i in range(n)(n ≤ 20) - Littéraux de listes, tuples et ensembles (≤ 20 éléments)
- Déballage de tuples :
a, b = 1, 0 - Affectation de variables :
x = value,x += value - Fonctions intégrées :
range(),abs(),int(),bool() - Accès aux résultats :
q_age.outcome
✗ Hors du sous-ensemble vérifié (voir la note ci-dessous) :
- imports, fonctions, classes
- boucles while,
break,continue - opérations sur les dictionnaires
- méthodes de chaînes
- compréhensions de listes
- instructions print (ignorées sans message)
Schémas courants
Section intitulée « Schémas courants »Divulgation progressive
Section intitulée « Divulgation progressive »Affichez les questions progressivement en fonction des réponses antérieures. Utilisez des préconditions de bloc pour ne pas répéter la même condition sur chaque item :
- id: b_screening items: - id: q_employed kind: Question title: "Are you currently employed?" input: control: Switch
- id: b_employment precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50q_job_title et q_years_employed héritent tous deux automatiquement de la précondition du bloc — ils n’apparaissent que si le répondant a un emploi.
Calcul de scores et catégorisation
Section intitulée « Calcul de scores et catégorisation »Calculez des scores et classez les répondants en catégories :
questionnaire: codeInit: | risk_score = 0
blocks: - id: b_assessment items: - id: q_factor1 kind: Question title: "Do you smoke?" codeBlock: | if q_factor1.outcome == 1: risk_score += 20 input: control: Switch
- id: q_factor2 kind: Question title: "Do you exercise regularly?" codeBlock: | if q_factor2.outcome == 0: risk_score += 15 input: control: Switch
- id: q_result kind: Comment title: "Assessment complete" codeBlock: | if risk_score >= 30: risk_category = "high" elif risk_score >= 15: risk_category = "moderate" else: risk_category = "low"Validation de la qualité des données
Section intitulée « Validation de la qualité des données »Garantissez la qualité des réponses par des vérifications de cohérence entre items :
- id: q_age kind: Question title: "Your age" input: control: Editbox min: 18 max: 100
- id: q_work_experience kind: Question title: "Years of work experience" postcondition: - predicate: q_work_experience.outcome <= (q_age.outcome - 16) hint: "Work experience cannot exceed your potential working years" input: control: Editbox min: 0 max: 60Bonnes pratiques
Section intitulée « Bonnes pratiques »Conception des questions
Section intitulée « Conception des questions »- Soyez précis : « Quel est le revenu annuel de votre ménage ? » plutôt que « Revenu ? »
- Choisissez des contrôles adaptés : Editbox pour des nombres précis, Slider pour des appréciations subjectives
- Fixez des bornes réalistes : min/max doivent refléter les contraintes du monde réel
- Donnez du contexte : utilisez les textes
left/rightpour les unités et les précisions
Gestion des dépendances
Section intitulée « Gestion des dépendances »- Gardez les items liés ensemble dans le même bloc
- L’ordre compte : une question doit apparaître avant d’être référencée
- Testez tous les chemins : assurez-vous que chaque question peut être atteinte
Stratégie de validation
Section intitulée « Stratégie de validation »- Définissez les contraintes de domaine avec les min/max des contrôles de saisie
- Utilisez des postconditions pour la cohérence logique
- Rédigez des messages d’aide utiles : des messages d’erreur clairs guident les répondants
- Pensez aux cas limites : que se passe-t-il si quelqu’un saisit des valeurs extrêmes ?
Recommandations pour les blocs de code
Section intitulée « Recommandations pour les blocs de code »- Initialisez tôt : mettez en place les variables dans
codeInit - Restez simple : les calculs complexes peuvent être difficiles à déboguer
- Pensez à la portée : toutes les variables sont globales
- Testez soigneusement : lancez le validateur de questionnaire
Vérification formelle
Section intitulée « Vérification formelle »Les questionnaires QML sont automatiquement validés pour :
- l’atteignabilité : chaque question peut-elle être atteinte ?
- la cohérence : les règles de validation sont-elles satisfiables ?
- les cycles : les dépendances forment-elles des cycles ?
- la complétude : existe-t-il au moins un chemin de passation valide ?
Le validateur s’appuie sur une analyse mathématique (résolution SMT) pour détecter les erreurs de conception avant la mise en production.
Voir la section Théorie pour les détails mathématiques.
Pour administrer un même questionnaire en plusieurs langues, ajoutez des traductions au lieu de le copier : une traduction ne remplace que le texte, si bien que la validation, les branchements et les codes de réponse restent ceux du questionnaire que vous avez rédigé.
Exemple complet
Section intitulée « Exemple complet »qmlVersion: "2.0"questionnaire: title: "Customer Feedback Survey" codeInit: | nps_score = 0 follow_up_needed = 0
blocks: - id: b_intro title: "Welcome" items: - id: q_welcome kind: Comment title: "Thank you for taking our survey. It will take about 3 minutes."
- id: b_experience title: "Your Experience" items: - id: q_nps kind: Question title: "How likely are you to recommend us? (0 = Not at all, 10 = Extremely likely)" codeBlock: | nps_score = q_nps.outcome if nps_score <= 6: follow_up_needed = 1 input: control: Slider min: 0 max: 10 labels: 0: "Not likely" 5: "Maybe" 10: "Very likely"
- id: q_reason kind: Question title: "What is the primary reason for your score?" precondition: - predicate: follow_up_needed == 1 input: control: Dropdown labels: 1: "Product quality" 2: "Customer service" 3: "Pricing" 4: "Other"
- id: q_aspects kind: QuestionGroup title: "Please rate these aspects:" questions: - "Product quality" - "Customer service" - "Value for money" input: control: Radio labels: 1: "Poor" 2: "Fair" 3: "Good" 4: "Excellent"
- id: b_closing title: "Thank You" items: - id: q_comments kind: Comment title: "Thank you for your valuable feedback!"