This page is part of FHIR DSTU 2 (v1.0.2) in it's permanent home (it will always be available at this URL). It has been superceded by R4. For a full list of available versions, see the Directory of published versions .. Page versions: R5 R4B R4 R3 R2

See below for version history details.

1.5 Version History

This is the developmental version of FHIR. The only changes tracked here are the changes made after the publication of the first DSTU release. For earlier changes, see the DSTU #1 Version History . Note that a full archive history of everything is available through the HL7 gForge SVN archives .

1.5.1 How FHIR Versioning works

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, 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 extremely minimal).

The following kinds of changes may be made to the specification:

  • Non-substantive changes do not cause changes in any conformant application. For example, section renumbering, broken links, style corrections, typos, and clarifications that do not change the meaning. Some corrections may be judged not to create any expectation of change to a conformant application.
  • Substantive changes that are not breaking. These introduce new functionality - changes to the specification that create new capabilities - but would not render existing applications non-conformant if they do not change.
  • Breaking changes would mean that previously conformant applications are no longer conformant

Note that the following are, by definition, considered non-breaking changes, even though some implementations (including the reference implementations) may not be able to handle some consequences of these changes without error:

  • creation of new resources
  • adding new elements in an existing resource
  • defining new data types
  • Adding new API operations

Also, the examples are never substantive. Every effort is made to ensure that FHIR examples are correct, but changes to the examples in the specification are not considered substantive.

Each FHIR version is identified by a string composed from 4 parts: publication.major.minor.revision.

  • Incremented when HL7 publishes FHIR as an updated specification, e.g. a DSTU or normative version of FHIR
  • HL7 plans to do this every 1 to 2 years
  • The first DSTU was version 0
  • Increments every time a breaking change is made
  • When a new publication is made, this is reset to 0 in the publication, and 1 in the development branch
  • Since HL7 does not make breaking changes as technical corrections to a published specification, these versions of FHIR always have a version number X.0.n.r
  • Because the development version is the subject of ongoing analysis, debate, ballot and repeated alterations, breaking changes are to be expected
  • Increments every time a substantive change is made
  • Resets to 0 any time the major version changes
  • Incremented any time a change is made to the specification
  • At present, this is the SVN version number (this allows anyone to reconstruct the source from which the version was built)

