Page tree
Skip to end of metadata
Go to start of metadata


  1. Join us in our next virtual connectathon from September 9-11, 2020. Details can be found here.
    1. To view our upcoming connectathon schedule, click here. 
  2. Click here to view the SDOH-CC Master and Temporary Code List.


The Gravity Project creates and maintains a consensus-building community to expand available Core Social Determinant of Health (SDOH) Data for Interoperability and accelerate standards-based information exchange by using HL7 FHIR. Gravity Project is part of the HL7 FHIR Accelerator Program.

Many of the recent innovations at scale in this area begin with the strategic collection of SDOH data. As examples, the Centers for Medicare & Medicaid Services Innovation Center (CMS Innovation Center) Comprehensive Primary Care Plus Model requires providers to assess patients’ social risks; and the CMS Innovation Center’s Accountable Health Communities Model developed a social risk assessment tool to help identify and address social risks across clinical and community-based settings. However, presently there is no consensus on the coding and standards-based modeling to facilitate the data uses envisioned for SDOH information. The Gravity Project is addressing the question of how to record and document SDOH information in the clinical care setting, across the four primary activities of care (screening, assessment/diagnosis, care planning, and treatment). Initially, the project focuses on three of the many different domains that form social determinants of health: Food Insecurity, Housing Instability and Quality, and Transportation Access.

The FHIR IG work for Gravity will include several iterative builds of the SDOH-CC IG, multiple rounds of Connectathon testing, and periodic updates to summarize this work for the Community. General education about FHIR IG development and HL7 ballot participation will be provided to build awareness and develop skills relevant for participation in standards development at the Community level.

Upcoming FHIR IG Meetings

DateTimeTopicWebinar Information

If you missed any FHIR IG meetings, click here for past meeting minutes.

Quick Links

Implementation GuidesSponsoring Work GroupsGovernance DocumentsConnectathon InformationPotential Connectathon ParticipantsBallot InformationReference ImplementationsTesting and Validation Tools

SDOHCC Master and Temporary Code List v0.0.3

Approved SDOHCC FHIR IG Build Errors/Warnings


Patient Care



Public Health

Status: Approved 2019.11.18

FHIR IG Proposal: Proposal 

Status: Approved 2019.10.30

Sydney 2020 HL7 Connectathon 23

Sydney, Australia


May 2020 HL7 Connectathon 24


May 2020 MiHIN Interopathon


Sept 2020 HL7 Connectathon 25 - Virtual 2020.09.9-11

Ballot for STU: 2020.09

Git Hub TBD

Interventions Framework

Form Creator Demonstration

If you have any questions, please contact Gravity Technical Director, Robert Dieterle at

Project Scope Statement

For details on the approved scope for the Gravity Project SDOH Data Element FHIR IG, read the HL7 PSS.

Project Insight Number: 1567

Project Deliverables

The Gravity Project will incrementally develop one (1) FHIR IG covering the following three primary use cases listed in the table below.  The three SDOH domains these use cases focus on are as follows:

  • Food Insecurity (In-progress)
  • Housing Instability and Quality
  • Transportation Access

Use Cases

1) Document SDOH Data Elements in the Clinical Care Setting

Document SDOH data in conjunction with the patient encounter.

2) Track SDOH Intervention Referrals to Completion

Document and track SDOH related intervention referrals to completion.

3) Aggregate SDOH Data Elements for Secondary Use (QRPH)

Gather and aggregate SDOH data for uses beyond the point of care (e.g.,quality, research, and population/public health)

Note: Out of Scope for the 2020 SDOH-CC FHIR IG.

Click here to download the Gravity Use Case Package

Roadmap Timelines (updated 2020.05.04)

Milestones (updated 2020.05.26)

TaskWorkStreamOverview of FHIR IG Development Workstream ActivitiesStart DateTarget DateStatusCompletion Date
51Work Stream 1 (Community Engagement) comprises three main aspects of work:
- Participation in PMO activities
- Support for Gravity Community and Content Domain activities
- HL7 WG Community Support and Project Governance
52Work Stream 2 (Connectathon Testing) comprises three main aspects of work:
- Planning for Connectathons
- Support for Testing Participants
- Participation in Connectathon Events

