Ir al contenido
Base de conocimiento

Sintaxis de QML

QML (Questionnaire Markup Language) es un lenguaje basado en YAML para crear cuestionarios verificados formalmente. Esta página ofrece un breve resumen técnico.

QML permite:

  • Verificación formal de la lógica del cuestionario mediante solucionadores SMT
  • Ramificación condicional con precondiciones y poscondiciones
  • Resultados enteros para todas las respuestas, lo que hace posible el análisis matemático
  • Código Python integrado para cálculos (un subconjunto restringido que admite la verificación)
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 declara la versión mínima del esquema QML que requiere su documento, en la forma Major.Minor.Patch:

  • Los cambios MAJOR rompen la compatibilidad: un documento escrito para una versión mayor anterior puede dejar de ser válido, o una construcción existente puede comportarse de otro modo.
  • Los cambios MINOR solo añaden capacidades opcionales: todo documento escrito para una versión menor anterior de la misma versión mayor sigue siendo válido.
  • Los cambios PATCH nunca alteran el contrato (redacción, aclaraciones, correcciones).

La versión actual del esquema es la 2.7.0. La versión 2.0.0 fue una versión mayor incompatible que redujo los tipos de bloque a Group (el tipo predeterminado, de una sola pasada, que puede limitarse con count) y Roster; los documentos escritos para una versión mayor anterior (que usaban los tipos eliminados Sequence/Sample) deben migrarse. La versión menor 2.1.0 añadió la clave opcional subjectFrom en los bloques Roster (consulte Roster), la 2.1.1 fue un parche que hizo más estricta la validación y la versión menor 2.2.0 añadió el indicador opcional external en un ítem (consulte Entradas externas): todas son ampliaciones compatibles con versiones anteriores, de modo que todo documento 2.0.0 sigue siendo válido. Declarar qmlVersion: "2.0" basta para cargarlo; use "2.2" si depende de external. La versión menor 2.5.0 convirtió la respuesta de un Range y su default en un par [low, high] (consulte Control: Range); use "2.5" si asigna un default a un Range. La versión menor 2.6.0 rechaza una clave de input que el control no declara, de modo que un lables mal escrito es un error en lugar de ignorarse en silencio, y declara minLength para Textarea y left / right para Switch. El parche 2.6.1 rechaza un id de ítem que no sea un nombre simple (letras, dígitos y guiones bajos, sin empezar por un dígito, y que no sea ni una palabra clave de Python ni un nombre integrado como len, sum o math), ya que una condición lee un ítem como <id>.outcome. El parche 2.6.2 mantiene la aritmética de QML en números enteros: el código del autor que pueda producir una fracción (/, un literal decimal, float) se rechaza al cargar el cuestionario; use // en su lugar. El parche 2.6.3 hace que el default de un Range sea un par de números enteros, como lo es toda respuesta de un Range. El parche 2.6.4 rechaza un default fuera del dominio de respuestas del ítem: un cuestionario cuyo valor predeterminado no podría coincidir con ninguna respuesta no se carga. La versión menor 2.7.0 añade el indicador opcional invented en una poscondición (consulte Lógica condicional); use "2.7" si lo escribe. La versión del esquema es independiente de la versión interna de la plataforma.

  • Comment: muestra texto sin recoger respuestas
  • Question: un único resultado entero
  • QuestionGroup: vector de resultados enteros
  • MatrixQuestion: matriz de resultados enteros
  • Switch: binario (0/1)
  • Radio: selección única entre opciones etiquetadas
  • Checkbox: selección múltiple (codificada como máscara de bits)
  • Dropdown: selección única con prefijo/sufijo
  • Editbox: número entero libre dentro de [min, max]
  • Textarea: texto libre; el resultado es una cadena y queda excluido de la verificación formal
  • Slider: selección visual de un entero
  • Range: selección de un intervalo; el resultado es un par [low, high]

Las precondiciones determinan la visibilidad:

precondition:
- predicate: q_age.outcome >= 18

Las poscondiciones imponen restricciones:

postcondition:
- predicate: q_children.outcome < q_household.outcome
hint: "Children must be fewer than household size"

