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.
Descripción general
Sección titulada «Descripción general»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)
Componentes principales
Sección titulada «Componentes principales»Estructura
Sección titulada «Estructura»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: ControlTypeqmlVersion
Sección titulada «qmlVersion»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.
Tipos de ítem
Sección titulada «Tipos de ítem»- Comment: muestra texto sin recoger respuestas
- Question: un único resultado entero
- QuestionGroup: vector de resultados enteros
- MatrixQuestion: matriz de resultados enteros
Controles de entrada
Sección titulada «Controles de entrada»- 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]
Lógica condicional
Sección titulada «Lógica condicional»Las precondiciones determinan la visibilidad:
precondition: - predicate: q_age.outcome >= 18Las 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: trueUn 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 != 3El 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 = 0blocks: - 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 wayCada 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.
Entradas externas (precarga)
Sección titulada «Entradas externas (precarga)»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.
Bloques de código
Sección titulada «Bloques de código»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 comomath.sqrt,statistics.meanorandom.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 es100 * part // total, una media en décimas es10 * total // ny un sorteo aleatorio esrandom.randint(1, 6). - Funciones, clases, importaciones
- Bucles while, break, continue
- Diccionarios, métodos de cadenas
Ejemplos completos
Sección titulada «Ejemplos completos»Esta sección muestra todos los tipos de ítem y de control con ejemplos que funcionan.
Tipo de ítem: Comment
Sección titulada «Tipo de ítem: Comment»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 == 1Tipo de ítem: Question
Sección titulada «Tipo de ítem: Question»Preguntas con un único resultado y distintos tipos de control.
Control: Switch
Sección titulada «Control: Switch»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: 0off / on rotulan los dos lados; left / right rotulan esos mismos lados
cuando no se indican off / on.
Control: Radio
Sección titulada «Control: Radio»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: 1Control: Dropdown
Sección titulada «Control: Dropdown»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"Control: Checkbox
Sección titulada «Control: Checkbox»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 = 16Seleccionar «Reading» y «Music» produce el resultado 1 | 4 = 5
Control: Editbox
Sección titulada «Control: Editbox»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"Control: Textarea
Sección titulada «Control: Textarea»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: 500Propiedades opcionales:
placeholder: texto de ayuda que se muestra cuando el área de texto está vacíaminLength: número mínimo de caracteres que espera (se registra, no se impone)maxLength: número máximo de caracteres permitidos
Control: Slider
Sección titulada «Control: Slider»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: 5Control: Range
Sección titulada «Control: Range»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: TextareaNo 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].
Tipo de ítem: QuestionGroup
Sección titulada «Tipo de ítem: QuestionGroup»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.
Tipo de ítem: MatrixQuestion
Sección titulada «Tipo de ítem: MatrixQuestion»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.
Ejemplo complejo con bloques de código
Sección titulada «Ejemplo complejo con bloques de código»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
Tipos de bloque
Sección titulada «Tipos de bloque»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: TextareaEl 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: 120El encuestado responde recuento = 3 → el codeBlock calcula family_mask = 2 ** 3 - 1 = 7 → el motor recorre los bits 1, 2 y 4.
Nombrar cada iteración (subjectFrom)
Sección titulada «Nombrar cada iteración (subjectFrom)»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: 120subjectFrom 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())Restricciones (v1)
Sección titulada «Restricciones (v1)»iterateOveres estrictamente una expresión entera: no se aceptan tipos lista/secuencia.- Las claves de
labelsdeben 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 - 1para «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) ymaxEntriesno 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.
Estructura de la exportación Bronce
Sección titulada «Estructura de la exportación Bronce»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_notesMá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.
Cuándo usar QuestionGroup o Roster
Sección titulada «Cuándo usar QuestionGroup o Roster»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.
Recuento máximo de un Group
Sección titulada «Recuento máximo de un Group»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 uncountno 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.