Aller au contenu
Base de connaissances

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.

Éditeur de questionnaire dans Armiger

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

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.

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 Roster pose 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 preferences

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

Dans 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

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 un Group pour 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.

QML prend en charge quatre types d’items :

Affiche du texte sans recueillir de réponse :

- id: q_intro
kind: Comment
title: "Please answer honestly. Your responses are confidential."

Pose une question et recueille une réponse :

- id: q_age
kind: Question
title: "What is your age?"
input:
control: Editbox
min: 18
max: 120

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"

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"

Chaque question doit préciser comment les réponses sont recueillies.

Choix binaire :

input:
control: Switch
on: "Yes"
off: "No"

Sélection d’une option parmi plusieurs :

input:
control: Radio
labels:
1: "Option A"
2: "Option B"
3: "Option C"

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"

Sélection compacte parmi de nombreuses options :

input:
control: Dropdown
labels:
1: "High School"
2: "Bachelor's"
3: "Master's"
4: "PhD"
left: "Education:"

Saisie libre d’un nombre :

input:
control: Editbox
min: 0
max: 1000000
left: "Annual income: $"

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"

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]

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

placeholder (texte indicatif affiché tant que le champ est vide) et maxLength (nombre maximal de caractères) sont tous deux facultatifs.

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]

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.

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

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

QML permet d’intégrer du code Python pour les calculs et la logique dynamique.

Utilisez codeInit pour mettre en place des variables de suivi :

questionnaire:
codeInit: |
total_score = 0
risk_level = 0

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

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)

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

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

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"

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: 60
  • 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/right pour les unités et les précisions
  • 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
  • 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 ?
  • 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

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

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