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.

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).
Inicio rápido
Sección titulada «Inicio rápido»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.
Conceptos básicos
Sección titulada «Conceptos básicos»Bloques: organizar la encuesta
Sección titulada «Bloques: organizar la encuesta»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
Rosterhace 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 preferencesPrecondiciones de bloque
Sección titulada «Precondiciones de bloque»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: 50En 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
Tipos de bloque avanzados
Sección titulada «Tipos de bloque avanzados»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 unGrouppara 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.
Ítems: tipos de pregunta
Sección titulada «Ítems: tipos de pregunta»QML admite cuatro tipos de ítem:
1. Comment (instrucciones)
Sección titulada «1. Comment (instrucciones)»Muestra texto sin recoger respuestas:
- id: q_intro kind: Comment title: "Please answer honestly. Your responses are confidential."2. Question (respuesta única)
Sección titulada «2. Question (respuesta única)»Hace una pregunta y recoge una respuesta:
- id: q_age kind: Question title: "What is your age?" input: control: Editbox min: 18 max: 1203. QuestionGroup (varias preguntas relacionadas)
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"4. MatrixQuestion (cuadrícula)
Sección titulada «4. MatrixQuestion (cuadrícula)»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"Controles de entrada
Sección titulada «Controles de entrada»Cada pregunta debe especificar cómo se recogen las respuestas.
Switch (Sí/No)
Sección titulada «Switch (Sí/No)»Elección binaria:
input: control: Switch on: "Yes" off: "No"Radio (elegir una)
Sección titulada «Radio (elegir una)»Seleccionar una opción entre varias:
input: control: Radio labels: 1: "Option A" 2: "Option B" 3: "Option C"Checkbox (elegir varias)
Sección titulada «Checkbox (elegir varias)»Seleccionar cero o más opciones:
input: control: Checkbox labels: 1: "Feature A" 2: "Feature B" 4: "Feature C" 8: "Feature D"Dropdown (elegir de una lista)
Sección titulada «Dropdown (elegir de una lista)»Selección compacta entre muchas opciones:
input: control: Dropdown labels: 1: "High School" 2: "Bachelor's" 3: "Master's" 4: "PhD" left: "Education:"Editbox (entrada numérica)
Sección titulada «Editbox (entrada numérica)»Introducción libre de un número:
input: control: Editbox min: 0 max: 1000000 left: "Annual income: $"Slider (escala visual)
Sección titulada «Slider (escala visual)»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"Range (selección de un intervalo)
Sección titulada «Range (selección de un intervalo)»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]Textarea (texto libre)
Sección titulada «Textarea (texto libre)»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: 500Tanto placeholder (texto de ayuda que se muestra mientras está vacío) como maxLength (límite de caracteres) son opcionales.
Lógica condicional
Sección titulada «Lógica condicional»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.
Validar las respuestas (poscondiciones)
Sección titulada «Validar las respuestas (poscondiciones)»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: 15Si un encuestado introduce datos no válidos (p. ej., 5 hijos en un hogar de 3 personas), se muestra el mensaje de ayuda.
Bloques de código y variables
Sección titulada «Bloques de código y variables»QML permite incrustar código Python para cálculos y lógica dinámica.
Inicializar variables
Sección titulada «Inicializar variables»Use codeInit para preparar las variables de seguimiento:
questionnaire: codeInit: | total_score = 0 risk_level = 0Calcular después de las respuestas
Sección titulada «Calcular después de las respuestas»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: 10Funciones de Python admitidas
Sección titulada «Funciones de Python admitidas»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)
Patrones habituales
Sección titulada «Patrones habituales»Revelación progresiva
Sección titulada «Revelación progresiva»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: 50Tanto q_job_title como q_years_employed heredan automáticamente la precondición del bloque: solo aparecen cuando el encuestado tiene empleo.
Puntuación y categorización
Sección titulada «Puntuación y categorización»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"Validación de la calidad de los datos
Sección titulada «Validación de la calidad de los datos»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: 60Buenas prácticas
Sección titulada «Buenas prácticas»Diseño de las preguntas
Sección titulada «Diseño de las preguntas»- 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/rightpara las unidades y las aclaraciones
Gestión de dependencias
Sección titulada «Gestión de dependencias»- 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
Estrategia de validación
Sección titulada «Estrategia de validación»- 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?
Pautas para los bloques de código
Sección titulada «Pautas para los bloques de código»- 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
Verificación formal
Sección titulada «Verificación formal»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ó.
Ejemplo completo
Sección titulada «Ejemplo completo»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!"