53Work Stream 3 (FHIR IG) comprises three main aspects of work: FHIR IG Dev2020.01.012020.08.01In Progress
53Work Stream 3 (FHIR IG) comprises three main aspects of work: Ballot Reconciliation and Execution of Ballot Changes2020.08.012020.12.31

53Development of Reference Implementation2020.10.012020.12.31

Task WorkStream 1DetailsStart DateTarget DateStatusCompletion Date
51Project Scope Statement2019.10.042019.11.18Completed2019.11.18
51FHIR IG Proposal2019.10.172019.10.30Completed2019.10.30
51Develop Base IG and Profiles for UC1v1 (IGV0.0.1)
Initial pass at key SDOH-specific profiles for UC1.

51Gravity Community Feedback
51Overview of FHIR IG Development in Gravity Community Meeting
51Review initial Community Feedback
51Project briefing for Patient Care
51Project briefing for Vocabulary WG
51Project briefing for Public Health WG
51HIMSS SDOH Presentations
51Overview of FHIR IG Development in Gravity Community Meeting
51Sydney Connectathon Report out
51Project briefing for Patient Care
51Project briefing for Vocabulary WG
51Project briefing for Public Health WG
51May 2020 HL7 Connectathon Track Plan
51May 2020 HL7 Connectathon Report to Gravity Community
2020.06In progress
51Project briefing for Patient Care WG
2020.06In progress
51Project briefing for Vocabulary WG
2020.06In progress
51Project briefing for Public Health WG
2020.06In progress
51Governance WS: NIB for Sept Ballot must be completed

51Approval to ballot from Patient Care Workgroup


Marketing/Education WS: Overview of FHIR IG Development in Gravity Community Meeting


51Sept 2020 HL7 Connectathon Track Plan

51Project briefing for Patient Care

51Sept 2020 HL7 Connectathon Report to Gravity Community

51Sept 2020 Analysis of Ballot Comments

51Project briefing for Vocabulary WG

51Project briefing for Public Health WG

51Work on Ballot Comments2020.09.012020.11.30

51Approval of Ballot Reconciliation Amalgamated Sheet2020.09.012020.11.30

51Approval of Request to Publish STU R1 from Patient Care Workgroup

TaskWorkStream 2DetailsStart DateTarget DateStatusCompletion Date
52Generate SDOH Track Proposal and prepare track participants (Sydney)
52HL7 Connectathon 23 - Sydney, Australia2020.02.022020.02.03Completed2020.02.04
52Connectathon Participants Preparation Call
52Connectathon Participants Preparation Call
52Connectathon Participants Preparation Call
52Connectathon Participants Preparation Call

Generate SDOH Track Proposal and prepare track participants for San Antonio, TX Connectathon

52Connectathon Participants Preparation Call
52Connectathon Participants Preparation Call
52HL7 Connectathon 24 - Virtual2020.05.132020.05.15Completed
52MiHIN Interopathon - Virtual2020.05.282020.05.29In progress
72Create Recommendations to inform the development and piloting of the AHRQ/NIDDKE eCare Plan app and associated FHIR IG2020.032020.06.05In progress
52Generate SDOH Track Proposal and prepare track participants for Baltimore, MD Connectathon2020.07

52Connectathon Participants Preparation Call2020.07

52Connectathon Participants Preparation Call2020.08

52Connectathon Participants Preparation Call2020.08

52HL7 Connectathon 25 - Baltimore, MD2020.09

TaskWorkStream 3DetailsStart DateTarget DateStatusCompletion Date
53IG Development: Continued IG Development UC1v2 (IGV0.0.2))

Refinement of V0.0.1 with emerging content ready enough for early testing at Sydney Connectathon
53IG Development: Continued IG Development UC1v3 (IGV0.0.3)

Improvements on V0.0.2 based on learning from Sydney Connectathon and additional profiles and guidance that continues to be developed.
53IG Development: Continued IG Development UC1v4, UC2v1 (IGV0.0.4)

First version that includes profiles and guidance regarding use of BSeR for UC2

FHIR IG Scope change to focus solely on Resource content profiles. Specifying data exchange mechanisms between actors removed from scope.

53Continued IG Development UC1v5, and UC2v2 (IGV0.0.5)

Improvements on V0.0.4 based on learning from Connectathon 24 and additional profiles and guidance that continues to be developed.
2020.05.012020.07.30In progress
53Ballot Package Prep (IGV5), WG Review and Voting2020.06.012020.07.30