Una poscondición puede llevar invented: true. Al importar un cuestionario, se marca así toda comprobación que la fuente no formulaba como regla estricta, como una validación flexible o una comprobación tomada de una instrucción para el entrevistador («indague si las horas superan 80»), para que usted pueda confirmarla o cambiarla antes de publicar. El indicador no cambia nada en la encuesta ni en el validador, y los encuestados nunca lo ven; el editor marca cada una de esas comprobaciones. Elimínelo cuando haya confirmado la comprobación. Las precondiciones no lo admiten.

postcondition:
- predicate: q_hours.outcome <= 80
hint: "More than 80 hours a week: please check the number"
invented: true

Un bloque tiene tres funciones. Agrupa ítems relacionados en una sección; ramifica, porque una precondition de bloque condiciona todos los ítems del bloque; y, como Roster, repite sus ítems una vez por cada entidad seleccionada. Las condiciones del bloque y del ítem se combinan durante la encuesta (primero las del bloque y después las del ítem, y todas deben cumplirse), y el validador las combina del mismo modo.

Condicione una rama en el bloque. Una serie de dos o más ítems que comparten una condición debe ir en su propio bloque con esa condición; un ítem conserva su propia precondición solo para lo que le es específico. Escriba la condición una vez, no en cada ítem:

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

Una condición de bloque lee respuestas y variables de ítems anteriores al bloque. Se comprueba de nuevo antes de cada ítem, de modo que una condición que lee una variable asignada por un bloque de código dentro del mismo bloque cambia a mitad del bloque y, en cuanto dos ítems la asignan, el validador informa de un ciclo de dependencias. Los bloques siguen el orden del archivo, así que coloque un bloque condicionado después del ítem que lo decide. Los bloques no se anidan; una rama dentro de otra rama es una condición de bloque más una precondición de ítem, o un bloque adicional. La precondición de un ítem nunca se traslada al ítem siguiente, por lo que un ítem condicional fuera de un bloque condicionado debe expresar su propia condición completa.

Una pregunta que el encuestado dejó sin responder. Cuando a un encuestado se le muestra una pregunta y la deja en blanco, una condición que lee su respuesta se decide con las respuestas que sí existen, de modo que q_a.outcome == 1 or q_b.outcome == 1 se sigue cumpliendo cuando solo q_a se respondió con 1. Si la respuesta que falta aún pudiera cambiar el resultado, una precondición oculta su pregunta y una poscondición deja pasar la respuesta. En ambos casos la encuesta registra una advertencia, y la respuesta permanece en su conjunto de datos. Para dirigir a un lugar concreto a quienes no respondieron, compruébelo explícitamente:

precondition:
- predicate: q_marital.outcome is None or q_marital.outcome != 3

El validador entiende esta comprobación: una condición que comprueba si se respondió a una pregunta simple se verifica como cualquier otra comparación, siempre que la comprobación vaya antes de los demás usos de esa respuesta en la condición, como ocurre aquí.

El validador también tiene en cuenta las respuestas en blanco al clasificar una pregunta. Una precondición que lee una respuesta que el encuestado puede dejar en blanco se clasifica como alcanzada condicionalmente, y no como alcanzada siempre, ya que una respuesta en blanco oculta la pregunta. Para que una respuesta sea obligatoria, asigne a esa pregunta su propia poscondición q_marital.outcome is not None; así el validador sabe que nunca queda en blanco.

Una pregunta que nunca se mostró porque su propia precondición la ocultó es distinta: su respuesta simplemente está vacía, y una condición como q_pregnant.outcome != 1 la trata así.

Contar a lo largo de un bloque. La precondición de un bloque se comprueba de nuevo antes de cada una de sus preguntas, de modo que un contador que actualizan las preguntas puede terminar el bloque antes de tiempo:

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

Cada pregunta ve el contador tal como lo dejaron las preguntas anteriores en el archivo; su propio bloque de código se ejecuta después de sus propias condiciones. El validador lo interpreta del mismo modo: una condición que el contador nunca puede cumplir (negative_count < 0) se notifica como inalcanzable, y lo mismo vale para un contador leído por la precondición de la propia pregunta. Una pregunta dejada en blanco hace que el contador sea desconocido (su bloque de código leyó una respuesta ausente), por lo que se omite el resto del bloque: tal como está escrito, solo la primera pregunta se formula siempre. Asigne a cada pregunta la poscondición q_concept_1.outcome is not None (y así sucesivamente) para exigir una respuesta; el validador clasifica entonces las tres primeras preguntas como siempre formuladas y las posteriores como condicionales.

