Compatibility - FHIR v1.8.0

STU3 Candidate

This page is part of the FHIR Specification (v1.8.0: STU 3 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R3 R2

7.2 Inter-version Compatibility

FHIR Infrastructure

Work Group

Maturity Level: N/A

Ballot Status: STU 3

The following rules will apply to resources, profiles and other content within the specification once those portions of the specification reach full normative status. These rules ensure that implementations may exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between applications using different versions of FHIR.

During the period of trial use of the specification (and once normative status is reached for elements that remain at draft or trial use status), changes may occur based on issues identified during early implementation of the specification. These changes do not need to adhere to the rules listed below.

7.2.1 Version identification

There is no explicit version marker in the resource content. FHIR adheres to the DICOM approach to versioning where content can safely be processed by instances independent of version. When dealing with STU-level content, applications may wish to use resource tags to help manage this during the period of trial use.

The conformance layer (CapabilityStatement and StructureDefinition) has mandatory properties declaring the FHIR specification version, and these may be used to determine which version of FHIR an implementation is using to aid in validation.

7.2.2 Change frequency

New versions of the FHIR specification will be produced regularly in accordance with the FHIR publication timeline. New versions of the specification will include additional draft and trial use content as well as promotion of previous trial use content to normative. Once content reaches normative, changes are expected to be infrequent. This is for two reasons:

The core specification focuses on those capabilities expected to be supported by most systems. For new capabilities to be introduced, it would need to be reflective of an overall change in the world-wide healthcare implementation environment.
If the implementation community has already consolidated around a standard approach to solving a FHIR implementation issue (e.g. using a particular extension), FHIR will not introduce confusion into the implementation community by defining a conflicting mechanism for solving that problem in the core specification.

7.2.3 Forward compatible behavior

In a typical scenario, mixed versions may need to exist, so applications SHOULD ignore elements that they do not recognize unless they are modifierExtensions. However, in a healthcare context, many application vendors are unwilling to consider this approach because of concerns about clinical risk or technical limitations in their software (e.g. schema based processing). Applications are not required to ignore unknown elements, but SHALL declare whether they will do so in their Capability Statements.

Unrecognized search criteria SHALL always be ignored. (Search criteria supported in a query are echoed as part of the search response so there is no risk in ignoring unexpected search criteria.)

Attempts to perform HTTP operations on unexpected URLs SHOULD be responded to with an appropriate error code.

7.2.4 Permitted changes for normative content

Category	Allowed changes
Elements	Once normative, subsequent versions of this specification may introduce new elements and/or content (e.g. XML attributes, etc.) at any location in the bundle, resource and/or data type structures. However, the names, path and meaning of previously existing data elements will not be changed. This includes 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. (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.
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	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 if the referenced code system(s) or value set(s) change. For non-immutable value sets: Value sets with an enumerated list of codes and having a 'fixed' binding may have additional codes introduced but will never have codes removed, though they may be deprecated. Value sets making use of filters may have filters loosened or tightened to accommodate changes to underlying code systems. StableDates and referenced code system and value set versions may be adjusted to point to newer versions. Definitions and display values for codes may change, but only in a manner that would not change the reasonable interpretation of data captured using the previous definitions or names. Abstract codes may be made concrete. Concrete codes will not be made abstract. For both immutable and non-immutable value sets, additional designations may be declared.
Terminology Bindings	Fixed bindings will remain fixed and will continue to point to the same value set. If the reference is version-specific, it will not change. Example bindings and preferred bindings may change to point to distinct value sets. Example bindings may be replaced with preferred bindings.
Data Types	Data types will not be removed or changed. New data types may be introduced. Types declared on existing elements will not be removed or changed. Additional data types may be added to elements which are already expressed as a choice of data types only if those elements are optional (minimum cardinality = 0).
Value Constraints	The allowed list of Data types will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed.
Flags	The Is Modifier and Is Summary flags will not be changed. The Must Support flag may be changed to true, but will not be removed.
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 (with the exception of correcting obvious errors).
Operations	New operations may be defined but operations may 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; e.g. Operation signatures cannot change; instead, additional operation variants will be defined.
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 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 data types 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.

Additional discussion on inter-versioning issues can be found here: http://wiki.hl7.org/index.php?title=FHIR_interversion_compatibility .