53Sponsor WG approves FHIR IG content submitted to ballot2020.08.01

53FHIR IG content determined is included in September HL7 Ballot V0.1.02020.08.13

53September HL7 Ballot

Community reviews and submits formal comments on V0.1.0

53Improvements on V0.1.1 based on learning from Baltimore Connectathon and additional profiles and guidance that continues to be developed.2020.09

53Ballot Reconciliation2020.12

53FHIR IG with Ballot dispositions applied. (v1.0.2 - v1.0.n)2020.12

53Publish SDOH-CC STU1 V1.0.0 for Food Insecurity2020.12

53Develop FHIR Reference Implementation

Out of ScopeOut of ScopeSubsequent iterations for Housing Instability and Quality (STU R2)TBD

Out of ScopeOut of ScopeSubsequent Iterations for Transportation Barriers (STU R3)TBD

View HL7 2020 Balloting and Publishing Schedule

FHIR R4 Implementation Guide and Artifacts

 (updated 2020.05.07)

Implementation Guide Narrative ExplanationsXX
Patient Stories and Persona InformationXX
Use Case DocumentationXX

Use Case 1Use Case 2
Resources, Profiles, Operations, Examples, Validation ScriptsScreeningEncounterRequestResponse
US Core PatientXXXX
US Core PractitionerXXXX
US Core PractitionerRoleXXXX

US Core Organization

US Core Location XXXX
US Core Encounter for a patient visit/encounter

$process-message operation for screening Task


MessageBundle for screening task


MessageHeader for screening taskremovedremoved

Task for screening taskremovedremoved

CDex CommunicationRequestremovedremoved

CDex Communicationremovedremoved

MessageHeader for update screening taskremovedremoved

SDC QuestionnaireXX

SDOH-CC List of Patients for screening task


SDOH-CC Consent for sharing questionnaire response informationXX

SDC QuestionnaireResponseXX

US Core Observation for Screening Result


Document Bundle for encounter summary and care plan documents or referral note and referral feedback documentsremovedremoved

C-CDA on FHIR Composition for encounter summary and care plan documents or referral note and referral feedback documentsremovedremoved

DocumentReference for keeping track of received documentsremovedremoved

Binary for holding a copy of a received documentremovedremoved

SDOH-CC Observation for food insecurity clinical observation

SDOH-CC Condition for food insecurity diagnosis

SDOH-CC Goal for food insecurity goal

SDOH-CC Procedure for food insecurity services (performed and requested)

SDOH-CC ServiceRequest to do a referral (ServiceRequest) for services to address SDOH needs 

SDOH-CC CarePlan to show how SDOH information relates to each other
Description only

CDex MessageBundle for Communications

CDex MessageHeader for solicited communication request

CDex MessageHeader for solicited communication response

BSer $process-message operation for SDOH Referral Task


BSer MessageBundle for SDOH Referral Task

BSer MessageHeader for SDOH Initiate Referral Task


BSer MessageHeader for SDOH Update Referral Task

BSeR ServiceRequest Activity Status

Clinical Statements -  multiple Profiles that describe how to represent individual data elements used in referral note and referral feedback documents


CapabilityStatement - Patient Appremovedremoved

CapabilityStatement - Screening Appremovedremoved

CapabilityStatement - Screening Requesterremovedremoved

CapabilityStatement - Clinical Data Sourceremovedremoved

CapabilityStatement - Clinical Data Requesterremovedremoved

CapabilityStatement - Referral Requester

CapabilityStatement - Referral Responder

CapabilityStatement - Services Directory

Resource Instance ExamplesXXXX
Messaging ExamplesInformative examples on Confluence onlyInformative examples on Confluence onlyInformative examples on Confluence onlyInformative examples on Confluence only
Validation Scriptsremovedremoved * Due to CDex changingremovedremoved

Approved SDOHCC FHIR IG Errors and Warnings

IG versionError/WarningNotes
v0.0.1N/AEarly efforts are not complete enough to expect error-free builds with IG Publisher.
v0.0.2N/AEarly efforts are not complete enough to expect error-free builds with IG Publisher.
v0.0.3Current unresolved Build Errors for v0.0.3First version where expectation is an error-free build with IG Publisher. 199 total errors. 181 errors are approved at this time. 18 errors need to be resolved

Slicing Information

