Ir al contenido
Base de conocimiento

Creación de encuestas con QML

Esta guía explica cómo crear encuestas con QML (Questionnaire Markup Language), un lenguaje basado en YAML diseñado para cuestionarios sofisticados con verificación formal, control dinámico del flujo y validación de los datos.

Editor de cuestionarios en Armiger

El editor de Armiger en el navegador: el explorador del proyecto y el chat de generación con IA (izquierda), el código QML (centro), el diagrama de flujo y una vista previa en tiempo real de la pregunta seleccionada (derecha).

Todo cuestionario QML empieza con esta estructura:

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"

El campo qmlVersion declara la versión principal de QML para la que está escrito su documento. La versión principal actual es la 2, así que escriba "2.0" (o "2.1" para usar las funciones opcionales más recientes). Los documentos escritos para la antigua gramática 1.x ya no se cargan y deben migrarse. Para la gramática completa, los tipos de ítem y los bloques avanzados, consulte la referencia de sintaxis de QML.

Un bloque cumple tres funciones:

  • Agrupación: reúne preguntas relacionadas en una sección.
  • Ramificación: su precondición controla todas las preguntas que contiene, de modo que una sola condición decide si un encuestado ve toda la serie.
  • Repetición: un bloque Roster hace sus preguntas una vez por cada entidad seleccionada (consulte Tipos de bloque avanzados).

El uso más sencillo es la agrupación:

blocks:
- id: b_demographics
title: "About You"
items:
# Questions about the respondent
- id: b_preferences
title: "Your Preferences"
items:
# Questions about preferences

Los bloques pueden tener sus propias precondiciones. Cuando un bloque tiene una precondición, esta se aplica automáticamente a todos los ítems del bloque: no hace falta repetir la misma condición en cada pregunta.

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

En este ejemplo, tanto q_job_title como q_years_employed heredan la precondición del bloque q_employed.outcome == 1. Los ítems también pueden definir sus propias precondiciones adicionales: la precondición del bloque se combina con las precondiciones de cada ítem.

Buenas prácticas:

  • Use identificadores descriptivos que empiecen por b_ (p. ej., b_demographics, b_experience)
  • Agrupe las preguntas relacionadas por tema
  • Mantenga las dependencias dentro de los bloques siempre que sea posible
  • Cuando dos o más preguntas comparten una misma condición de visibilidad, póngalas en su propio bloque y escriba la condición una sola vez, en el bloque; reserve las precondiciones de ítem para las condiciones específicas de esa pregunta
  • Una precondición de bloque lee respuestas y variables de preguntas anteriores al bloque, así que sitúe el bloque después de la pregunta que lo decide

De forma predeterminada, un bloque es un Group que presenta cada uno de sus ítems una vez. Dos variantes opcionales permiten encuestas más dinámicas:

  • Secciones repetidas (Roster): repiten un conjunto de preguntas una vez por cada elemento seleccionado (por ejemplo, hacer las mismas preguntas sobre cada comida que tomó un encuestado o sobre cada miembro de la familia).
  • Extracciones adaptativas (count): limitan un Group para que solo presente los N primeros ítems que cumplan los requisitos (por ejemplo, mostrar 3 preguntas de un conjunto más amplio).

Ambas se explican en detalle, con ejemplos, en la referencia de sintaxis de QML.

QML admite cuatro tipos de ítem:

Muestra texto sin recoger respuestas:

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

Hace una pregunta y recoge una respuesta:

- id: q_age
kind: Question
title: "What is your age?"
input:
control: Editbox
min: 18
max: 120
Sección titulada «3. QuestionGroup (varias preguntas relacionadas)»

Hace varias preguntas con el mismo formato de respuesta:

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

Recoge respuestas en formato de filas por columnas:

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

Cada pregunta debe especificar cómo se recogen las respuestas.

Elección binaria:

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

Seleccionar una opción entre varias:

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

Seleccionar cero o más opciones:

