--- { "title": "Comment versionner un Questionnaire FHIR", "description": "Apprenez à versionner correctement les Questionnaires FHIR : quand incrémenter MAJOR, MINOR ou PATCH, quels changements brisent silencieusement la compatibilité, et les règles pratiques pour faire évoluer vos formulaires en toute sécurité.", "date": "2026-02-24", "author": "Vitalii Banchenko", "reading-time": "7 minutes", "tags": [ "Forms", "Aidbox" ] } --- Dans cet article, nous explorons le fonctionnement du versionnage des Questionnaires FHIR et son importance pour préserver l'intégrité des données. Nous passons en revue le versionnage canonique dans FHIR, discutons des approches courantes, expliquons comment gérer différents types de changements à l'aide du versionnage sémantique, et mettons en lumière des recommandations pratiques ainsi que les erreurs fréquentes. L'objectif est de fournir des directives claires pour gérer l'évolution des Questionnaires sans briser la compatibilité. ## Introduction Dans FHIR, un Questionnaire est une ressource canonique utilisée pour décrire des formulaires structurés destinés à la collecte de données de santé. Il définit une liste de questions, leur regroupement et leur ordre, les options de réponse, ainsi que des comportements dynamiques plus complexes fondés sur les réponses déjà fournies. Au fil du temps, les formulaires changent : de nouvelles questions sont ajoutées, la formulation est précisée, la structure est réorganisée et les éléments désuets sont supprimés. Ces changements sont inévitables, mais ils soulèvent un défi critique : comment s'assurer que les données QuestionnaireResponse collectées précédemment demeurent correctes et interprétables. Puisque Questionnaire est une ressource canonique, il suit les règles de versionnage canonique. Le versionnage vous permet d'identifier de façon unique le formulaire utilisé lors de la collecte de données, de garantir l'interprétation correcte des réponses, de conserver un historique d'audit et d'introduire des améliorations en toute sécurité sans compromettre la compatibilité. Sans un versionnage adéquat, même de petites modifications structurelles peuvent rendre les données historiques peu fiables. ## Versionnage canonique dans FHIR Les ressources canoniques dans FHIR (telles que Questionnaire, StructureDefinition, ValueSet, CodeSystem) sont réutilisables, stables et versionnées. Elles sont identifiées par une url globalement unique et une version. Un exemple minimal : ```javascript { "resourceType": "Questionnaire", "url": "http://aidbox.app/fhir/Questionnaire/vitals-form", "version": "1.0.0", "status": "active" } ``` L'url est un identifiant logique permanent et doit demeurer inchangée d'une version à l'autre. La version identifie une édition précise du formulaire et change chaque fois que le formulaire est modifié de façon significative. Le status (draft, active, retired, unknown) reflète l'état du cycle de vie, et non le versionnage lui-même. Lorsqu'un Questionnaire est complété, le QuestionnaireResponse doit référencer la version exacte utilisée : ```javascript "questionnaire": "http://aidbox.app/fhir/Questionnaire/vitals-form|1.0.0" ``` Cette référence garantit l'interprétation correcte des données même si des versions ultérieures sont introduites par la suite. Chaque nouvelle version est effectivement une nouvelle ressource. Les versions déjà publiées doivent demeurer immuables. Plusieurs versions peuvent coexister dans le système — cela est fondamental pour la rétrocompatibilité et la conformité réglementaire. ## Approches de versionnage FHIR ne définit pas strictement la structure que doivent avoir les numéros de version. À partir de [FHIR R5](/articles/fhir-r4-vs-fhir-r5-choosing-the-right-version-for-your-implementation), l'élément facultatif versionAlgorithml peut préciser l'approche retenue (sémantique, numérique, basée sur la date, etc.), mais il n'est pas obligatoire. L'approche la plus répandue et recommandée est le Versionnage Sémantique (SemVer) au format MAJOR.MINOR.PATCH (par exemple, 2.1.0). Dans ce modèle : - MAJOR indique des changements non rétrocompatibles qui affectent la compatibilité (suppression de questions, modification de linkId, restructuration du formulaire). - MINOR indique des ajouts rétrocompatibles (ajout de questions, extension des options de réponse). - PATCH indique des corrections non disruptives (fautes de frappe, clarification de la formulation sans changement de sens). Le versionnage sémantique rend la compatibilité explicite et aide les développeurs à déterminer si une mise à niveau est sécuritaire. Parmi les autres approches, on trouve le versionnage par date (p. ex., 2025-08 ou 2025.08.15), qui indique clairement la date de publication mais ne renseigne pas sur la compatibilité, ainsi que les schémas incrémentiels simples ou alphanumériques (1, 2, 3 ou rev1, rev2), qui sont souples mais manquent de clarté sémantique. Quelle que soit la méthode choisie, il est essentiel d'utiliser une approche cohérente pour chaque formulaire (même url) et de s'assurer que chaque paire (url, version) est unique. ## Scénarios de changement courants et versionnage SemVer Lors de la modification d'un Questionnaire, la question clé est de savoir si le changement affecte la structure ou l'interprétation des données collectées. La réponse détermine l'incrément de version requis. Examinons les types de changements suivants : - Ajout d'une question - Suppression d'une question - Modification d'un linkId - Modification d'un code - Modification du texte - Modification de l'ordre des questions - Modification de la structure des groupes - Modification de la logique de complétion ### Ajout de questions L'ajout d'une nouvelle question sans modifier les questions existantes est un changement rétrocompatible et doit incrémenter la version mineure (1.1.0 → 1.2.0). ### Suppression de questions La suppression d'une question est un changement non rétrocompatible et exige une augmentation de la version majeure (1.1.0 → 2.0.0). ### Modification du linkId La modification d'un linkId brise le lien entre les éléments du Questionnaire et les réponses du QuestionnaireResponse; elle doit donc toujours être traitée comme un changement majeur (1.1.0 → 2.0.0). ### Modification des codes (code) La mise à jour ou le remplacement des codes utilisés pour l'identification sémantique des questions (p. ex., LOINC, SNOMED CT) peut modifier le sens clinique d'une question et affecter l'interopérabilité. Toutefois, l'impact dépend de la nature du changement : - Si un code est entièrement remplacé par un autre, il s'agit d'un changement non rétrocompatible qui exige une mise à jour de version majeure (1.1.0 → 2.0.0). - Si un code supplémentaire est ajouté sans supprimer l'ancien, il s'agit d'une mise à jour de version mineure (1.1.0 → 1.1.1). ### Modification du texte des questions L'ajustement de la formulation, la traduction dans une autre langue ou la correction de fautes de grammaire peuvent correspondre à différents types de changements, selon que le sens est modifié ou non : - Si le sens ne change pas, il s'agit d'une mise à jour de type patch (1.1.0 → 1.1.1). - Si le sens change, il s'agit d'une mise à jour majeure (1.1.0 → 2.0.0). ### Modification de l'ordre des questions La réorganisation des éléments au sein du même niveau d'imbrication n'affecte généralement pas l'interprétation, mais peut modifier l'expérience utilisateur et le déroulement de la complétion. Il s'agit d'un changement de version mineure (1.1.0 → 1.1.1). ### Modification de la structure des groupes Le déplacement de questions entre des groupes ou la modification de l'imbrication peut affecter la façon dont les réponses sont mappées et peut également briser des règles enableWhen (p. ex., une question précédemment à l'intérieur d'un groupe masqué par défaut) — entraînant des résultats imprévisibles. Ces changements doivent être traités comme une mise à jour de version majeure (1.1.0 → 2.0.0). ### Modification de la logique de complétion Les modifications apportées à enableWhen, required, maxLength et d'autres règles peuvent affecter les réponses collectées. - S'il s'agit d'ajustements mineurs, il s'agit d'une mise à jour de version mineure. - S'ils modifient significativement les conditions, il s'agit d'une mise à jour de version majeure. ## Recommandations pratiques et bonnes pratiques Un versionnage approprié d'un Questionnaire minimise le risque de bris de compatibilité et simplifie la maintenance des formulaires. Voici des recommandations fondées sur l'expérience de mise en œuvre de FHIR dans des systèmes cliniques. ### Ne pas modifier les versions publiées Une fois qu'un Questionnaire est publié avec un statut active, son contenu doit demeurer inchangé. Toute modification — même la correction d'une faute de frappe — exige la publication d'une nouvelle version. Les versions historiques doivent rester immuables afin de préserver l'intégrité des réponses. ### Assurer l'unicité de la paire (url, version) Chaque version d'un formulaire doit posséder une combinaison unique d'url et de version. Cette règle permet l'identification non ambiguë d'une édition précise du formulaire dans n'importe quel système. Il est recommandé de mettre en place des vérifications automatiques d'unicité lors de la publication. ### Documenter les changements Il est fortement recommandé de tenir un journal des modifications documentant chaque changement, la raison de la modification et s'il s'agit d'une mise à jour majeure, mineure ou de type patch. Une documentation claire simplifie les audits et l'évaluation de la compatibilité. ### Utiliser le contrôle du cycle de vie Statuts du Questionnaire Les statuts draft → active → retired doivent refléter l'état réel du formulaire. - N'utilisez pas active pour des formulaires de test ou incomplets. - Lors du passage d'un formulaire à retired, assurez-vous qu'il n'est plus utilisé dans les flux de travail en cours. Processus de publication type : Brouillon (draft) → Vérification → Publication (active). ### Lier les réponses à une version précise Dans QuestionnaireResponse.questionnaire, incluez toujours une référence au format : {url}|{version}. ```javascript "questionnaire": "http://aidbox.app/fhir/Questionnaire/vitals-form|1.1.0" ``` Cela garantit l'interprétation correcte des données même si le formulaire change dans le futur. ### Intégrer les vérifications au processus de publication Vérifications de version Avant d'activer une nouvelle version, il est utile d'automatiser les vérifications suivantes : - S'assurer qu'il n'y a pas de doublons de url + version. - Vérifier qu'il n'existe pas de références au formulaire dans des flux de travail non terminés si la version change. - Analyser la différence entre les versions pour déterminer le niveau de changement. ### Planifier la compatibilité à l'avance Impact des changements - Si le formulaire est susceptible d'évoluer, utilisez des linkIds et des codes (code) stables dès la première version. - Évitez les changements non rétrocompatibles à moins que cela ne soit nécessaire. - Envisagez d'utiliser des ressources Library ou des composants distincts pour réduire l'impact des mises à jour. ## Erreurs courantes dans le versionnage des Questionnaires Une erreur fréquente consiste à modifier l'url au lieu d'incrémenter la version. L'url doit demeurer stable pour préserver la continuité. Seule la version doit changer. Un autre problème courant est d'ignorer la rétrocompatibilité. La suppression de questions ou la modification d'identifiants sans augmentation de la version majeure peut conduire à une interprétation incorrecte des réponses existantes. Modifier le linkId ou les codes cliniques sans réflexion approfondie peut briser le mappage des données et les rapports. Ces identifiants doivent demeurer stables d'une version compatible à l'autre. L'utilisation de schémas de versionnage incohérents ou de conventions de nommage informelles rend difficile l'évaluation de la compatibilité. Le mélange de changements non rétrocompatibles et rétrocompatibles dans une même version sans incrément de version approprié complique davantage la maintenance. Enfin, une documentation insuffisante crée de la confusion quant à ce qui a changé et pourquoi, rendant la gouvernance à long terme plus difficile. ## Conclusion Versionnage des Questionnaires Le versionnage des ressources Questionnaire FHIR est un aspect critique du maintien de l'intégrité des données, de la garantie de la compatibilité et du soutien à la pérennité des formulaires cliniques. Une gestion appropriée des versions préserve la validité des données historiques QuestionnaireResponse tout en permettant aux formulaires d'évoluer en fonction des besoins cliniques changeants. **Points clés à retenir :** - **Utilisation cohérente du Versionnage Sémantique (SemVer)** : Distinguer les changements mineurs rétrocompatibles des changements majeurs non rétrocompatibles. - **URL stables** : Suivre les formulaires dans le temps à l'aide d'une url constante; en général, seul l'élément version change. - **Gestion rigoureuse des identifiants d'éléments et des codes** : Maintient un mappage et des rapports précis d'une version à l'autre. - **Documentation et journal des modifications** : Essentiels pour informer les développeurs et faciliter les mises à jour. - **Éviter les pièges courants** : Ne pas combiner des changements incompatibles dans une même version ni modifier linkId inutilement, réduisant ainsi le risque d'erreurs dans les flux de travail cliniques. En définitive, un versionnage rigoureux permet aux organisations de faire évoluer les questionnaires en toute sécurité, de maintenir la rétrocompatibilité lorsque nécessaire, et d'assurer une collecte et une analyse cohérentes des données. L'application de ces principes, accompagnée d'exemples concrets, crée un écosystème de Questionnaires fiable et facile à maintenir. Voir aussi : [Rendu des Questionnaires HL7 FHIR](/blog/rendering-hl7-fhir-questionnaires) et [Comment créer un Guide d'implémentation FHIR](/blog/how-to-create-a-fhir-implementation-guide).