error-The link '' for "Table of Contents" cannot be resolved17 errors

error- The link '' for "" cannot be resolved148 errors 

error- The link 'Patient/patientExample1' for "Patient/patientExample1" cannot be resolved5 errors

error- The link 'Encounter/encounterExample1' for "Encounter/encounterExample1" cannot be resolved.

error- The link 'Encounter/encounterExample2' for "Encounter/encounterExample2" cannot be resolved

The link 'Encounter/encounterExample3' for "Encounter/encounterExample3" cannot be resolved

4 errors

error- The link 'Practitioner/practitionerExample1' for "Practitioner/practitionerExample1" cannot be resolved

The link 'Practitioner/practitionerExample2' for "Practitioner/practitionerExample2" cannot be resolved

3 errors

The link 'StructureDefinition-SDOHCC-Procedure-FoodInsecurity-1.sch' for "Schematron" cannot be resolved4 errors
v0.0.4StructureDefinition.baseDefinition warning US FHIR Usage rules require that all profiles on CarePlan derive from the core US profile

The link 'StructureDefinition-SDOHCC-Procedure-FoodInsecurity-1.sch' for "Schematron" cannot be resolved

The link 'StructureDefinition-SDOHCC-Observation-FoodInsecurity-1.sch' for "Schematron" cannot be resolved

The link 'StructureDefinition-SDOHCC-Goal-FoodInsecurity-1.sch' for "Schematron" cannot be resolved

The link 'StructureDefinition-SDOHCC-Condition-FoodInsecurity-1.sch' for "Schematron" cannot be resolved

The resource should declare it's jurisdiction to match the package id (, jurisdiction = urn:iso:std:iso:3166:-2#US)

Other IGs to be Utilized

Implementation GuideDescription and intended use (Note that many extensions are defined within these IGs)


Version (3.1.0) - FHIR R4

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 the latest proposed ONC U.S. Core Data for Interoperability (USCDI) 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. 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.


Version 2.1 - widely adopted standard for exchange of patient encounter information.

Consolidated CDA (C-CDA) specifies several relevant document types used currently by EHR systems to exchange clinical encounter information. These documents express a collection of information that tells the patient's story at a point in time when an encounter occurred or provides the patient's medical history over a span of time.  The documents are expressed using the HL7 Clinical Document Architecture standard which is compatible and can be used in conjunction with FHIR.  For systems that do not yet support FHIR document creation, exchange of patient data using C-CDA standard documents may be a viable option. C-CDA document can be shared as attachments within FHIR exchange mechanisms.  FHIR also supports robust document registry and repository capabilities appropriate for exchanging information in all types of document formats.

Structured Data Capture (SDC)

Version  for FHIR R4

Questionnaires and forms permeate healthcare. They are used to capture administrative data, claims data, clinical information, research information, for public health reporting - every type of data that is manipulated by healthcare systems. They provide a user-friendly mechanism for capturing data in a consistent way. In FHIR, forms are represented using the Questionnaire resource and completed forms are represented using the QuestionnaireResponse resource. The base FHIR specification defines these resources but doesn't provide much guidance around how they should be used, nor does it set minimal expectations for interoperation. This implementation guide provides a set of guidance around the use of Questionnaire and QuestionnaireResponse. Specifically, it provides answers to - and conformance expectations around - questions such as:

  • What are the minimum capabilities a system should have to properly support FHIR-based forms?
  • How do I present questions in a table?
  • I want help text to appear in red - how do I do that?
  • What's the mechanism to calculate and display a score for a completed form?
  • I don't want to expose the logic of the questionnaire to other systems, but I still want to support form completion. How do I do that using FHIR?
  • Some of the data in this form already exists in the patient's record. How can I save the time (and prevent the transcription errors) associated with re-entering it into a form?
  • Once a form's complete, I want to import the data into other FHIR resources - is there an easy way to do that?

The implementation guide is structured to allow implementers to pick and choose the capabilities they need and combine them as necessary.




This open-source app uses the LHC-Forms form rendering widget to manage FHIR Questionnaire and QuestionnaireResponse resources. It provides partial (and growing) support for the Structured Data Capture (SDC) profile. The app is designed to be launched from an EHR system using SMART on FHIR to connect to the EHR's FHIR server. When you select "Try App" below, you will first go to a patient selector, and then to the app, the idea being that in an EHR environment, the patient would already be chosen before the app is used to fill out a form for the patient.

