--- { "title": "Cómo versionar un Questionnaire FHIR", "description": "Aprenda a versionar los Questionnaires FHIR correctamente: cuándo incrementar MAJOR, MINOR o PATCH, qué cambios rompen la compatibilidad de forma silenciosa y las reglas prácticas para evolucionar sus formularios con seguridad.", "date": "2026-02-24", "author": "Vitalii Banchenko", "reading-time": "7 minutes", "tags": [ "Forms", "Aidbox" ] } --- > For the complete documentation index, see [llms.txt](https://www.health-samurai.io/llms.txt). > Use it to discover all available pages before guessing URLs. --- En este artículo exploramos cómo funciona el versionado de los Questionnaires FHIR y por qué es esencial para mantener la integridad de los datos. Revisamos el versionado canónico en FHIR, analizamos los enfoques de versionado más habituales, explicamos cómo gestionar distintos tipos de cambios mediante versionado semántico y destacamos recomendaciones prácticas y errores frecuentes. El objetivo es ofrecer una guía clara para gestionar la evolución de los Questionnaires sin romper la compatibilidad. ## Introducción En FHIR, un Questionnaire es un recurso canónico que describe formularios estructurados para recopilar datos sanitarios. Define una lista de preguntas, su agrupación y orden, las opciones de respuesta, así como comportamientos dinámicos más complejos basados en las respuestas ya proporcionadas. Con el tiempo, los formularios cambian: se añaden nuevas preguntas, se clarifica la redacción, se reorganiza la estructura y se eliminan elementos obsoletos. Estos cambios son inevitables, pero plantean un reto crítico: cómo garantizar que los datos de QuestionnaireResponse recopilados previamente sigan siendo correctos e interpretables. Dado que Questionnaire es un recurso canónico, sigue las reglas del versionado canónico. El versionado permite identificar de forma unívoca el formulario utilizado para la recopilación de datos, garantizar la interpretación correcta de las respuestas, mantener el historial de auditoría e introducir mejoras de forma segura sin comprometer la compatibilidad. Sin un versionado adecuado, incluso pequeños cambios estructurales pueden hacer que los datos históricos sean poco fiables. ## Versionado canónico en FHIR Los recursos canónicos de FHIR (como Questionnaire, StructureDefinition, ValueSet, CodeSystem) son reutilizables, estables y versionados. Se identifican mediante una `url` globalmente única y una `version`. Un ejemplo mínimo: ```javascript { "resourceType": "Questionnaire", "url": "http://aidbox.app/fhir/Questionnaire/vitals-form", "version": "1.0.0", "status": "active" } ``` La `url` es un identificador lógico permanente y no debe modificarse entre versiones. La `version` identifica una edición concreta del formulario y cambia cada vez que el formulario se modifica de manera significativa. El `status` (`draft`, `active`, `retired`, `unknown`) refleja el estado del ciclo de vida, no el versionado en sí. Cuando se cumplimenta un Questionnaire, el QuestionnaireResponse debe hacer referencia a la versión exacta utilizada: ```javascript "questionnaire": "http://aidbox.app/fhir/Questionnaire/vitals-form|1.0.0" ``` Esta referencia garantiza la correcta interpretación de los datos incluso si posteriormente se introducen versiones más recientes. Cada nueva versión es efectivamente un recurso nuevo. Las versiones publicadas anteriormente deben permanecer inmutables. Pueden coexistir múltiples versiones en el sistema — esto es fundamental para la compatibilidad retroactiva y el cumplimiento normativo. ## Enfoques de versionado FHIR no define estrictamente cómo deben estructurarse los números de versión. A partir de [FHIR R5](/articles/fhir-r4-vs-fhir-r5-choosing-the-right-version-for-your-implementation), el elemento opcional `versionAlgorithm` puede especificar el enfoque elegido (semántico, numérico, basado en fecha, etc.), aunque no es obligatorio. El enfoque más ampliamente utilizado y recomendado es el Versionado Semántico (SemVer) en el formato MAJOR.MINOR.PATCH (por ejemplo, 2.1.0). En este modelo: - MAJOR indica cambios incompatibles que afectan a la compatibilidad (eliminación de preguntas, cambio de `linkId`, reestructuración del formulario). - MINOR indica adiciones compatibles con versiones anteriores (añadir preguntas, ampliar opciones de respuesta). - PATCH indica correcciones no disruptivas (erratas, clarificación de la redacción sin cambio de significado). El versionado semántico hace explícita la compatibilidad y ayuda a los implementadores a decidir si la actualización es segura. Otros enfoques incluyen el versionado basado en fecha (por ejemplo, 2025-08 o 2025.08.15), que muestra claramente la fecha de publicación pero no indica compatibilidad, y los esquemas incrementales simples o alfanuméricos (1, 2, 3 o rev1, rev2), que son flexibles pero carecen de claridad semántica. Con independencia del método elegido, es esencial utilizar un enfoque coherente por formulario (misma `url`) y garantizar que cada par (`url`, `version`) sea único. ## Escenarios de cambio habituales y versionado SemVer Al modificar un Questionnaire, la pregunta clave es si el cambio afecta a la estructura o a la interpretación de los datos recopilados. La respuesta determina el incremento de versión necesario. Analicemos los siguientes tipos de cambios: - Añadir una pregunta - Eliminar una pregunta - Cambiar un `linkId` - Cambiar un código - Cambiar el texto - Cambiar el orden de las preguntas - Cambiar la estructura de grupos - Cambiar la lógica de cumplimentación ### Añadir preguntas Añadir una nueva pregunta sin alterar las existentes es un cambio compatible con versiones anteriores y debe incrementar la versión minor (1.1.0 → 1.2.0). ### Eliminar preguntas Eliminar una pregunta es un cambio disruptivo y requiere un incremento de la versión major (1.1.0 → 2.0.0). ### Cambiar el `linkId` Cambiar el `linkId` rompe el vínculo entre los elementos del Questionnaire y las respuestas del QuestionnaireResponse, por lo que siempre debe tratarse como un cambio major (1.1.0 → 2.0.0). ### Cambiar códigos (`code`) Actualizar o reemplazar los códigos utilizados para la identificación semántica de las preguntas (por ejemplo, LOINC, SNOMED CT) puede modificar el significado clínico de una pregunta y afectar a la interoperabilidad. Sin embargo, el impacto depende de la naturaleza del cambio: - Si un código se reemplaza completamente por otro, es un cambio disruptivo que requiere una actualización de versión major (1.1.0 → 2.0.0). - Si se añade un código adicional sin eliminar el anterior, es una actualización de versión minor (1.1.0 → 1.1.1). ### Cambiar el texto de las preguntas Ajustar la redacción, traducir a otro idioma o corregir errores gramaticales puede corresponder a distintos tipos de cambio, según si el significado varía: - Si el significado no cambia, es una actualización patch (1.1.0 → 1.1.1). - Si el significado cambia, es una actualización major (1.1.0 → 2.0.0). ### Cambiar el orden de las preguntas Reordenar elementos dentro del mismo nivel de anidamiento normalmente no afecta a la interpretación, pero puede modificar la experiencia de usuario y el flujo de cumplimentación. Se trata de un cambio de versión minor (1.1.0 → 1.1.1). ### Cambiar la estructura de grupos Mover preguntas entre grupos o cambiar el anidamiento puede afectar al mapeo de respuestas y también puede romper reglas `enableWhen` (por ejemplo, una pregunta que estaba dentro de un grupo oculto por defecto), dando lugar a resultados impredecibles. Estos cambios deben tratarse como una actualización de versión major (1.1.0 → 2.0.0). ### Cambiar la lógica de cumplimentación Las modificaciones en `enableWhen`, `required`, `maxLength` y otras reglas pueden afectar a qué respuestas se recopilan. - Si son ajustes menores, es una actualización de versión minor. - Si modifican significativamente las condiciones, es una actualización de versión major. ## Recomendaciones prácticas y buenas prácticas Un versionado adecuado de un Questionnaire minimiza el riesgo de romper la compatibilidad y simplifica el mantenimiento de los formularios. A continuación se presentan recomendaciones basadas en la experiencia de implementación de FHIR en sistemas clínicos. ### No modificar versiones publicadas Una vez que un Questionnaire se publica con estado `active`, su contenido no debe modificarse. Cualquier cambio — incluso la corrección de una errata — requiere la publicación de una nueva versión. Las versiones históricas deben permanecer inmutables para preservar la integridad de las respuestas. ### Garantizar la unicidad del par (`url`, `version`) Cada versión de un formulario debe tener una combinación única de `url` y `version`. Esta regla permite identificar de forma inequívoca una edición concreta del formulario en cualquier sistema. Se recomienda implementar comprobaciones automáticas de unicidad en el momento de la publicación. ### Documentar los cambios Se recomienda encarecidamente mantener un registro de cambios que documente cada modificación, el motivo del cambio y si representa una actualización major, minor o patch. Una documentación clara simplifica la auditoría y la evaluación de la compatibilidad. ### Utilizar el control del ciclo de vida Estados del Questionnaire Los estados `draft` → `active` → `retired` deben reflejar el estado real del formulario. - No utilice `active` para formularios de prueba o incompletos. - Al pasar un formulario a `retired`, asegúrese de que ya no se utiliza en flujos de trabajo en curso. Proceso de publicación típico: Borrador (`draft`) → Verificación → Publicación (`active`). ### Vincular las respuestas a una versión específica En `QuestionnaireResponse.questionnaire`, incluya siempre una referencia con el formato: `{url}|{version}`. ```javascript "questionnaire": "http://aidbox.app/fhir/Questionnaire/vitals-form|1.1.0" ``` Esto garantiza la correcta interpretación de los datos aunque el formulario cambie en el futuro. ### Integrar comprobaciones en el proceso de publicación Comprobaciones de versión Antes de activar una nueva versión, es útil automatizar las siguientes comprobaciones: - Asegurarse de que no existen duplicados de `url` + `version`. - Verificar que no hay referencias al formulario en flujos de trabajo sin finalizar si la versión cambia. - Analizar las diferencias entre versiones para determinar el nivel de los cambios. ### Planificar la compatibilidad con antelación Impacto de los cambios - Si se prevé que el formulario evolucione, utilice `linkId` y códigos (`code`) estables desde la primera versión. - Evite cambios incompatibles con versiones anteriores salvo que sea necesario. - Considere el uso de recursos `Library` o componentes independientes para reducir el impacto de las actualizaciones. ## Errores frecuentes en el versionado de Questionnaires Un error habitual es cambiar la `url` en lugar de incrementar la versión. La `url` debe permanecer estable para preservar la continuidad. Solo la `version` debe cambiar. Otro problema frecuente es ignorar la compatibilidad retroactiva. Eliminar preguntas o modificar identificadores sin incrementar la versión major puede dar lugar a una interpretación incorrecta de las respuestas existentes. Cambiar el `linkId` o los códigos clínicos sin la debida reflexión puede romper el mapeo de datos y los informes. Estos identificadores deben mantenerse estables entre versiones compatibles. El uso de esquemas de versionado inconsistentes o convenciones de nomenclatura informales dificulta la evaluación de la compatibilidad. Mezclar cambios disruptivos y no disruptivos en la misma versión sin los incrementos de versión adecuados complica aún más el mantenimiento. Por último, una documentación insuficiente genera confusión sobre qué cambió y por qué, lo que dificulta la gobernanza a largo plazo. ## Conclusión Versionado de Questionnaires El versionado de los recursos Questionnaire de FHIR es un aspecto crítico para mantener la integridad de los datos, garantizar la compatibilidad y apoyar la usabilidad a largo plazo de los formularios clínicos. Una gestión adecuada de las versiones preserva la validez de los datos históricos de QuestionnaireResponse al tiempo que permite que los formularios evolucionen conforme a los requisitos clínicos cambiantes. **Conclusiones clave:** - **Uso coherente del Versionado Semántico (SemVer)**: Diferencia entre cambios menores compatibles con versiones anteriores y cambios mayores disruptivos. - **URLs estables**: Realice el seguimiento de los formularios a lo largo del tiempo mediante una `url` constante; por lo general, solo el elemento `version` cambia. - **Gestión cuidadosa de los identificadores de elementos y los códigos**: Mantiene un mapeo e informes precisos entre versiones. - **Documentación y registro de cambios**: Esencial para informar a los desarrolladores y facilitar las actualizaciones. - **Evitar errores frecuentes**: No combine cambios incompatibles en una misma versión ni modifique el `linkId` innecesariamente, reduciendo así el riesgo de errores en los flujos de trabajo clínicos. En definitiva, un versionado disciplinado permite a las organizaciones evolucionar los questionnaires de forma segura, mantener la compatibilidad retroactiva cuando sea necesario y garantizar una recopilación y análisis de datos coherentes. La aplicación de estos principios junto con ejemplos prácticos crea un ecosistema de Questionnaires fiable y mantenible. Véase también: [Renderización de Questionnaires HL7 FHIR](/blog/rendering-hl7-fhir-questionnaires) y [Cómo crear una Implementation Guide de FHIR](/blog/how-to-create-a-fhir-implementation-guide).