Additional notes:

  • Changes to a formally published specification (except for minor publishing corrections, such as correcting broken links) are only made via announced technical corrections
  • The reference implementations have 2 versions - the version of the specification that they implement, and their own version. Consult the reference implementation documentation for policy regarding this version number
  • The specification published by the continuous integration service (http://build.fhir.org/ ) build may not conform to this version policy, but the versions published on the HL7 web site will (see Directory of published versions )
  • The first DSTU was published prior to these rules being agreed as v0.80-2286. This has been updated to as a technical correction to align with this policy on 9-May 2014

1.5.2 Version History since DSTU #1

This table lists substantive changes only.

Version Changes

Security Note, May 15, 2015

New security note about risks associated with XML Entities


Technical Correction 1, Oct 24 2015

A series of technical corrections to the specification following extensive review:

  • Corrections to Extension cardinalities in implementation guides
  • Corrections in the conformance resources that support the specifications
  • Correct several erroneous invariants
  • Various typos, broken links, and fixes in examples
  • For a comprehensive list of corrections, see the Task list for FHIR DSTU2 Technical Correction 1

DSTU 2, Sept 23 2015

Changes of significance during the QA process:

  • Remove the Clinical Quality Improvement Framework (CQIF) from this published version
  • made fixes to generated schematrons
  • updated generated comformance resources (StructureDefinitions and SearchParameters) so they were consistent with the specification
  • Many spelling / grammar / broken link fixes

DSTU 2 QA Preview, Aug 31 2015

This version had extensive change as a result of the May 2015 DSTU ballot, ongoing testing, and the open change proposals (1317 gForge tasks). The extent of the changes is best illustrated by the number of the list of changes labelled 'breaking change' - 158 changes of 1317 total tasks. Below is a list of the most important changes:


DSTU Ballot, May 2015

This version had extensive change as a result of the January 2015 Draft ballot, ongoing testing, and the open change proposals (over 800 gForge tasks). The list below is a summary of the major changes to resource content. It shows only a limited number of the overall changes.


  • All spaces removed
  • Extensive content changes not noted here

New Data Types

Changed Data Types

  • Coding - remove valueSet
  • Attachment - add creation
  • Identifier - replace label with type
  • Timing - major rework of content
  • ElementDefinition - add label, code, rename 'formal' to definition, rename synonym to alias, add language to mapping, remove conformance and isExtensible and replace with strength

New Resources

Removed Resources

  • CarePlan2 -> collapsed into CarePlan
  • FamilyHistory -> broken up into FamilyMemberHistory
  • InstitutionalClaim, OralHealthClaim, PharmacyClaim, ProfessionalClaim, VisionClaim -> collapsed into Claim
  • Other - use Basic instead
  • PendedRequest,Readjudicate, Reversal, StatusRequest, StatusResponse - use ProcessRequest/Response instead
  • SupportingDocumentation - use DocumentManifest instead

Renamed Resources

  • Alert -> Flag: 'alert' made people think it was an action like an alarm
  • SecurityEvent -> AuditEvent: it wasn't just for security purposes
  • ClinicalAssessment -> ClinicalImpression: people got confused with 'assessment' tools like APGAR score
  • Profile -> StructureDefinition: 'Profile' is the process, a package of statements

Changes Inside Resources

  • Parameters - allow parameter.part to contain a resource
  • AllergyIntolerance - rename subject to patient
  • Appointment - remove lastModifiedBy/lastModified, add location
  • AppointmentResponse - remove lastModifiedBy/lastModified, add rename individual to actor
  • AuditEvent - add .event.purposeOfEvent, participant.location, .policy, and .purposeOfUse
  • Bundle - major reorganization
  • CarePlan - pull goal out + other reorganization
  • ClinicalImpression - add status, replace careplan & referral with trigger, rename diagnosis to finding, make plan 0..*,
  • Composition - change .section.content to refer to List only, not any
  • ConceptMap - change identifier to url, add useContext, change telecom to contact,
  • Condition - rename subject to patient, rename status to clinicalStatus, change to bodySite = code or Reference(BodySite), rename .codeableConcept to .code
  • Conformance - change identifier to url, add useContext, change telecom to contact, add requirements and copyright, add support for conditional operations,
  • Contract - extensive rewrite
  • Coverage - add bin, subscriberId
  • DataElement - total rewrite to use ElementDefinition
  • Device - add status, manufactureDate
  • DeviceMetric - rename operationalState to operationalStatus, add measurementMode, rename calibrationInfo to calibration, change color to an enumerations
  • DeviceUseRequest/DeviceUseStatement - change to bodySite = code or Reference(BodySite)
  • DiagnosticOrder - change to bodySite = code or Reference(BodySite)
  • DiagnosticReport - add encounter
  • DocumentManifest - add options for how content is referred to
  • DocumentReference - add format, remove policyManager, make content : Attachment, and remove several related attributes, remove service reference and add context.practiceSetting, sourcePatientInfo, and related
  • Encounter - add incomingReferralRequest, allow reason to repeat, rename diet to dietPreference
  • EpisodeOfCare - rename currentStatus to status, allow referralRequest to repeat,
  • Flag - rename subject to patient, change from note to code
  • Goal - add targetDate, statusDate, author, priority
  • HealthcareService - extensive rewrite
  • ImagingObjectSelection - remove retrieveAETitle, rename retrieveUrl to url, add frames
  • ImagingStudy - add laterality, change url to attachment
  • Immunization - add encounter, rename subject to patient, rename refusedIndicator to wasNotGiven, rename refusalReason to reasonNotGiven
  • ImmunizationRecommendation - rename subject to patient
  • List - add title, status, change ordered to orderedBy, add note
  • Location - remove status
  • Media - remove created (-> Attachment)
  • Medication - add batch
  • MedicationAdministration - add reasonGiven, note, text. remove timing & maxDosePerPeriod
  • MedicationDispense - collapse to a single dispense, add daysSupply, note and substitution, change quantity to allow range
  • MedicationOrder - add note, change quantity to allow range,
  • MedicationStatement - add informationSource, status, dateAsserted, replace whenGiven with effective[x], remove device, add dosage.text
  • NamingSystem - add date, publisher,
  • NutritionOrder - extensive rewrite
  • Observation - change name to code, allow more types of value[x], change type of dataAbsentReason, change to bodySite = code or Reference(BodySite), allow identifier to repeat, add device,
  • OperationDefinition - change identifier to url, add useContext, change telecom to contact, change name to title, add reuqirements, idempotent,
  • OperationOutcome - change type of .issue.type
  • OrderResponse - rename code to orderStatus
  • Organization - remove location and contact.gender
  • Patient - communication to allow 'preferred'
  • Person - rename other to target
  • Practitioner - change type of birthDate, allow multiple roles per practitioner
  • Procedure - add status and category, change to bodySite = code or Reference(BodySite), allow date to be period too, add location, change followUp to code 0..*, add device tracking
  • ProcedureRequest - change to bodySite = code or Reference(BodySite)
  • Provenance - change integritySignature to signature & make it a type, allow reference by Reference as well as URI
  • Questionnaire - add telecom
  • Schedule - move lastModified
  • SearchParameter - change telecom to contact, add status, experimental, date,
  • Slot - move lastModified
  • Specimen - change source to parent, change to bodySite = code or Reference(BodySite)
  • StructureDefinition - complete rewrite
  • Subscription - change type of tag, reanme url to endPoint,
  • ValueSet - change identifier to url, add useContext, change telecom to contact, replace purpose with useContext, add requirements, rename stableDate to lockedDate, change type of expansion.identifier, add expansion parameters

Draft For Comment, January 2015 Ballot

Breaking Changes (full list):

  • Replace atom and taglist with a native Bundle format (3728 , 3558 , 2889 ) (and also Binary)
  • JSON: change how extensions are represented (3471 )
  • RESTful API: change how version specific upgrades work (3451 )
  • DataTypes:
  • Rename Schedule to Timing (3536 , 3236 )
  • Rename Contact to ContactPoint (3533 ) and swap order of elements (3108 ))
  • Address - change zip to postCode (2888 )
  • Quantity: Correct schema spelling for "QuantityCompararator" (3531 )
  • Change allowable values for the id type to include capital letters, and allow up to 64 chars (3750 )
  • Restructure Profile - only one structure, and pull ExtensionDefinition out of Profile (3647, 3498), and pull SearchParameter out (3626 )
  • Profile: allow 0..* discriminator (3131 ), and change the way discriminators work across resource boundaries (3124 ) + generate multiple types properly (2856 )
  • remove _validate interaction, and replace with $validate operation (3686 )
  • Patient: separate birth time from birthDate (3731 ), Change Administrative Gender from a CodableConcept to a Code. Also fixed the values as male|female|other|unknown with mappings to v2 and v3 (3070 )
  • DocumentReference: change encoding of Hash to Base64 (3291 )
  • Group: rename header to title (3126 )
  • Condition: split relatedItem into two (3111 )
  • Questionnaire: drop questionnaire.group.question.remarks (3255 ) and move omitReason from extension to base resource (3260 )
  • QuestionnaireResponse: allow multiple answers (3146 )
  • ValueSet: replace ValueSet.compose.include.code with ValueSet.compose.include.concept (3258 ), added new rules about expansion content (3138 )
  • Media: Rename element 'dateTime' to 'created' (3174 ) and length to duration (2866 )
  • Remove DeviceObservationReport and Query
  • Collapse AdverseReaction into AllergyIntolerance
  • Appointment changes - individual field renamed to actor, and added mappings to HL7 v2 and HL7 v3
  • FamilyMemberHistory combined with List replaces FamilyHistory (with corresponding updates to related profiles)
  • Flag replaces Alert including improved clarification of how it is used and replacement of "note" with "code"
  • CarePlan significantly refactored including splitting Goal out as a distinct resource, moving elements between activity and detail, introduction of several new elements and supported relationship types

New Resources:

New Implementation Guides (see discussion of status)

  • Minor new optional elements on value set for metadata, new extensions for all the rest of the VSD project metadata, formal profile to express basic minimum metadata for value set
  • Namespace: adjustments based on Grahame's feedback

Note: a useful tool for displaying the differences between pages is the W3C HTML Diff engine .