Los instrumentos reales suelen ramificarse según un valor que ninguna pregunta recoge: un indicador de rotación, un grupo de cuestionario dividido (split ballot), el sexo o el estado civil procedentes de un archivo de muestra, una respuesta de una oleada anterior. Marque ese ítem con external: true (esquema 2.2.0 o posterior) para declararlo apto para precarga:

- id: q_rotate_out
kind: Question
title: "Is this respondent rotating out this wave?"
external: true
input:
control: Radio
labels:
0: "No"
1: "Yes"

Por lo demás, un ítem externo es una pregunta completamente normal: tiene un dominio input: real y puede tener precondiciones, poscondiciones y un bloque de código, y Z3 lo verifica exactamente igual que el mismo ítem sin el indicador (el indicador no añade ninguna lógica nueva que demostrar). Al iniciarse la encuesta, la plataforma intenta responderlo de antemano a partir del registro del encuestado (datos demográficos y atributos importados), vinculado en cada campaña mediante una correspondencia que configura un operador. Cuando se obtiene un valor válido para el dominio del ítem, el ítem se responde automáticamente y se oculta; cuando no hay valor (o está fuera del dominio), el ítem simplemente se formula en el flujo normal: la precarga es una optimización, nunca un obstáculo.

La correspondencia de origen de cada ítem es una propiedad administrativa que se configura por campaña (en Targetor), no en el archivo QML, de modo que el mismo cuestionario puede ejecutarse con una precarga distinta en distintas campañas. Un valor respondido automáticamente se marca en los datos como aportado externamente, para que el análisis pueda distinguirlo de una respuesta del propio encuestado.

external: true es la forma aprobada de condicionar según un valor externo: sustituye a las soluciones provisionales anteriores (un nombre sin definir, una constante congelada en codeInit o una pregunta preliminar con título ADMIN:), que el validador ahora señala.

Subconjunto restringido de Python para la verificación formal:

Admitido:

  • Aritmética con números enteros: +, -, *, // (división entera), %, ** con exponente no negativo
  • Comparaciones: <, <=, >, >=, ==, !=
  • Lógica booleana: and, or, not
  • Control de flujo: if/elif/else, for (limitado)
  • Operador ternario: x = 1 if condition else 0
  • Desempaquetado de tuplas: a, b = 1, 0
  • Funciones integradas: range(), abs(), int(), bool()
  • Acceso al resultado: item.outcome

No admitido:

  • Todo lo que produzca una fracción: /, un número decimal (0.5), float(), un exponente negativo (2 ** -1) o una función fraccionaria como math.sqrt, statistics.mean o random.random. Toda respuesta es un número entero y toda condición se verifica sobre números enteros, por lo que un cuestionario que use alguno de estos elementos no se carga; el mensaje indica dónde. Escale los valores en su lugar: un porcentaje es 100 * part // total, una media en décimas es 10 * total // n y un sorteo aleatorio es random.randint(1, 6).
  • Funciones, clases, importaciones
  • Bucles while, break, continue
  • Diccionarios, métodos de cadenas

Esta sección muestra todos los tipos de ítem y de control con ejemplos que funcionan.

Muestra un texto informativo sin recoger respuestas:

- id: intro_comment
kind: Comment
title: "Welcome to our demographic survey. Your responses help us understand our community better."

Los comentarios pueden mostrarse de forma condicional:

- id: parent_notice
kind: Comment
title: "The following questions are about your children."
precondition:
- predicate: q_has_children.outcome == 1

Preguntas con un único resultado y distintos tipos de control.

Elección binaria (0 = desactivado, 1 = activado):

- id: q_has_children
kind: Question
title: "Do you have children?"
input:
control: Switch
off: "No"
on: "Yes"
default: 0

off / on rotulan los dos lados; left / right rotulan esos mismos lados cuando no se indican off / on.

Selección única entre opciones etiquetadas:

- 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

Selección única con texto opcional de prefijo/sufijo:

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