The app supports both STU3 and R4 versions of FHIR; the "Try App" button will connect you to an R4 FHIR server.

Da Vinci Clinical Data Exchange


Version (1.0.0) for FHIR R4

The CDex implementation guide defines combinations of exchange methods (push, pull, etc. ), specific payloads (Documents, Bundles, and Individual Resources), search criteria, conformance, provenance, and other relevant requirements to support the exchange of clinical information between provider and other providers and/or payers. The goal is to identify, document and constrain specific exchange patterns so that providers and payers can reliably exchange information for patient care (including coordination of care), risk adjustment, quality reporting, identifying that requested services are necessary and appropriate (e.g. should be covered by the payer) and other uses that may be documented as part of this effort. Clinical data payloads will include C-CDA, C-CDA on FHIR, compositions, bundles, and discrete resources conforming to the US Core specification.

Ultimately this IG is expected to support multiple versions of FHIR (DSTU2/Argonaught, STU3, and R4), but the current version of this IG only supports for FHIR R4.

Bidirectional Services eReferrals


Version (0.2.0) for FHIR R3

The Bidirectional Services eReferrals (BSeR) FHIR IG provides guidance on STU3 FHIR Resources and US Core IG profiles for use in exchanging a referral request and specific program data from a clinical provider to a typically extra-clinical program service provider, such as a diabetes prevention program, a smoking quitline, or a hypertension management training program. And provides for the return of feedback information from the service program to the referring provider.

This IG includes definition of the BSer Consent Profile which may be used to share information sharing consent information gathered from the patient.

FHIR Bulk Data Access

Version (1.0.0) for FHIR 4.0

Providers and organizations accountable for managing the health of populations often need to efficiently access large volumes of information on a group of individuals. For example, a health system may want to periodically retrieve updated clinical data from an EHR to a research database, a provider may want to send clinical data on a roster of patients to their ACO to calculate quality measures, or an EHR may want to access claims data to close gaps in care. In most cases, access to these bulk-data exports is pre-authorized between the data holder and the data requester. The data exchange involves extracting a specific subset of fields from the source system, mapping the fields into a structured file format like CSV, and persisting the files in a server from which the requester can then download them into the target system. This multi-step process increases the cost of integration projects and can act as a counter-incentive to data liquidity.

Existing FHIR APIs work well for accessing small amounts of data, but large exports can require hundreds of thousands of requests. This implementation guide defines a standardized, FHIR based approach for exporting bulk data from a FHIR server to a pre-authorized client.



Version (1.1.0) for FHIR R4

Consolidated CDA (C-CDA) is one of the most widely implemented implementation guides for CDA and covers a significant scope of clinical care. Its target of the ‘common/essential’ elements of healthcare is closely aligned with FHIR’s focus on the ‘80%’. There is significant interest in industry and government in the ability to interoperate between CDA and FHIR and C-CDA is a logical starting point. Implementers and regulators have both expressed an interest in the ability to map between FHIR and C-CDA.

This Implementation Guide (IG) defines a series of FHIR profiles on the Composition resource to represent the various document types in C-CDA. This release does not directly map every C-CDA template to FHIR profiles, rather tries to accomplish the C-CDA use case using Composition resource profiles created under this project (the equivalent of Level 2 CDA documents), and begins by linking to the profiles created under the US Core project for any coded entries that would normally be included in C-CDA sections. To have a simpler, more streamlined standard that reuses existing work and focuses on the 80% that implementers actually need in production systems, the resources of US Core represents a portion of the 80% needed for coded entries for coded entries of CCD, Care Plan & Discharge Summary).

The Composition profiles in this IG do not require coded data in any section. This is a departure from C-CDA, which requires coded data for Problems, Results, Medications, etc. This departure is intentional, as the C-CDA requirement for one or more coded entries in these sections resulted in some very complicated workarounds using nullFlavors to handle the fact that sometimes a patient is not on any medications, or has no current problems. In general, FHIR takes the approach that if something is nullable, it should simply be optional to ease the burden on implementers, thus C-CDA on FHIR does not require any coded entries, but rather uses the “required if known” approach, meaning that if an implementer’s system has data for a section that requires data under Meaningful Use, they need to send it, but if they have no data there is no need for a null entry.


  • No labels