US Veterans Health Administration FHIR Map Set Implementation Guide
1.3.1 - 250401 United States of America flag

Publication Build: This will be filled in by the publication tooling

Index

Official URL: http://va.gov/fhir/ImplementationGuide/va.maps Version: 1.3.1
Active as of 2025-03-31 Computable Name: VAMapsIG

This implementation guide (IG) provides maps from Veterans Health Administration (VHA) data sources – primarily but not exclusively VistA – to Fast Healthcare Interoperability Resources (FHIR). The maps are asserted in the StructureDefinition resources that profile FHIR US Core R5 profiles, where available, and R4 core FHIR resources where no R5 US Core profile is defined.

Developers of FHIR interfaces for specific clinical purposes, whether they develop IGs or not, can use these maps to ensure that their assumptions about data equivalence are shared by other VHA stakeholders and partners.

It is anticipated that these maps may be specified more formally as StructureMap resources, but this will require consensus on representing VistA data as StructureDefinition files. Since clients to date have used a variety of interfaces to VistA (including Vx130 via CDW, VPR, VPR via VDIF, VIA, and HDR), it is not clear that this more strictly enforceable approach would actually support better governance.

Note: These maps are based on current analysis and review, and they are subject to future revision. The date of publication is in the page header. If you'd like to ask a question or provide feedback, you can do so here.

How to Read This Guide

If you wish to map VistA to FHIR, there are three ways to search this specification.

  1. If you are familiar with FHIR, or comfortable browsing, look for a profile with a name that matches your interest.
  2. Consult the Classes table for VistA file-to-FHIR Resource correspondences.
  3. Search "my term" site: {url}. This method will not work while the site is hosted at github.io.

The resource profile of interest will have a tab at the top of the page including the link "Mappings." This links to a page of all the mappings defined for the profile. Many of these mappings are inherited from the base specification, but the VistA mappings (and other VA-sources mappings, as available) will be found there.

Note that the publication tool infers that any mapped element is of interest. These elements are the ones that appear on the main page of the profile, even though the profile asserts no constraints on them.

The guide also contains concept maps for generating valid coded elements based on VistA content.

Other data sources may be added to this specification as needed.

If you find what you need, please let the VA FHIR Community of Practice know, so that we may understand how widely the maps are being used, and so that we may notify you if any changes are contemplated at the enterprise level.

How to Improve This Guide

If you do not find what you need, please contact the VA FHIR Community of Practice for assistance in creating new maps that will support your use case. If you have already created maps, please let us know so that we can publicize your work and encourage consensus.

If you identify a problem or issue with this guide, feel free to log a ticket with the Community of Practice LEAF.

Methods used

The VistA data dictionary has over 70,000 entries, so we are not able to map all fields. Map creation is driven by business need. Most cases to date have involved mapping to commonly understood elements outside the enterprise, so the elements required or constrained in the US Core IG have been the first priority.

For more information on the mapping process and design assumptions, see Design Guidance.

For more information on engaging with the CoP team, see Process Guidance.

Dependencies

Package hl7.fhir.uv.extensions.r4#5.2.0

This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Mon, Feb 10, 2025 21:45+1100+11:00)

Package hl7.fhir.uv.bulkdata#2.0.0

FHIR based approach for exporting large data sets from a FHIR server to a client application (built Fri, Nov 26, 2021 05:56+1100+11:00)

Package hl7.fhir.uv.sdc#3.0.0

The SDC specification provides an infrastructure to standardize the capture and expanded use of patient-level data collected within an EHR.
This includes two components:
* Support more sophisticated questionnaire/form use-cases such as those needed for research, oncology, pathology and other clinical domains.
*Support pre-population and auto-population of EHR data into forms/questionnaires for uses outside direct clinical care (patient safety, adverse event reporting, public health reporting, etc.). (built Tue, Mar 8, 2022 18:36+0000+00:00)

Package hl7.fhir.us.core#5.0.1

The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Common Clinical Data Set (CCDS), and ONC U.S. Core Data for Interoperability (USCDI) v1 provided the requirements for this guide. The prior Argonaut search and vocabulary requirements, based on FHIR DSTU2, are updated in this guide to support FHIR Version R4. This guide was used as the basis for further testing and guidance by the Argonaut Project Team to provide additional content and guidance specific to Data Query Access for purpose of ONC Certification testing. These profiles are the foundation for future US Realm FHIR implementation guides. In addition to Argonaut, they are used by DAF-Research, QI-Core, and CIMI. Under the guidance of HL7 and the HL7 US Realm Steering Committee, the content will expand in future versions to meet the needs specific to the US Realm. These requirements were originally developed, balloted, and published in FHIR DSTU2 as part of the Office of the National Coordinator for Health Information Technology (ONC) sponsored Data Access Framework (DAF) project. For more information on how DAF became US Core see the US Core change notes. (built Wed, Jun 22, 2022 19:44+0000+00:00)

Package hl7.fhir.us.davinci-pdex-plan-net#1.1.0

Davinci PDEX Plan Net (built Mon, Apr 4, 2022 14:01+0000+00:00)

US Core 6.1.0 and 7.0.0 Compliancy

This implementation guide is build against US Core 5.0.1 and automatically validated against US Core 6.1.0 and US Core 7.0.0. All Profiles that have the US Core profile as base are marked "compliedWithProfile" when there are no issues detected by the FHIR validator.

This is visible in the "Formal Views of Profile Content"-section under description on every profile that is compliant. For example for the Allergy Intolerance Use Case Profile:

This profile also complies with the profile US Core AllergyIntolerance Profile (6.1.0)"

Known US Core 6.1.0 Differences and Solutions

  • US Core 6.1.0 has profile for Specimen now (us-core-specimen)
    • solution: in LabObservation use-case change Specimen base to us-core-specimen
  • US Core 6.1.0 merged us-core-observation-clinical-test and us-core-observation-imaging to us-core-observation-clinical-result
    • solution: in LungCancerScreening use-case change base to us-core-observation-clinical-result
    • solution: in ObservationImagingResult use-case change base to us-core-observation-clinical-result
  • US Core 6.1.0 renamed slice to "uscore" instead of "us-core"
    • solution: in DocumentReference use-case change slicename to "uscore"
  • US Core 6.1.0 fixed SpO2 cardinality issue (force to 2..* in our profile)
    • workaround in VitalSignsSpO2 use-case no longer needed

Cross Version Analysis

This is an R4 IG. None of the features it uses are changed in R4B, so it can be used as is with R4B systems. Packages for both R4 (va.maps.r4) and R4B (va.maps.r4b) are available.