FHIR CI-Build
FoundationThis is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions 
| FHIR Infrastructure Work Group | Maturity Level: Normative | Standards Status: Normative |
This page documents the way version change is handled in FHIR. FHIR is a standard, so the way version change is handled is a bit different from an application API. This page describes:
See also Managing FHIR Versions for additional implementer advice about dealing with versions.
FHIR is a standard. In order to be useful, standards need to evolve. At the same time, the evolution of standards needs to be predictable and manageable for the implementation community. This section describes how HL7 develops a standard so that implementers know what to expect as the standard evolves.
HL7 has five descriptive terms that describe the level of stability and implementation readiness associated with different aspects of the specification. They are as follows:
| Standard Level | Description |
|---|---|
| Normative | This content was approved by the ANSI standards process in a previous version (see Normative status note).
It has been subject to review and production implementation in a wide variety of environments.
The content is considered to be stable and has been 'locked', subjecting it to FHIR
Inter-version Compatibility Rules. While changes are possible, they are
expected to be infrequent and are tightly constrained.
Note that this version of the specification has NOT been submitted to ANSI for consideration as a normative standard. |
| Trial Use |
This content has been well reviewed and is considered by the authors to be ready for use in production systems. It has been subjected to ballot and approved as an official standard. However, it has not yet seen widespread use in production across the full spectrum of environments it is intended to be used in. In some cases, there may be documented known issues that require implementation experience to determine appropriate resolutions for. Future versions of FHIR may make significant changes to Trial Use content that are not compatible with previously published content. |
| Draft | This portion of the specification is not considered to be complete enough or sufficiently reviewed to be
safe for implementation. It may have known issues or still be in the "in development" stage. It is included
in the publication as a place-holder, to solicit feedback from the implementation community and/or to give
implementers some insight as to functionality likely to be included in future versions of the specification.
Content at this level should only be implemented by the brave or desperate and is very much "use at your own
risk". The content that is Draft that will usually be elevated to Trial Use once review and
correction is complete after it has been subjected to ballot
Some resources with a standards status of 'draft' have an FMM level of 1 or 2 - this means that the committee responsible for them is ready for them to be tested and balloting, but that balloting has not yet occurred. Draft resources cannot have a FMM level greater than 2 |
| Informative | This portion of the specification is provided for implementer assistance and does not make rules that implementers are required to follow. Typical examples of this content in the FHIR specification are tables of contents, registries, examples, and implementer advice |
| Deprecated | This portion of the specification is outdated and may be withdrawn in a future version. Implementers who already support it should continue to do so for backward compatibility. Implementers should avoid adding new uses of this portion of the specification. The specification should include guidance on what implementers should use instead of the deprecated portion |
Some Normative artifacts contain a few parts labeled as 'Trial Use' even though the artifact itself is labeled 'Normative':
While HL7 prefers to avoid this outcome, there are several resources where the overall functionality of the artifact is clearly ready to be labeled as 'normative' while some very specific parts are known not to have the requisite level of implementation experience as the rest of the resource. E.g. Bundle.signature.
Where a Normative resource contains elements marked as trial-use, these elements are clearly marked in the resource definitions. Implementers should be aware that future versions of the FHIR specification may change these parts of the resources (in addition to the other changes allowed under the inter-version compatibility rules. While HL7 will carefully consider the consequences of breaking change to these elements, implementers should be aware that reading/using these elements has the potential to cause breaking change to their applications later.
Note that this same status will arise as a matter of process when new elements are introduced into normative resources in future versions - they will undergo a period of trial use as appropriate.
Note: it is also possible that some resources in the future will be labeled as 'trial use', but contain some elements labeled as 'normative'. There is no resource like this in this specification, though all Trial Use resources contain normative content from Resource and DomainResource, and the Datatypes.
Notes:
The content of this release has been subject to significant review through ballot and other HL7 processes and many aspects of it have been
implemented and subjected to interoperability testing through Connectathons and early adoption. However, the degree of testing has varied. Some resources
have been well tested in a variety of environments. Others have received relatively little real-world exercise. In general, the infrastructure should be
considered to be more stable than the resources themselves. In some cases, there are issues on which input is specifically requested during the
Trial Use period
(see the Outstanding Issue List, and known issues will arise after publication (refer to the
FHIR Change Request tracker for details.)
Guidance from early implementation will help address these areas.
All artifacts in this specification are assigned a "Maturity Level", known as FMM (after the well-known CMM grades).
The FMM level can be used by implementers to judge how advanced - and therefore stable - an artifact is. The following FMM levels are defined:
| Draft (0) | the artifact has been published on the current build. Artifacts with this level must have a standards status of Draft. |
| FMM 1 | FMM0 + the artifact produces no warnings during the build process and the responsible work group has indicated that they consider the artifact substantially complete and ready for implementation. For resources, profiles and implementation guides, the FHIR Management Group has approved the underlying resource/profile/IG proposal. |
| FMM 2 | FMM1 + the artifact has been tested and successfully supports interoperability among at least three independently developed systems leveraging most of the scope (e.g. at least 80% of the core data elements) using semi-realistic data and scenarios based on at least one of the declared scopes of the artifact (e.g. at a connectathon). These interoperability results must have been reported to and accepted by the FHIR Management Group. |
| FMM 3 | FMM2 + the artifact has been verified by the work group as meeting the Conformance Resource Quality Guidelines ; has been subject to a round of formal balloting; has at least 10 distinct implementer comments recorded in the tracker drawn from at least 3 organizations resulting in at least one substantive change. |
| FMM 4 | FMM3 + the artifact has been tested across its scope (see below), published in a formal publication (e.g. STU), and implemented in multiple prototype projects. As well, the responsible work group agrees the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes. |
| FMM 5 | FMM4 + the artifact has been published in two formal publication release cycles as STU and has been implemented in at least 5 independent production systems in more than one country. |
| FMM 6 (N) | FMM5 + the responsible work group and the FHIR management group agree the material is ready to lock down according to the inter-version change rules and the artifact has passed HL7 normative ballot. This is synonymous with Normative standard status. |
Tested across scope means:
has signed off on the list of "example contexts" defined for the artifactThe Maturity level is strongly related to stability; the higher the maturity level, the more controls are enforced to restrict breaking changes to the resource
The table above represents a frozen snapshot of the maturity levels maintained by the FHIR Management Group on the FHIR Confluence page . Further information and discussion about these levels can be found there.
The maturity model is significantly influenced by the degree and type of implementation activity using an artifact. For this reason,
we encourage implementers to register their implementations .
A detailed analysis of the basis for the maturity metrics for FHIR artifacts can be found here .
Implementation Note: For this release (R5), please note:
- The rules for FMM levels will be reviewed prior to the next release to reflect the size of the FHIR implementation community and to place more value on the rate of external adoption
- The FMM levels for some resource types in R5 have been increased at the discretion of the FHIR management group in accordance with the community adoption without meeting all the internal process requirements
- Timelines for the publication for R5 did not allow formal review of FMM levels for all resources. Some resources may meet higher requirements than those listed
Once review is complete, FMM levels will be reflected in the CI-build
New versions of FHIR will be published on a release cycle of approximately 18-24 months. This frequency is based on the timelines necessary to consult with implementers, to develop and review new content, as well as to undertake the formal balloting and reconciliation processes required for ANSI-approved standards. This release cycle also ensures an opportunity to incorporate implementer feedback from earlier versions of the specification into subsequent versions. Limited-scope releases on a shorter timeline may occur occasionally where necessary to meet implementer needs.
Each new release is assigned a unique version number. The FHIR version policy is based on
Semantic versioning , but with some differences due to the
fact that FHIR is a specification, not a software API.
There is a single development version of FHIR. This undergoes cycles of development as managed by HL7. Each major cycle of development is concluded by a formal ballot (or more than one), and then a new specification is published. In version control terms, each published specification is a branch off the development trunk, which may then itself undergo further change as HL7 maintains the published specification (though such changes are usually minimal, limited to necessary technical corrections or security alerts).
Each FHIR version is identified by a string composed from 4 parts: major.minor.patch-label.
| major |
|
| minor |
|
| patch |
|
| label |
|
Additional notes:
The FHIR version is usually known implicitly, but can be specified/determined by one of three methods:
For further information, see Managing Multiple FHIR Versions.
The following kinds of changes may be made to the specification:
The intent of these rules is to ensure that applications that are conformant to an existing specification are also conformant to subsequent versions. In practice, there are many subtle issues around inter-version change, and the exact rules are subject to further clarification based on feedback from implementers.
Content with a status of Draft or Trial Use can change - including Breaking Changes - from version to version, subject to the rules described by the Maturity Process. There are no rules for maintaining any sort of compatibility between versions for content with these statuses, though of course we will only make breaking changes based on feedback from the community.
Once an artifact achieves Normative status, specific rules come into play around inter-version compatibility. These rules have implication for both forward and backward compatibility and are intended to allow implementations to exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between systems using different versions of FHIR. These rules do not apply to non-normative content, including STU content within normative artifacts.
In rare circumstances, HL7 may approve changes that technically break content with a status of Normative where there is a high level of confidence that the change will not impact existing implementers. Such deviations from the declared rules will involve broad notification, extensive community consultation and reviews by multiple levels of HL7 governance processes.
Yes, this this is the second dragon in as many paragraphs. Inter-version compatibility is complicated...
The assertion around non-breaking change does NOT mean that the types of changes permitted here cannot cause existing systems to fail, even if they make allowances for the types of changes permitted. (Though those that make allowances will hopefully fail more gracefully.) Because the requirements of healthcare continue to evolve, the rules defined here allow for new content to be introduced - new codes, new elements, etc. Depending on the design of a receiving system, such new content may cause failure. A system that relies on schema validation will fail because of a new element. A system that relies on a select statement iterating through 'status' codes might fail or behave unexpectedly due to incorrect fall-through when a new status code is introduced. Systems designers are strongly encouraged to consider the types of changes permitted here and consider how these types of changes will impact their ability to safely function when dealing with newer versions of FHIR.
NOTE: The examples provided as part of this specification are never substantive. While every effort is made to ensure that FHIR examples are correct, changes to the examples in the specification are not considered substantive.
Forward compatibility means that content that is conformant in an old release will remain conformant with future versions. Once normative, FHIR's rules try to enforce forward compatibility. However, that doesn't guarantee that all old systems will interoperate with future systems.
Backward compatibility means that instances created against future versions of the specification will interoperate with older versions of the specification. This is not guaranteed by FHIR, though there are strategies systems can adhere to that will increase their chances of such interoperability. Specifically, when dealing with content from a system supporting an unknown normative version and wishing to maximize backwards compatibility, applications SHOULD:
However, in a healthcare context, many implementers are unwilling to consider some of these steps because of concerns about clinical risk or technical limitations in their software (e.g. schema-based processing).
.
| Category | Allowed changes |
|---|---|
| Resources | New artifacts resources may be introduced. Existing resources will not have their names changed |
| Artifacts (resources, profiles, code systems, etc.) | New artifacts including new resources and datatypes may be introduced. Existing artifacts will not have any computable identifiers (e.g. resource names) changed. Artifacts may be deprecated |
| Elements | New optional elements and/or content (e.g. XML attributes, etc.) may be introduced at any location in resource and datatype structures provided they do not constitute "isModifier" elements. However, the names, path and meaning of previously existing data elements will not be changed. This means there will be no change to resource names and no changes to names assigned to slices and other elements within profiles. |
| Cardinality | Minimum element cardinalities will not be changed. Upper cardinality may change from 1 to * only in circumstances where all elements except for the first repetition can be safely ignored. Note that this may change the path to the element in some syntaxes (e.g. JSON). This may mean that an order is assigned to the repeating items or that there is no preference as to which element is retained. Systems should follow the rules above for unexpected elements. Because of the JSON issue, changes to cardinality for normative elements will be minimized whenever possible, e.g. by defining new sibling elements. |
| Descriptions | Descriptive information about a resource - short labels, definitions, usage notes, aliases, examples, rationale, mappings, etc. may be updated or revised to provide additional clarity or guidance, but not in such a manner as to invalidate a reasonable interpretation of the previously documented use of an element. (This does not preclude fixing obvious errors.) |
| Value Sets and Code Systems |
The definition of any value set that is marked as immutable will never change. The expansions for immutable value sets may still change if no "stable date" is declared and the value set does not restrict code system and/or value set references to specific versions and the codes in the referenced code system(s) or value set(s) change. For non-immutable value sets:
For both immutable and non-immutable value sets, additional designations may be declared. Normative CodeSystems whose content is generated from a mix of normative and non-normative contents may break these rules. For example, the code system containing the list of all resources may have codes removed or renamed as non-normative resources are removed or renamed. These expectations only apply to Value Sets and Code Systems maintained as part of the FHIR specification. HL7 cannot enforce these rules on terminology artifacts maintained by other authorities - e.g. UCUM unit codes, ISO language codes, etc. |
| Terminology Bindings |
|
| Datatypes |
Except as described in the preceding paragraph, Datatypes will not be removed or changed except as allowed above for elements. New datatypes may be introduced. Types declared on existing elements will not be
removed or changed, except for the special case that string may be changed to markdown.
Additional datatypes may be added to elements which are already expressed as a choice of datatypes only if those elements are optional (minimum cardinality = 0).
|
| Value Constraints | The allowed list of Datatypes will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed in a way that could invalidate previous instances. New warning or best practice invariants may be added. 'Error' invariants may be added that are tied to newly introduced elements or codes, or existing rules in the specification narrative. |
| Flags | The Is Modifier and Is Summary flags will not be changed. |
| Slicing | Slicing rules and aggregation characteristics will not be changed. |
| Search Criteria | Search criteria may be added but not removed or renamed. Existing criteria will not have their type or path changed or have their description altered in any way that would invalidate the reasonable behavior of existing systems (except for correcting obvious errors). |
| Operations | New operations may be defined but operations will not be removed or renamed. Existing parameters will not be removed or renamed, nor may their type or lower cardinality be changed. Upper cardinality may be changed from 1 to *. (Systems should ignore unexpected repetitions.) Additional optional parameters may be introduced. Changes to operations that would violate the preceding constraints will be handled by defining new operations and, potentially, deprecating the old operations. |
| Restful interface | Existing endpoints will not be renamed or removed, nor have their expected behavior changed in a manner that would cause reasonable systems designed against prior versions to be non-interoperable. Additional endpoints and interactions may be introduced. |
| Profiles and extension definitions | Profile structure, extension definitions and search criteria definitions will not be removed or have their URIs changed. New profile structures, extension definitions and search criteria definitions may be introduced. Profiles may have their statuses changed to "retired". Profiles referenced by data elements for structures or datatypes may be replaced with a reference to a distinct profile that is "compatible" with the previously referenced profile according to these forward and backward compatibility rules. |
| Capability Statements | Within the CapabilityStatements for defined FHIR Services or 'core' implementation guides, additional operations may be added. These additions might be optional (MAY/SHOULD) or mandatory (SHALL). Note that the introduction of mandatory operations would break forwards compatibility and will only occur with community consultation. |
| Implementation Guides | Additional artifacts can be added, and artifacts can be changed. The list of global profiles will not change |
| References | Where one conformance resource points to another (e.g. CapabilityStatement to profile, profile to profiles, profile to value set, etc.), the reference may change to point to a newer version of the conformance resource or to a distinct conformance resource so long as the content of the newly referenced resource adheres to the compatibility rules with respect to the previously referenced version. Additional resources or profiles can also be added to the list of available targets for a reference. Where a reference is to a non-normative resource, the name of the referenced resource may still change between versions until such time as the referenced resource becomes normative. In some cases, non-normative resources may be removed in future versions of the FHIR spec. |
| Conformance Language | SHALL statements cannot be broken (though they can be clarified) and new SHALL statements cannot be introduced unless they are conditional based on version. E.g. "Instances in version x and higher of FHIR SHALL..." Changes of SHOULD to MAY and vice versa as well as introducing new MAY and SHOULD statements are permitted. |
Once content is normative, there is a process for removing it from the standard by marking it as
deprecated or withdrawn (from the HTML 4.0 Standard ):
| Deprecated | Systems should continue to support the artifact/feature/concept, but are discouraged from making use of it |
| Withdrawn | Documented for historical purposes, no longer supported |
The specification will provide guidance with deprecated materials showing how to avoid using them.
Deprecated materials are eligible to be balloted to be withdrawn two years after their deprecated status is published.
The computable artifact labels (e.g. codes, element names, urls, etc.) associated with withdrawn materials SHALL not be used in future versions of HL7 specifications. Materials marked "deprecated" may have that marking removed as part of a subsequent ballot at a later moment, while withdrawn materials SHALL NOT.
The following artifacts are deprecated in this version of FHIR:
Additional discussion on inter-versioning issues can be found here:
https://confluence.hl7.org/display/FHIR/Interversion+Compatibility .
Regardless of the degree of prior implementation, all aspects of the FHIR specification are potentially subject to change while an artifact has a status of Draft or Trial Use. These changes may be minor (clarifications of definitions, etc.) or major (refactoring of resources, changes to serialization rules, eliminating or adding datatypes, etc.) There is no commitment to backward or forward compatibility during the trial use process until content is normative. Changes will not be made without cause, however the interests of long-term implementability will generally trump the impact on early adopters when determining what changes should be made. This balance will shift more towards early adopters as maturity levels increase. I.e. Impact on existing implementations will be weighted more highly for an FMM-level 5 artifact than they would for an FMM-level 1 artifact.
Implementers who are willing to accept the risk of change (perhaps for the benefit of early implementation experience, first mover advantage and the ability to leverage FHIR's intrinsic benefits) are encouraged to implement those parts of FHIR that are early in the maturity cycle in real-world systems. However, those implementers should be aware that local adaptations may be necessary to meet real-world requirements. Furthermore, such implementers should architect their solutions to be tolerant of changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification or different local adaptations.
During the Trial Use period, requests for change may be submitted using the HL7 issue tracker which can be found
here . Where possible, updates to the
"development" version of the specification will be made in a timely fashion. Implementers should be aware that the changes are not
considered "official" until such time as they are balloted and approved as part of a subsequent Trial Use or Normative publication.
Change requests might be fixes to allow implementation, clarifications or enhancements. In addition, HL7 will be developing and
introducing additional resources and profiles as part of the FHIR specification.
SDOs and regulatory bodies that are interested in making use of the FHIR specification should feel free to do so, but should consider and plan for the possibility that the specification will evolve and change prior to becoming Normative.
A key aspect of the FHIR specification development process is gaining feedback from implementers making
use of the specification. As well, the process is conditional on real-world implementation in order to
move through the maturity cycle. For this reason, all FHIR implementers are encouraged to register their
usage here , which captures contact and other information
that will allow HL7 to perform appropriate monitoring of FHIR usage. Survey information is confidential and reported in aggregate only.
Many implementations need to convert resources from one FHIR version to another. Once resources become normative (once sufficiently mature and stable), converting resources forwards from past versions is not needed. Converting back to older versions presents a challenge, however, in that the newer version may add additional elements that are not present in the older version. In some cases, the elements are simply irrelevant since the requirements they represent are not in scope for older applications, but in other cases, it is necessary to represent the data in order to cater for round-tripping.
A more complex problem arises with resources that are not yet stable (early in the maturity process). If applications have implemented less stable resources, not only do they have the problem of new elements for new requirements, the specification may change in either compatible or incompatible ways, and it may be necessary to carry data elements from past versions forward in order to allow seamless round-tripping.
In order to help implementers with this problem, any element defined in any version of FHIR is automatically assigned an extension URL that uniquely identifies the element and can be used in the relevant FHIR version. The extension URL for an element can automatically be derived:
http://hl7.org/fhir/[version]/StructureDefinition/extension-[Path]
where [version] is taken from this list:
| FHIR DSTU2 |
1.0 |
| FHIR R3 (STU3, or just R3) |
3.0 |
| FHIR R4 (mixed STU/Normative) |
4.0 |
| FHIR R4B (only STU changes) |
4.3 |
| FHIR R5 (this version) |
5.0 |
This table includes the formal milestone releases for DSTU2 and on, which are the only releases for which this process is defined. Older versions than that are not supported. Technical correction releases are not listed because they will never introduce or change elements. Ballot and interim releases are not supported for use in implementation environments
The [Path] is actually the ElementDefinition.id from the relevant StructureDefinition for the element. This leads to URLs like the following:
http://hl7.org/fhir/4.0/StructureDefinition/extension-Bundle.signature |
R4 Signature Element on Bundle |
http://hl7.org/fhir/3.0/StructureDefinition/extension-Patient.animal.species |
STU3 Species Element on Patient |
http://hl7.org/fhir/1.0/StructureDefinition/extension-ValueSet.extensible |
DSTU2 ValueSet.extensible |
Implementers should be aware of the following issues when using these extensions:
Bundle.entry.resource, DomainResource.contained, etc.)http://hl7.org/fhir/5.0/StructureDefinition/extension-Observation.value for types
allowed in Observation.value in R5 that were not allowed in an earlier version
http://hl7.org/fhir/5.0/StructureDefinition/extension-... could
never appear in an R5 instance.
targetProfile elements that refer to resources,
only those targetProfile resources that have URLs that exist in the referencing version can exist.
If a resource has been renamed, it can't be used in the prior release (note: this is because there's no
computable way of determining what names would be allowed); the alternate-reference
and alternate-canonical extensions may be used in this context. E.g. if converting
from a version that supports 3 target types when the target version only supports 2 target types, any repetition that referred to
the non-supported type would be represented as a reference or canonical instance where the content would just be the alternate extension (and a display, since something must be provided).
This table shows the mapping between primitive datatypes across versions:
| R5 | R4 | R3 | DSTU2 |
| base64Binary | base64Binary | base64Binary | base64Binary |
| boolean | boolean | boolean | boolean |
| canonical | canonical | (uri) | (uri) |
| code | code | code | code |
| date | date | date | date |
| dateTime | dateTime | dateTime | dateTime |
| decimal | decimal | decimal | decimal |
| id | id | id | id |
| instant | instant | instant | instant |
| integer | integer | integer | integer |
| markdown | markdown | markdown | markdown |
| oid | oid | oid | oid |
| positiveInt | positiveInt | positiveInt | positiveInt |
| string | string | string | string |
| time | time | time | string |
| time | unsignedInt | unsignedInt | unsignedInt |
| uri | uri | uri | uri |
| url | url | (uri) | (uri) |
| uuid | uuid | uuid | (uri) |
| integer64 | string | string | string |
To Do
There are several different variations when it comes to representing a complex datatype that has no equivalent in an earlier version. This section illustrates those situations.
A complex datatype in a resource
This is how it appears in R6:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"administeredProduct" : {
"reference" : {
"reference" : "Medication/something"
}
},
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Immunization.administeredProduct",
"extension" : [{
"url" : "reference",
"valueReference" : {
"reference" : "Medication/something"
}
}]
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
Note that this is an R5 extension, since valueAttachment was introduced in R5.
A complex datatype in a resource for a choice element
This is how it appears in R6:
{
"resourceType" : "Parameters",
"parameter" : [{
"name" : "ref",
"valueCodeableReference" : {
"concept" : {
"text" : "Something"
}
}
}]
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Parameters",
"parameter" : [{
"name" : "ref",
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Parameters.parameter.value%5Bx%5D",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
},{
"url" : "concept",
"valueCodeableConcept" : {
"text" : "Something"
}
}
}]
}]
}
A complex data type in an extension
The extension http://hl7.org/fhir/StructureDefinition/immunization-procedure is defined
in the extensions pack, but uses the R5 specific data type CodeableReference. This
is how it appears in R6:
{
"resourceType" : "Immunization",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/immunization-procedure",
"valueCodeableReference" : {
"concept" : {
"text" : "something"
},
"reference" : {
"display" : "something"
}
}
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
This is how the same extension appears in R4 using a cross-version representation of the CodeableReference:
{
"resourceType" : "Immunization",
"id" : "xver-immunization2-r4",
"status" : "completed",
"vaccineCode" : {
"text" : "something"
},
"patient" : {
"reference" : "Patient/something"
},
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/immunization-procedure",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
}, {
"url" : "concept",
"valueCodeableConcept" : {
"text" : "something"
}
}, {
"url" : "reference",
"valueReference" : {
"display" : "something"
}
}]
}],
"occurrenceDateTime" : "2024-01-01T01:01:01Z"
}
A complex data type in an sub-extension
This is how it appears in R6:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/patient-sexParameterForClinicalUse",
"extension" : [{
"url" : "value",
"valueCodeableConcept" : {
"coding" : [{
"system" : "http://terminology.hl7.org/CodeSystem/sex-parameter-for-clinical-use",
"code" : "specified"
}]
}
},{
"url" : "supportingInfo",
"valueCodeableReference" : {
"concept" : {
"text" : "Per Registration Questions"
},
"reference" : {
"display" : "DocumentReference/Something"
}
}
}]
}]
}
This is how the same data appears in R4 using a cross-version extension:
{
"resourceType" : "Patient",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/individual-genderIdentity",
"extension" : [{
"url" : "supportingInfo",
"extension" : [{
"url" : "_datatype",
"valueString" : "valueCodeableReference"
},{
"url" : "concept",
"valueReference" : {
"text" : "Per Registration Questions"
}
},{
"url" : "reference",
"valueReference" : {
"display" : "DocumentReference/Something"
}
}]
}]
}]
}
The situation with required elements is more complicated. This is when the data that is being represented using a cross-version extension is data for an element that is mandatory in the earlier version. The intent of the mandatory element is that proper data must be provided, but the desire is to provide a different form of data using a cross-version extension.
Implementers should note that wherever possible, the correct data should be provided. But in the case that this is not possible, this example shows how the cross-version extension should be used.
Here is the data in R6 format, a CodeableReference in a Task input parameter:
{
"resourceType" : "Task",
"status" : "draft",
"input" : [{
"type" : { "text" : "code-me-please" },
"valueCodeableReference" : {
"concept" : {
"text" : "Something"
}
}
}]
}
The representation of the cross-version extension is the same in R4, but there must also be
an actual Task.input.value that is valid in R4. This is done using the
Data Absent Reason extension:
{
"resourceType" : "Task",
"id" : "xver-task-r5",
"status" : "draft",
"input" : [{
"type" : { "text" : "code-me-please" },
"_valueBoolean" : {
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
"valueCode" : "unsupported"
}]
},
"extension" : [{
"url" : "http://hl7.org/fhir/5.0/StructureDefinition/extension-Task.input.value%5Bx%5D",
"extension" : [{
"url" : "_datatype",
"valueString" : "CodeableReference"
}, {
"url" : "concept",
"valueCodeableConcept": {
"text" : "Something"
}
}]
}]
}]
}
Implementer Notes:
code of unsupported can observe the presence of a cross-version extension to understand that the system that authored
the resource had the data available but not a supported way to represent in the earlier (or later) version.| Format: | R2 Package | R3 Package | R4 Package | |
| R2 Extensions: | n/a | hl7.fhir.extensions.r2:3.0.1  |
hl7.fhir.extensions.r2:4.0.1 |
hl7.fhir.extensions.r2:5.0.0 |
| R3 Extensions: | hl7.fhir.extensions.r3:1.0.2 |
n/a | hl7.fhir.extensions.r3:4.0.1 |
hl7.fhir.extensions.r3:5.0.0 |
| R4 Extensions: | hl7.fhir.extensions.r4:1.0.2 |
hl7.fhir.extensions.r4:3.0.1 |
n/a | hl7.fhir.extensions.r4:5.0.0 |
| R5 Extensions: | hl7.fhir.extensions.r4:1.0.2 |
hl7.fhir.extensions.r4:3.0.1 |
hl7.fhir.extensions.r4:4.0.1 |
n/a |
Note for balloters: the R5 packages will be created when R5 is finalized. Until then, these are broken links.
This specification is the result of three years of work by HL7, it's standards, government and implementation partners, along with the wider (huge) FHIR implementation community. The FHIR implementation community is now massive, and the pace of publication has slowed (as is evident in the publication history).
Accordingly, the pace of implementation adoption of new versions is slowing, and it is unclear how quickly R5 will be adopted. HL7 will watch the market and survey it's many partners before deciding how quickly to pursue the next release, and whether the next release will be a restricted branch development from R5 (as R4B was to R4), or whether it will forge ahead with a full new version, which will be Release 6.
Note that for this release, the extensions have been moved out into a separate module and updated
versions will be published regularly. See the
Extension Version Policy for further
information.
Irrespective of the choice around publication speed and whether to publish partial new branch versions, HL7's general intent for the Release 6 is to move most of the resources in the Foundation, Base and Clinical layers (see the 'Category' tab in the Resources pages) to full Normative status, along with a fwe other resources including e.g. Questionnaire.
Whatever HL7 decides to do with regard to the formal status of the resources, the next release will
include additional clarifications, resources, profiles and quality enhancements over the current release based on
implementation experience and ongoing development work. It will also incorporate fixes for issues raised with
the FHIR issue tracker . It may be useful for implementers
of this release to review the candidate current release (at http://build.fhir.org )
to get a sense of what changes are likely coming and perhaps to find more robust definitions and guidance than are
available in this release.
Some implementers who are dependent on content that exists in a draft release may choose to implement based on a particular snapshot of the development release, though in doing so, they will limit their potential communication partners. In addition, implementers should be aware that most of the implementation tooling including those provided by HL7 will not support interim versions other than the latest release.
More information on plans for Release 5 can be found on the HL7 product director's blog .
(Subscribing to this blog is a good way to keep current on significant events in FHIR development, including ballot and publication timelines.)
FHIR ®© HL7.org 2011+. FHIR R6 hl7.fhir.core#6.0.0-ballot2 generated on Mon, Nov 11, 2024 07:32+0000.
Links: Search |
Version History |
Contents |
Glossary |
QA |
Compare to R5 |
|
Propose a change