input:
control: Checkbox
labels:
1: "Feature A"
2: "Feature B"
4: "Feature C"
8: "Feature D"

Selección compacta entre muchas opciones:

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

Introducción libre de un número:

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

Selección visual a lo largo de una escala:

input:
control: Slider
min: 0
max: 10
step: 1
labels:
0: "Not at all"
5: "Somewhat"
10: "Extremely"

Seleccionar un intervalo con dos tiradores (desde-hasta). La respuesta es un par [low, high] con min <= low <= high <= max.

input:
control: Range
min: 0
max: 100
step: 5
labels:
0: "Minimum"
50: "Mid"
100: "Maximum"
default: [20, 80]

Para respuestas abiertas y cualitativas, use Textarea. A diferencia de todos los demás controles, su resultado es una cadena, no un entero, por lo que no está disponible para la lógica de ramificación ni para la verificación formal (hacer referencia al resultado de un Textarea en una precondición, una poscondición o un bloque de código es un error de diseño). Úselo para comentarios, sugerencias o explicaciones que tenga previsto leer o codificar más adelante.

input:
control: Textarea
placeholder: "Tell us more..."
maxLength: 500

Tanto placeholder (texto de ayuda que se muestra mientras está vacío) como maxLength (límite de caracteres) son opcionales.

Mostrar preguntas de forma condicional (precondiciones)

Sección titulada «Mostrar preguntas de forma condicional (precondiciones)»

Use precondiciones para mostrar preguntas en función de respuestas anteriores:

- 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 pregunta q_car_brand solo aparece si el encuestado respondió «Sí» a la pregunta de si tiene coche.

Precondiciones complejas:

precondition:
- predicate: q_age.outcome >= 25 and q_employment.outcome in [1, 2, 3]

Ver las ramas: la vista de árbol del diagrama

Sección titulada «Ver las ramas: la vista de árbol del diagrama»

El diagrama de flujo junto a su QML tiene dos vistas, que se alternan con Secuencia y Árbol en su esquina superior izquierda.

  • Secuencia (la predeterminada) muestra todas las preguntas en el orden en que las hace la entrevista, con sus condiciones al lado.
  • Árbol muestra las mismas preguntas como ramas. Las preguntas que comparten una condición, tanto si está escrita en su bloque como si se repite en cada pregunta, forman una rama, y una rama cuya condición solo puede cumplirse dentro de otra se dibuja dentro de ella. Los caminos «sí» y «no» de una pregunta de filtro aparecen uno junto al otro, y una pregunta de seguimiento que solo se hace en el camino «sí» queda anidada en él.

Las relaciones se demuestran con Z3; no se deducen del texto. El árbol se calcula cuando cambia a esa vista, así que el primer cambio tarda un momento; si no puede calcularse, el diagrama se queda en la secuencia y explica por qué. Cada rama lleva la etiqueta de lo que Z3 ha establecido:

Marca Significado
excluyentes Esta rama y su vecina nunca pueden aplicarse a la vez: el encuestado toma un camino o el otro
paralelas Ambas pueden aplicarse al mismo encuestado: series opcionales que pueden plantearse ambas
? excluyente, ? anidada, ? se cumple Z3 no ha podido decidir (por ejemplo, una condición que no puede expresar por completo, o una sobre una respuesta o un valor calculado en dos momentos distintos de la entrevista): la rama se muestra donde está demostrada, y la marca indica qué queda sin decidir
nunca / siempre La condición de la rama nunca puede cumplirse, o se cumple siempre

Dos preguntas con el mismo texto de condición forman una sola rama solo cuando la condición significa lo mismo para ambas: si un bloque de código situado entre ellas cambia una variable que lee la condición, cada una tiene su propia rama.

Las poscondiciones no ramifican, así que se mantienen junto a sus preguntas en ambas vistas.

Use poscondiciones para garantizar la coherencia lógica:

- 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 encuestado introduce datos no válidos (p. ej., 5 hijos en un hogar de 3 personas), se muestra el mensaje de ayuda.

