-
Notifications
You must be signed in to change notification settings - Fork 33
v2 ‐ v3 Migration Guide (Draft)
- What is BFD v3?
- Field Mappings and Data Element Changes from v2 -> v3
- Patient Merge
- FHIR Conformance
- Data Ingestion Frequency in BFD v3
- Synthetic Data Notes
- Extracting Data Elements from BFD data
- Partially-Adjudicated Claims Data in BFD v3
- Deduplicating Claims and Identifying Duplicates
Beneficiary FHIR Database (BFD) is the FHIR server powering CMS’ Blue Button 2.0, Claims Data to Part D Sponsors API, Beneficiary Claims Data API, and Data at the Point of Care APIs. BFD v3 is the next iteration of BFD, a FHIR R4 server powered by the CMS’ Integrated Data Repository (IDR). BFD v1/v2 are powered by the CMS’ Chronic Conditions Warehouse (CCW), with partially-adjudicated claims data provided by the Replicated Data Access API (RDA). Some advantages of using the IDR, and changes from v2 -> v3 in general, are:
- Improved data refresh rates
- Utilizing a consistent source between partially and fully-adjudicated claims
- Reduced/elimination of instances of missing enrollees
- Additional information for Part D
- Improved FHIR Conformance
- Addition of StructureDefinition and CodeSystem resources
- Verified FHIRPath for each data element to ease extraction of data
BFD v3 is in active development, and mappings can change at any time. Mappings will be current with the BFD v3 data dictionary. When BFD v3 is considered “stable,” an announcement will be made. BFD v3 is currently under active development and subject to change.
- All mappings will align with the BFD v3 data dictionary
- Users should expect frequent updates and modifications until BFD v3 is stable
- An official announcement will be made when BFD v3 transitions from active development to a stable release
- Monitor for official announcements regarding BFD v3 stability before implementing in production environments
BFD v1/v2 will remain fully operational and supported through at least December 31, 2026. This transition to v3 won’t just affect the core BFD v1/v2 system —all APIs that depend on these versions will also be migrated to v3 simultaneously. This coordinated approach ensures consistency across the entire ecosystem and prevents orphaned dependencies that could cause integration issues.
The BFD team has created a comprehensive data dictionary for individual data elements, including the element name, description, FHIRPath expressions, and other information such as which Code Systems are applicable (for CMS-specific terminology).
(link to DD, omitted for now while DD is updated.)
The BFD Data Dictionary is the authoritative source for mappings between BFD's upstream data source (the IDR) and BFD's representation of them using FHIR. The data dictionary also contains mappings from CCLF to FHIR, as well as the CCW column (from the BFD v1/v2 data dictionary) to the FHIR element in v3. Not all elements are an exact match, and there has been consolidation of elements where possible. Some examples of improvements in BFD v3:
- In BFD v1/v2, there are 37 separately-defined extensions to represent "present on admission" indicators for a diagnosis. BFD v3 eliminates all of these extensions by using the ExplanationOfBenefit.diagnosis.onAdmission field with the industry-standard "CMS Present On Admission Indicator Codes Value Set".
- In BFD v1/v2, fields from the CCW such as BENE_PTNT_STUS_CD and NCH_PTNT_STATUS_IND_CD are present, but are duplicative. The data dictionary in v3 notes that these fields are consolidated and represented by BENE_PTNT_STUS_CD alone.
- In BFD v1/v2, fields such as CST_SHR_GRP_CD_01 are represented using 13 extensions that are co-dependent. In BFD v3, the concept of the cost sharing group is represented by multiple extensions, but has no monthly component to it, rather it's tied to the currently active coverage.
BFD will continually update the "notes" column for each field to address questions about the appropriate usage of each field, and it is strongly recommended to reference the data dictionary while migrating from v1/v2 to v3.
Some resource-specific notes are below.
- The Patient resource conforms to C4BB 2.1.0
- The Patient resource populates the US Core Sex Extension to represent Sex
- Dual eligibility status extensions have been removed from the Patient resource and this information is now available through the Coverage resource
- “Member Number” now refers to an individual’s MBI
- Patient Resource IDs are different between v2 and v3. In v3, the resource ID of Patient resources has no intrinsic meaning and is unrelated to the v2 resource ID
- Patient Merge Implemented - See dedicated section below
- All extensions replaced with FHIR-conformant extensions + proper CodeSystems
- Coverage resources now conform with C4BB 2.1.0, as well as US Core 6.1.0.
- Rx elements from Part D plans are present in the Part D Coverage resource
- Additional Coverage resource for Dual Medicare-Medicaid eligibility status
- Reference year + reference month concepts deprecated in favor of start and end dates for individual Coverage resources
- All extensions replaced with FHIR-conformant extensions + proper code systems.
- Claims are mapped to conform with C4BB 2.1.0.
- DME claims now correctly use the Professional profile.
- Partially-adjudicated claims are represented using the ExplanationOfBenefit resource. These claims may not be available in all APIs.
- Notice of hospice election is available in BFD v3, with claim types 1900 and 2900. These claims do not receive an adjudicated version, but are almost always followed up with a submitted hospice claim several weeks after the notice of election is available.
- A new metadata field called 'source' has been added to identify the specific CMS system the information originated from. For example NCH = National Claims History (All adjudicated claims), FISS = Fiscal Intermediary Shared System (Partially-Adjudicated Institutional Claims), MCS = Multi-Carrier System (Partially-Adjudicated Professional Claims), VMS = Viable Information Processing Systems (ViPS) Medicare Shared System (Partially-Adjudicated DME claims)
- A new metadata field called 'tag' will be populated to indicate whether an ExplanationOfBenefit is partially-adjudicated or fully-adjudicated
- Metadata security labels have been added in BFD v3: BFD will return a security tag (42CFRPart2) if an item is determined to be sensitive under an inter-agency agreement with SAMHSA. Partially-adjudicated and fully-adjudicated data will have tags to that effect.
- Information related to cost information that does not relate to an actual “benefit” beyond payment has been moved from ExplanationOfBenefit.benefitBalance to ExplanationOfBenefit.total. Other fields remain unchanged. For example, “lifetime reserve days” remain under benefitBalance.
- Addition of claim control numbers to track prior versions of a claim
BFD v3 implements patient merge. This feature addresses situations where duplicate patient records exist or when patient information requires consolidation. Blue Button 2.0 and the CMS Bulk APIs can search for patients using any Medicare Beneficiary Identifier (MBI), regardless of whether it's a previous or current identifier. The system will always return the active patient record, ensuring consistent access to patient information. The Patient.link element captures the relationship between merged records, showing the directional flow of the merge (whether a record "replaces" another or was "replaced-by" another). ?do we want an example here?
BFD v3 resources conform with CARIN for Blue Button version 2.1.0, which itself builds upon US Core 6.1.0. BFD v3 supports FHIR R4.
BFD v3 retires the usage of http://bluebutton.cms.gov/resources/ to represent extensions and CodeSystems. Instead, these are properly represented in v3 using StructureDefinition and CodeSystem resources.
Example:
In v2, the “Near Line Record Identification Code” uses an extension with the url:
https://bluebutton.cms.gov/resources/variables/nch_near_line_rec_ident_cd/ that also references a code system with the same URL. In v3, the extension has a url of
https://bluebutton.cms.gov/fhir/StructureDefinition/CLM-NRLN-RIC-CD, is represented as a StructureDefinition, and references a FHIR CodeSystem resource:
https://bluebutton.cms.gov/fhir/CodeSystem/CLM-NRLN-RIC-CD
In the BFD data dictionary, fields that are populated by a CMS code system have a link to the CodeSystem URL in the referenceTable column, for easy reference. FHIRPath expressions for extracting these fields also reference the extension urls to help target extraction of individual resources.
There is one instance where BFD deliberately breaks the C4BB specification: The published C4BB 2.1.0 Inpatient Institutional profile disallows Practitioner resources for rendering providers. In CMS data, the overwhelming majority of inpatient institutional claims have an individual as a rendering provider.
In BFD v1/v2, there can be a several month delay between when a enrollee's information is created and when it is received by BFD. Based upon internal testing, this lag time has been reduced to zero in BFD v3. Often, a enrollee's information will be present in BFD several months before Medicare coverage starts.
The table below shows the frequency of updates for data ingested into BFD in each version of BFD.
| Resource | v1/v2 | v3 |
|---|---|---|
| Patient | Weekly, on Friday | 6x/week, on Sunday-Friday |
| Coverage | Weekly, on Friday | 6x/week, on Sunday-Friday |
| ExplanationOfBenefit - Part A/B (Adjudicated) | Weekly, on Friday Data is loaded the Friday after it is loaded into source system. 1-2 weeks from “adjudication” → BFD ingestion) | Weekly, on Tuesday Data is loaded the Tuesday after it is loaded into source system. 0-7 days from “adjudication” → BFD ingestion) |
| ExplanationOfBenefit - Part D | Weekly, on Friday (1 week lag, same as Part A/B above) | 5x/week on Sunday - Thursday |
| ExplanationOfBenefit - Part A/B (Partially-Adjudicated) | 4x/week on Tuesday - Thursday and Sunday (BCDA-only) | 4x/week on Tuesday - Thursday and Sunday |
Synthetic data in BFD v2 was generated using Synthea (https://synthetichealth.github.io/synthea/#home) to approximate the mathematical and statistical properties of real data. Synthetic data in v3 today is representative of how individual fields may populate, but does not necessarily represent a longitudinal progression of an individual’s life. There are future plans to regenerate synthtic data using Synthea but there is no timeline for this effort. If there are specific issues with the synthetic data in v3, please feel free to reach out to the API that you received a given resource from. We love customer interaction!
BFD recommends the use of FHIRPath expressions to extract discrete data elements. FHIRPath expressions are populated in the BFD data dictionary. FHIRPath is a specification that provides path-based navigation and is uniquely suited to provide a consistent way to recommend isolation of specific elements with minimal code. See: https://hl7.org/fhirpath/N1/ for the specification.
To properly resolve references to contained resources, ensure that your FHIRPath implementation is context-aware. The BFD Data Dictionary itself populates examples using fhirpath.js, but additional implementations are listed at https://confluence.hl7.org/spaces/FHIRI/pages/161060129/FHIRPath+Implementations .
FHIRPath expressions can be conveniently used to create ViewDefinitions for use with SQL on FHIR (https://build.fhir.org/ig/FHIR/sql-on-fhir-v2/).
Partially-adjudicated claims are limited to certain APIs. For questions about the availability of partially-adjudicated claims within v3 for a given CMS API, please contact that API team via their google group.
BFD v3 enables more widespread availability of partially-adjudicated claim elements, and more consistency with adjudicated claims compared to v2. They are represented using the ExplanationOfBenefit resource, and are profiled to CARIN for Blue Button 2.1.0 profiles.
Some notes on partially-adjudicated claims:
- Data quality is lower than in adjudicated claims. Especially claims with a claim type code of 1XXX.
- The Meta.tag key can be used to determine if a claim is considered adjudicated or partially-adjudicated in the eyes of CMS.
- Not all fields are available in partially-adjudicated claims. Most of these relate to benefit balance information that is not available until a claim has been fully adjudicated.
BFD handles deduplication of claims from the same source automatically (within reason). BFD will only surface the latest version of a claim, as indicated by its upstream source. BFD does not de-duplicate between sources of claims information (for example, there may be both an adjudicated and a partially-adjudicated version of a claim present. See below for methods that enable de-duplication between partially and fully-adjudicated claims. ) Since it’s inefficient to perform full pulls for each patient each time, and to enable comparison to other formats such as CCLF, we have tested a way to de-duplicate claims.
To de-duplicate an individual’s claims, the CLM-CNTL-NUM identifier (ExplanationOfBenefit.identifier.where(‘system’=’https://bluebutton.cms.gov/fhir/CodeSystem/CLM-CNTL-NUM’)) can be used to identify, within a claim type, which claims are the same.
Additionally, if a claim receives a new claim control number, the previous claim control number will be available in ExplanationOfBenefit.related, and can be used to de-duplicate claims even if the claim control number has changed.
There may be some instances where a claim is not able to be de-duplicated via the CLM-CNTL-NUM. This occurs infrequently, but most often when a claim is originally submitted incorrectly or goes through a significant number of revisions. Some elements that may help in determining "are these two claims actually the same claim," broken down by claim domain, are:
Institutional Claims:
billablePeriod.start
billablePeriod.end
Provider NPI
Professional Claims:
These should always able to be deduplicated by the CLM-CNTL-NUM on a per-enrollee basis.
Part D Claims:
These should always able to be deduplicated by the CLM-CNTL-NUM on a per-enrollee basis.
For claims that have been previously submitted, when a new claim control number is obtained, the prior one is available in the EOB.related element. Of note, this relationship is only one level deep. If a claim has been re-submitted multiple times, and a consumer only has the first and final versions of a claim, using the CLM-CNTL-NUM will not work to fully populate the linked list of claim control numbers. Other fields can be used for this purpose. In practice, this will only really affect institutional claims.
One note:
- Phase 1 (claim type code 1XXX) claims can contain many duplicates that may not be marked as related upstream of BFD, meaning BFD cannot de-duplicate them with the claim that eventually gets processed. In claims processing, these claims are abandoned. To avoid leaving duplicates forever, any partially-adjudicated claim that has no updates for 60 days will be deleted from BFD. This is most common with institutional claims, and can generally be inferred by a significant number of fields for two resources being the exact same in everything except payment and CLM-CNTL-NUM.
- Home
- For BFD Users
- Making Requests to BFD
- API Changelog
- Migrating to V2 FAQ
- Synthetic and Synthea Data
- BFD SAMHSA Filtering