Selección múltiple (codificada como máscara 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

Seleccionar «Reading» y «Music» produce el resultado 1 | 4 = 5

Entrada libre de un número entero con límites. Una respuesta fuera de min..max, o con parte decimal, se rechaza y se pide al encuestado que introduzca un número entero dentro del rango. Un Editbox no admite step; para recoger un decimal, escálelo (pida céntimos en lugar de 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"

Entrada de texto libre para respuestas abiertas. El resultado es una cadena (no un entero), por lo que el análisis de Z3 lo ignora: 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 que el validador señala. Úselo para comentarios cualitativos, sugerencias u observaciones que requieran respuestas de texto.

- id: q_feedback
kind: Question
title: "Describe your experience with our service."
input:
control: Textarea
placeholder: "Type your answer here..."
maxLength: 500

Propiedades opcionales:

  • placeholder: texto de ayuda que se muestra cuando el área de texto está vacía
  • minLength: número mínimo de caracteres que espera (se registra, no se impone)
  • maxLength: número máximo de caracteres permitidos

Selección visual de un entero:

- 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

Selección de un intervalo con dos tiradores. El resultado es una lista de dos elementos [low, high] con 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]

Seleccionar de 100 a 500 guarda [100, 500]. Un default, si se indica, también es un par de números enteros: las posiciones de reposo de los dos tiradores.

Lea los extremos por su nombre: q_price_range.outcome.low es el extremo inferior y q_price_range.outcome.high el superior. No se acepta un índice como outcome[0] ni comparar la respuesta con una lista (outcome == [100, 500]).

- 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

No hace falta ninguna comprobación is not None: un Range sin responder deja la condición sin decidir en tiempo de ejecución, por lo que una precondición que lo lee omite su ítem. En un QuestionGroup con un control Range, el resultado es una lista de rangos; en un MatrixQuestion, son filas × columnas de rangos, y cada uno se lee como m.outcome[j][k].low / m.outcome[j][k].high. Un bloque de código asigna la respuesta de un Range con un par, q.outcome = [low, high].

Vector de resultados con el mismo control para cada subpregunta:

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

Acceda a los resultados mediante índices: qg_family_ages.outcome[0], qg_family_ages.outcome[1], etc.

El validador estático demuestra las condiciones que leen una sola respuesta, qg.outcome[i]. Hasta que el grupo se responde, su resultado es None (porque una condición lo excluyó, o porque se mostró y se dejó en blanco), de modo que cualquier lectura de qg.outcome[i] hace que una precondición falle y que una poscondición no se exija; compruebe primero qg.outcome is not None para condicionar según el propio grupo. Un grupo respondido deja como None las respuestas que faltan: qg.outcome[0] != 1 se cumple para una respuesta vacía y qg.outcome[0] > 1 no. Comparar la lista completa (qg.outcome == 1), un conjunto de respuestas, un grupo dentro de un Roster o de un Group con recuento máximo y un bloque de código que escribe en un grupo se aplican en tiempo de ejecución pero no se verifican, y se notifican como advertencias skipped_condition.

Matriz de resultados (filas × columnas):

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

Acceda a los resultados mediante índices de fila/columna: mq_language_proficiency.outcome[0][1] corresponde al primer idioma (English) y al segundo miembro de la familia (Spouse).

La matriz crea una cuadrícula en la que cada celda representa el nivel de un miembro de la familia en un idioma. Este ejemplo produce una matriz de 5×4 (5 idiomas × 4 miembros de la familia) = 20 resultados individuales.

Muestra precondiciones, poscondiciones y bloques de código:

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"

Este ejemplo muestra:

  • Visibilidad condicional: las preguntas sobre ingresos están en un bloque condicionado a la situación laboral, con la condición escrita una sola vez
  • Bloques de código: acumulan los ingresos a lo largo de las preguntas
  • Validación mediante poscondiciones: garantiza que los ingresos del hogar sean coherentes con los ingresos individuales
  • Dependencias encadenadas: cada pregunta depende de respuestas anteriores

kind es opcional y su valor predeterminado es Group. Valores reconocidos:

Tipo Semántica
Group (predeterminado) Formula una vez cada ítem interno aplicable, en orden canónico (topológico). Un count: N opcional limita el bloque a los N primeros ítems elegibles (véase más abajo).
Roster Repite los ítems internos por cada bit activo de una máscara de bits iterateOver (véase más abajo).

Los bloques de cualquier tipo también pueden llevar listas opcionales precondition y postcondition que se aplican a todos los ítems internos (las reglas del bloque se evalúan antes que las del ítem). Un Roster con una precondición falsa se omite por completo; con una verdadera, itera sobre iterateOver como de costumbre. La validación estática (Z3) tiene en cuenta el tipo de bloque: un Roster se despliega por cada clave de etiqueta en copias protegidas por su bit; un Group con count trata los ítems internos como presentes de forma condicional, con una selección de hasta N.

Un bloque Roster (kind: Roster) repite sus ítems internos una vez por cada clave de etiqueta activa. El autor declara:

  • iterateOver: una expresión de Python que debe evaluarse como un entero no negativo, tratado como una máscara de bits.
  • labels: una correspondencia entre claves enteras que son potencias de 2 (1, 2, 4, 8, 16, …) y los textos que se muestran, que declara el universo de iteraciones posibles.

El motor recorre los bits activos de iterateOver de menor a mayor. Por cada bit activo cuya clave aparece en labels, los ítems internos se ejecutan una vez con ese valor de bit como identidad intrínseca de la iteración.

Cada respuesta a un ítem de un Roster pertenece a una iteración. Una respuesta enviada a través de la API (submit_survey_response) a un ítem de un Roster que nunca se formuló, mientras no hay ninguna iteración del Roster en curso (antes de que la encuesta llegue al Roster o después de haberlo dejado), se rechaza, igual que un salto a ese ítem en la lista de pasos. Una respuesta que el Roster ya contiene puede seguir modificándose: se reabre en la iteración en la que se dio.

En la v1 se ofrecen dos formas de redacción:

1. Basada en selección múltiple (el Checkbox alimenta directamente el roster)

Sección titulada «1. Basada en selección múltiple (el Checkbox alimenta directamente el roster)»

El resultado de un Checkbox ES el entero de la máscara de bits (la suma de las claves potencia de 2 seleccionadas). Pasa directamente a iterateOver sin código intermedio:

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

El encuestado marca Breakfast + Dinner → q_meals_eaten.outcome = 5 (bit 1 + bit 4) → el motor recorre dos iteraciones: el bit 1 (Breakfast) y después el bit 4 (Dinner).

2. Numérica, «¿Cuántos?» (la máscara se construye con aritmética simple)

Sección titulada «2. Numérica, «¿Cuántos?» (la máscara se construye con aritmética simple)»

Para un recuento numérico, un codeBlock anterior construye una máscara de «los N primeros bits» con aritmética simple (2 ** n - 1). No se necesita el operador de desplazamiento de bits (<<):

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

El encuestado responde recuento = 3 → el codeBlock calcula family_mask = 2 ** 3 - 1 = 7 → el motor recorre los bits 1, 2 y 4.

De forma predeterminada, cada iteración toma su título de su entrada estática de labels («Member 1», «Member 2», …). Cuando el encuestado aporta un nombre más significativo dentro de la iteración (el nombre de un familiar, un producto que posee), haga que el subjectFrom opcional del bloque apunte al id de ese ítem interno, y su respuesta en cada iteración pasará a ser el sujeto que se muestra para la iteración. Hasta que ese ítem se responde, se muestra la entrada estática 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 solo cambia la etiqueta mostrada: la clave de bit canónica, potencia de 2, sigue siendo la identidad de la iteración para el almacenamiento, la exportación y las referencias entre iteraciones. Requiere qmlVersion: "2.1" (o superior).

Leer los resultados de un roster desde fuera del roster

Sección titulada «Leer los resultados de un roster desde fuera del roster»

Dentro de una iteración del roster, q_satisfaction.outcome devuelve el valor de la iteración actual (instantánea/restauración). Fuera del roster (bloques de código posteriores al roster, precondiciones de ítems posteriores), use el diccionario 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"

O agregue los valores de todas las iteraciones:

total_satisfaction = sum(q_satisfaction.outcomes.values())
  • iterateOver es estrictamente una expresión entera: no se aceptan tipos lista/secuencia.
  • Las claves de labels deben ser potencias de 2 positivas (1, 2, 4, 8, 16, …); el cargador rechaza cualquier otro valor con un error claro.
  • Los controles Checkbox también exigen claves de etiqueta que sean potencias de 2, lo que alinea la semántica del Checkbox con la del Roster para que el resultado de un Checkbox pase directamente a iterateOver.
  • Sin interpolación de cadenas en los títulos. Los títulos de los ítems se muestran literalmente; los elementos de visualización de cada iteración (p. ej., «2 of 4 · Lunch») los genera la interfaz de la encuesta a partir de la correspondencia labels[<bit>].
  • Sin operadores de desplazamiento de bits << / >> en los bloques de código del autor: use aritmética simple (2 ** n - 1 para «los N primeros bits»). El operador ** está permitido.
  • Sin listas por comprensión en los bloques de código del autor (por el coste de traducción a Z3).
  • as (vinculación de la variable de iteración) y maxEntries no se admiten en la v1: el diseño basado en máscaras de bits hace innecesarios ambos.
  • Los rosters anidados (un Roster dentro de otro Roster) no se admiten en la v1.
  • La autorreferencia en iterateOver (hacer referencia a un ítem que está dentro del mismo Roster) se rechaza al cargar.

Cada Roster produce un número fijo de columnas: len(labels) × len(inner items). Nombre de las columnas: {block_id}_{bit_key}_{item_id}. Las celdas de las claves de etiqueta no activas en una encuesta son NULL. El esquema queda totalmente determinado solo con la declaración QML.

Ejemplo (per_meal con 4 etiquetas × 2 ítems internos = 8 columnas):

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

Más la columna externa q_meals_eaten.

La exportación Oro en formato largo está disponible como transformación opcional que reorganiza el conjunto de datos Bronce en formato ancho en un conjunto de datos principal (sin columnas de roster) más un conjunto de datos secundario por cada Roster con las columnas survey_id, iteration_key, <inner_item>..., lo natural para los flujos de trabajo de análisis que agrupan por iteración.

Use QuestionGroup para varias preguntas en la misma página (un mismo atributo repetido, un número fijo, sin títulos por iteración).

Use Roster para preguntas por cada elemento, con una página por elemento: el número se determina en tiempo de ejecución (numérico o por selección múltiple), un ítem interno por página y un recorrido en profundidad que avanza iteración por iteración.

Un bloque Group acepta un count: N opcional que lo limita a los N primeros ítems internos elegibles, seleccionados de forma determinista en orden canónico. Sin count, un Group formula todos sus ítems aplicables.

  • count: el N, un literal entero positivo opcional. Si se omite, se formulan todos los ítems. Si está presente, el cargador rechaza explícitamente un count no positivo; no hay ningún valor predeterminado silencioso.
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"

Con count: 3, el motor formula los 3 primeros de los 5 ítems en orden canónico (topológico): una selección determinista de los N primeros, no una selección aleatoria. Los ítems cuyas precondiciones se evalúan como false se saltan sin coste (NO consumen plaza), por lo que pueden mostrarse menos de N ítems cuando las precondiciones agotan el conjunto.

Un ítem que el límite deja fuera está ausente, no respondido. Una vez que el Group ha formulado sus N ítems, se rechaza un salto a un ítem excluido en la lista de pasos de la encuesta, igual que una respuesta enviada a ese ítem a través de la API (submit_survey_response). Un ítem que el Group sí formuló puede seguir modificándose. Un ítem respondido a través de la API, o al que se salta, mientras el Group aún tiene una plaza libre ocupa esa plaza, de modo que el Group nunca formula más de N ítems en total. Conserva la plaza cuando el encuestado retrocede hasta antes del Group y vuelve a avanzar sin cambiar nada: el ítem se muestra de nuevo con su respuesta, en lugar de ser sustituido por un ítem anterior.

Se requieren ítems internos independientes: los ítems internos de un Group con count deben ser independientes: ningún ítem interno puede depender de otro ítem interno del mismo Group (directamente o a través de una variable compartida). El límite puede excluir cualquier ítem, de modo que una dependencia dentro del Group podría leer la respuesta de un ítem hermano no seleccionado. La plataforma rechaza un Group así en la validación. (Un Group sin count y las dependencias entre bloques no tienen restricciones.)

Resultados: los ítems internos de un Group con recuento máximo usan la ruta normal de outcome de valor único. Un ítem interno no seleccionado (omitido por su precondición o más allá del límite N) tiene outcome: null y no aparece en la exportación Bronce.