In this article, we explore how versioning works for FHIR Questionnaires and why it is essential for maintaining data integrity. We review canonical versioning in FHIR, discuss common versioning approaches, explain how to handle different types of changes using semantic versioning, and highlight practical recommendations and common mistakes. The goal is to provide clear guidance for managing Questionnaire evolution without breaking compatibility.
Introduction
In FHIR, a Questionnaire is a canonical resource used to describe structured forms for collecting healthcare data. It defines a list of questions, their grouping and order, answer options, as well as more complex dynamic behavior based on already provided answers. Over time, forms change: new questions are added, wording is clarified, structure is reorganized, and outdated elements are removed.
These changes are inevitable, but they introduce a critical challenge: how to ensure that previously collected QuestionnaireResponse data remains correct and interpretable.
Because Questionnaire is a canonical resource, it follows canonical versioning rules. Versioning allows you to uniquely identify the form used for data collection, ensure correct interpretation of responses, maintain audit history, and safely introduce improvements without compromising compatibility. Without proper versioning, even small structural changes can make historical data unreliable.
Canonical versioning in FHIR
Highlighted Text
Canonical resources in FHIR (such as Questionnaire, StructureDefinition, ValueSet, CodeSystem) are reusable, stable, and versioned. They are identified by a globally unique url and a version.
A minimal example:
{
"resourceType": "Questionnaire",
"url": "http://aidbox.app/fhir/Questionnaire/vitals-form",
"version": "1.0.0",
"status": "active"
}
Highlighted Text
The url is a permanent logical identifier and must remain unchanged across versions. The version identifies a specific edition of the form and changes whenever the form is modified in a meaningful way. The status (draft, active, retired, unknown) reflects lifecycle state, not versioning itself.
When a Questionnaire is completed, the QuestionnaireResponse should reference the exact version used:
"questionnaire":
"http://aidbox.app/fhir/Questionnaire/vitals-form|1.0.0"
This reference guarantees the correct interpretation of the data even if newer versions are later introduced. Each new version is effectively a new resource. Previously published versions must remain immutable. Multiple versions can coexist in the system — this is fundamental for backward compatibility and regulatory compliance.
Approaches to Versioning
Highlighted Text
FHIR does not strictly define how version numbers must be structured. From FHIR R5, the optional versionAlgorithml element can specify the chosen approach (semantic, numeric, date-based, etc.), but it is not mandatory.
The most widely used and recommended approach is Semantic Versioning (SemVer) in the format MAJOR.MINOR.PATCH (for example, 2.1.0). In this model:
- MAJOR indicates breaking changes that affect compatibility (removing questions, changing linkId, restructuring the form).
- MINOR indicates backward-compatible additions (adding questions, extending answer options).
- PATCH indicates non-breaking fixes (typos, wording clarification without meaning change).
Semantic versioning makes compatibility explicit and helps implementers decide whether upgrading is safe.
Other approaches include date-based versioning (e.g., 2025-08 or 2025.08.15), which clearly shows publication time but does not indicate compatibility, and simple incremental or alphanumeric schemes (1, 2, 3 or rev1, rev2), which are flexible but lack semantic clarity.
Highlighted Text
Regardless of the chosen method, it is essential to use one consistent approach per form (same url) and ensure that each (url, version) pair is unique.
Typical Change Scenarios and SemVer versioning
When modifying a Questionnaire, the key question is whether the change affects the structure or interpretation of collected data. The answer determines the required version increment.
Let’s consider the following types of changes:
- Adding a question
- Removing a question
- Changing a linkId
- Changing a code
- Changing text
- Changing question order
- Changing group structure
- Changing completion logic
Adding Questions
Adding a new question without altering existing ones is a backward-compatible change and should increment the minor version (1.1.0 → 1.2.0).
Removing Questions
Removing a question is a breaking change and requires a major version increase (1.1.0 → 2.0.0).
Changing linkId
Highlighted Text
Changing linkId breaks the binding between Questionnaire items and QuestionnaireResponse answers, so it must always be treated as a major change (1.1.0 → 2.0.0).
Changing Codes (code)
Updating or replacing codes used for semantic identification of questions (e.g., LOINC, SNOMED CT) may change the clinical meaning of a question and affect interoperability. However, the impact depends on the nature of the change:
- If a code is completely replaced with another, it is a breaking change that requires a major version update (1.1.0 → 2.0.0).
- If an additional code is added without removing the old one, it is a minor version update (1.1.0 → 1.1.1).
Changing Question Text
Adjusting wording, translating into another language, or fixing grammar errors can fall into different types of changes, depending on whether the meaning changes:
- If the meaning does not change, it is a patch update (1.1.0 → 1.1.1).
- If the meaning does change, it is a major update (1.1.0 → 2.0.0).
Changing Question Order
Reordering elements within the same nesting level usually does not affect interpretation, but it may change the UX and the flow of completion. This is a minor version change (1.1.0 → 1.1.1).
Changing Group Structure
Highlighted Text
Moving questions between groups or changing nesting can affect how responses are mapped,and may also break enableWhen rules (e.g., a question previously inside a hidden-by-default group) — leading to unpredictable results. Such changes should be treated as a major version update (1.1.0 → 2.0.0).
Changing Completion Logic
Highlighted Text
Edits in enableWhen, required, maxLength, and other rules may affect which responses are collected.
- If these are minor adjustments, it is a minor version update.
- If they significantly change conditions, it is a major version update.
Practical Recommendations and Best Practices
Highlighted Text
Proper versioning of a Questionnaire minimizes the risk of breaking compatibility and simplifies form maintenance.Below are recommendations based on experience implementing FHIR in clinical systems.
Do Not Modify Published Versions
Highlighted Text
Once a Questionnaire is published with an active status, its content must remain unchanged. Any modification — even a typo correction — requires releasing a new version. Historical versions must remain immutable to preserve response integrity.
Ensure Uniqueness of (url, version) Pair
Highlighted Text
Each version of a form must have a unique combination of url and version. This rule allows unambiguous identification of a specific form edition in any system. It is recommended to implement automatic uniqueness checks upon publication.
Document Changes
It is strongly recommended to maintain a changelog documenting each modification, the reason for the change, and whether it represents a major, minor, or patch update. Clear documentation simplifies auditing and compatibility assessment.
Use Lifecycle Control
Questionnaire Statuses
Statuses draft → active →
retired should reflect the actual state of the form.
-
Do not use active for test or incomplete forms.
-
When moving a form to retired, ensure it is no longer used in ongoing workflows.
Typical publication process: Draft (draft) → Verification →
Publication (active).
Link Responses to a Specific Version
Highlighted Text
In QuestionnaireResponse.questionnaire, always include a reference in the format: {url}|{version}.
"questionnaire":
"http://aidbox.app/fhir/Questionnaire/vitals-form|1.1.0"
This ensures the correct interpretation of data even if the form changes in the future.
Integrate Checks into the Publication Process
Version Checks
Before activating a new version, it is useful to automate the following checks:
-
Ensure no duplicates of url + version.
-
Verify there are no references to the form in unfinished workflows if the version changes.
-
Analyze the diff between versions to determine the level of changes.
Plan for Compatibility in Advance
Change Impact
-
If the form is expected to evolve, use stable linkIds and codes
(code) from the first release.
-
Avoid backward-incompatible changes unless necessary.
-
Consider using Library resources or separate components to reduce
the impact of updates.
Common Mistakes in Questionnaire Versioning
Highlighted Text
One common mistake is changing the url instead of incrementing the version. The url must remain stable to preserve continuity. Only the version should change.
Another frequent issue is ignoring backward compatibility. Removing questions or altering identifiers without increasing the major version can lead to incorrect interpretation of existing responses.
Changing linkId or clinical codes without careful consideration can break data mapping and reporting. These identifiers should remain stable across compatible versions.
Using inconsistent versioning schemes or informal naming conventions makes it difficult to assess compatibility. Mixing breaking and non-breaking changes within the same release without proper version increments further complicates maintenance.
Finally, insufficient documentation creates confusion about what changed and why, making long-term governance more difficult.
Conclusion
Questionnaire Versioning
Versioning of FHIR Questionnaire resources is a critical aspect of maintaining data integrity, ensuring compatibility, and supporting the long-term usability of clinical forms.
Proper version management preserves the validity of historical QuestionnaireResponse data while allowing forms to evolve according to changing clinical requirements.
Key takeaways:
-
Consistent use of Semantic Versioning (SemVer):
Differentiate between minor, backward-compatible changes and major, breaking changes.
-
Stable URLs:
Track forms over time using a constant url; typically, only the version element changes.
-
Careful management of element identifiers and codes:
Maintains accurate mapping and reporting across versions.
-
Documentation and changelog:
Essential for informing developers and supporting updates.
-
Avoid common pitfalls:
Do not combine incompatible changes in one version or change
linkId unnecessarily, reducing the risk of errors in clinical workflows.
Ultimately, disciplined versioning enables organizations to safely evolve questionnaires,
maintain backward compatibility when needed, and ensure consistent data collection and analysis.
Applying these principles alongside practical examples creates a reliable and maintainable
Questionnaire ecosystem.