QML permite incrustar código Python para cálculos y lógica dinámica.

Use codeInit para preparar las variables de seguimiento:

questionnaire:
codeInit: |
total_score = 0
risk_level = 0

Vincule bloques de código a los ítems para ejecutar cálculos:

- 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

El código QML se ejecuta en un entorno aislado, pero solo un subconjunto de Python puede traducirse al modelo formal (Z3) que verifica su cuestionario. Manténgase dentro de este subconjunto para que su lógica quede cubierta por la verificación:

✓ Subconjunto verificado:

  • Aritmética: +, -, *, //, %
  • Comparaciones: <, <=, >, >=, ==, != (incluidas las encadenadas, p. ej. 0 < x < 10)
  • Pertenencia: in, not in (p. ej. q_x.outcome in [1, 2, 3])
  • Lógica booleana: and, or, not
  • Condicionales: if, elif, else
  • Expresiones ternarias: x = 1 if condition else 0
  • Bucles for: for i in range(n) (n ≤ 20)
  • Literales de lista, tupla y conjunto (≤ 20 elementos)
  • Desempaquetado de tuplas: a, b = 1, 0
  • Asignación de variables: x = value, x += value
  • Funciones integradas: range(), abs(), int(), bool()
  • Acceso a los resultados: q_age.outcome

✗ Fuera del subconjunto verificado (consulte la nota más abajo):

  • Importaciones, funciones, clases
  • Bucles while, break, continue
  • Operaciones con diccionarios
  • Métodos de cadenas
  • Comprensiones de listas
  • Instrucciones print (se ignoran sin aviso)

Muestre las preguntas de forma progresiva en función de las respuestas previas. Use precondiciones de bloque para no repetir la misma condición en cada ítem:

- 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

Tanto q_job_title como q_years_employed heredan automáticamente la precondición del bloque: solo aparecen cuando el encuestado tiene empleo.

Calcule puntuaciones y clasifique a los encuestados:

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"

Garantice la calidad de las respuestas con validaciones entre ítems:

- 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
  • Sea específico: «¿Cuáles son los ingresos anuales de su hogar?» frente a «¿Ingresos?»
  • Use los controles adecuados: Editbox para números precisos, Slider para valoraciones subjetivas
  • Fije rangos realistas: min/max deben reflejar las restricciones del mundo real
  • Aporte contexto: use el texto left/right para las unidades y las aclaraciones
  • Mantenga juntos los ítems relacionados en el mismo bloque
  • El orden importa: las preguntas deben aparecer antes de que se haga referencia a ellas
  • Pruebe todos los caminos: asegúrese de que se puede llegar a cada pregunta
  • Fije restricciones de dominio mediante el min/max del control de entrada
  • Use poscondiciones para la coherencia lógica
  • Ofrezca mensajes de ayuda útiles: los mensajes de error claros orientan a los encuestados
  • Tenga en cuenta los casos límite: ¿qué ocurre si alguien introduce valores extremos?
  • Inicialice pronto: prepare las variables en codeInit
  • Manténgalo simple: los cálculos complejos pueden ser difíciles de depurar
  • Recuerde el ámbito: todas las variables son globales
  • Pruebe a fondo: ejecute el validador del cuestionario

La validación automática de los cuestionarios QML comprueba:

  • Alcanzabilidad: ¿se puede llegar a cada pregunta?
  • Coherencia: ¿pueden satisfacerse las reglas de validación?
  • Ciclos: ¿forman ciclos las dependencias?
  • Completitud: ¿existe al menos un camino válido para completar el cuestionario?

El validador utiliza análisis matemático (resolución SMT) para detectar errores de diseño antes de la puesta en marcha.

Consulte la sección de teoría para los detalles matemáticos.

Para aplicar el mismo cuestionario en varios idiomas, añada traducciones en lugar de copiarlo: una traducción solo sustituye el texto, de modo que la validación, la ramificación y los códigos de respuesta siguen siendo los del cuestionario que usted redactó.

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