This page is part of the US Core (v3.1.0: STU3) based on FHIR R4. The current version which supercedes this version is 5.0.1. For a full list of available versions, see the Directory of published versions
DSTU2 to R4 Conversion
- Introduction
- Endpoint Discoverability
- No Guarantee that Resource IDs are Preserved
- Expectation that DSTU2 Data is Preserved in R4
- Authorization Across Versions
Introduction
There are several consideration for the user and developer experience when transitioning from FHIR DSTU2 to FHIR R4. To ensure a smoother upgrade path the following the guidance is provided.
Endpoint Discoverability
A server may make explicit which version of Argo/US Core on their FHIR endpoint (e.g., “DSTU2” or “R4” path component or separate files based on version). However best practice is to inspect the endpoint metadata on each endpoint to discover the information about a server’s capabilities including the FHIR version and the US Core Profile version that is supported:
GET [base]/metadata{?mode=[mode]} {&_format=[mime-type]}
No Guarantee that Resource IDs are Preserved
In some FHIR servers the identifier of the underlying clinical data is not maintained across FHIR versions. Client applications must plan on deduplication methods that don’t rely on a common identifier across FHIR versions.
- Servers SHOULD maintain a stable common identifier for a resource across versions.
Expectation that DSTU2 Data is Preserved in R4
In an upgraded R4 endpoint any data in DSTU2 should be in R4. However, not all data in R4 may be available in DSTU2 because some profiles and data classes like Clinical Notes and pediatric observations are not part of DSTU2.
- The FHIR RESTful resource types supported in a DSTU2 implementation SHALL be supported in a R4 implementation
- Exceptions
- MedicationStatement MAY be deprecated and the data SHALL be mapped to MedicationRequest.
- See the Medication List Guidance section for guidance on accessing a patient’s medications
- care teams as represented by CarePlan in DSTU2 SHALL be replaced by and the data mapped to CareTeam in R4
- MedicationStatement MAY be deprecated and the data SHALL be mapped to MedicationRequest.
- Exceptions
- Servers SHALL make available the same information in DSTU2 and R4 where the more recent standard allows. (e.g., patient Rhonda Jones is available on both)
- Exceptions
- MedicationStatement data mapped to MedicationRequest
- care teams as represented by CarePlan SHALL be mapped to CareTeam in R4
- Exceptions
- Data SHALL not be degraded between versions.
Authorization Across Versions
- Separate authorization is required
- There is no expectation that DSTU2 authorizations will work on R4 endpoints and reauthorization is required when migrating between versions.
- Maintaining the same auth server for both endpoints so that the refresh token is valid for both DSTU2 the R4 endpoint as well may be possible but not in scope.
- There is no expectation that DSTU2 authorizations will work on R4 endpoints and reauthorization is required when migrating between versions.
-
The new endpoint will bring additional/changed resource types and added scopes
The table below summarizes the different profiles and resource types between DSTU2 and R4:
DSTU2 Profile | Equivalent R4 Profile | Notes |
---|---|---|
Argonaut AllergyIntolerance Profile | US Core AllergyIntolerance Profile | |
Argonaut CarePlan Profile | US Core CarePlan Profile | Resource type changed from CarePlan in DSTU2 to CareTeam in R4 |
Argonaut CareTeam Profile | US Core CareTeam Profile | |
Argonaut Condition Profile | US Core Condition Profile | |
Argonaut Device Profile | US Core Implantable Device Profile | |
Argonaut DiagnosticReport Profile | US Core DiagnosticReport Profile for Laboratory Results Reporting | |
Argonaut DocumentReference Profile | US Core DocumentReference Profile | |
Argonaut Goal Profile | US Core Goal Profile | |
Argonaut Immunization Profile | US Core Immunization Profile | |
Argonaut Medication Profile | US Core Medication Profile | |
Argonaut MedicationOrder Profile | US Core MedicationRequest Profile | |
Argonaut MedicationStatement Profile | US Core MedicationStatement Profile not defined in R4, Map DSTU2 data to MedicationRequest | |
Argonaut Observation Results Profile | US Core Laboratory Result Observation Profile | |
Argonaut Patient Profile | US Core Patient Profile | |
Argonaut Procedure Profile | US Core Procedure Profile | |
Argonaut Smoking Status Observation Profile | US Core Smoking Status Observation Profile | |
Argonaut Vital Signs Observation Profile | FHIR Vital Signs Profile | The FHIR Vital Signs Profile is published in the FHIR specification |
- | US Core DiagnosticReport Profile for Report and Note exchange | New Profile in R4 |
- | US Core Encounter Profile | New Profile in R4 |
- | US Core Location Profile | New Profile in R4 |
- | US Core Organization Profile | New Profile in R4 |
- | US Core Pediatric BMI for Age Observation Profile | New Profile in R4 based on the FHIR Vital Signs Profile |
- | US Core Pediatric Weight for Height Observation Profile | New Profile in R4 based on the FHIR Vital Signs Profile |
- | US Core Practitioner Profile | New Profile in R4 |
- | US Core PractitionerRole Profile | New Profile in R4 |
- | US Core Provenance Profile | New Profile in R4 |
- | US Core Pulse Oximetry Profile | New Profile in R4 based on the FHIR Vital Signs Profile |