FHIR Data Model
Resource schemas, field definitions, and relationship graph for the CMS NPD FHIR R4 dataset
Resource Relationship Graph
| From Resource | Field | To Resource | Completeness |
|---|---|---|---|
| PractitionerRole | .practitioner | Practitioner | 100% |
| PractitionerRole | .organization | Organization | 98.1% |
| PractitionerRole | .location[] | Location | 78.0% |
| PractitionerRole | .endpoint[] | Endpoint | 6.2% |
| Location | .managingOrganization | Organization | 76.6% |
| Endpoint | .managingOrganization | Organization | 19.2% |
| OrganizationAffiliation | .organization + participating | Organization | 100% |
Resource Schemas
Individual healthcare providers. Each record has a unique NPI, name, gender, qualifications (NUCC taxonomy), and optional communication languages.
| Field | Type | Notes |
|---|---|---|
| id | string | Internal FHIR resource ID |
| identifier[NPI] | Identifier | National Provider Identifier (100% present) |
| active | boolean | 96.5% active in sample |
| name | HumanName | Family + given names (100% present) |
| gender | code | male | female | other | unknown |
| qualification | Qualification[] | NUCC taxonomy codes (95.2% present) |
| communication | CodeableConcept[] | Spoken languages (2.8% present) |
The join table of the NPD. Links a Practitioner to an Organization, Location, and Endpoint. Contains specialty codes (NUCC) and telecom for the role.
| Field | Type | Notes |
|---|---|---|
| practitioner | Reference<Practitioner> | 100% present |
| organization | Reference<Organization> | 98.1% present |
| location | Reference<Location>[] | 78% present |
| endpoint | Reference<Endpoint>[] | 6.2% present |
| specialty | CodeableConcept[] | NUCC specialty (46.1% present) |
| telecom | ContactPoint[] | Phone/fax (75.2% present) |
| active | boolean | 55.2% active in sample |
Healthcare entities: hospitals, clinics, health systems, pharmacies. Each has NPI + Pseudo-EIN identifiers, address, and telecom.
| Field | Type | Notes |
|---|---|---|
| identifier[NPI] | Identifier | National Provider Identifier (100%) |
| identifier[pseudo-EIN] | Identifier | CMS-assigned pseudo-EIN (100%) |
| active | boolean | 100% active in sample |
| name | string | Organization name |
| address | Address[] | Physical address (88.2% present) |
| telecom | ContactPoint[] | Phone/fax (88.7% present) |
| type | CodeableConcept[] | Organization type code |
Physical service locations. All have addresses; 46.6% have GPS coordinates. Linked to managing organizations.
| Field | Type | Notes |
|---|---|---|
| status | code | active | suspended | inactive (100% active) |
| mode | code | instance (100% in sample) |
| address | Address | Physical address (100% present) |
| position | Position | GPS lat/lon (46.6% present) |
| managingOrganization | Reference<Organization> | 76.6% present |
| physicalType | CodeableConcept | Building type code |
FHIR API endpoints for healthcare interoperability. All are active HTTPS URLs using the hl7-fhir-rest connection type.
| Field | Type | Notes |
|---|---|---|
| status | code | active (100% in sample) |
| connectionType | Coding | hl7-fhir-rest |
| address | url | HTTPS FHIR endpoint URL (100% HTTPS) |
| payloadType | CodeableConcept[] | not-applicable (100%) |
| managingOrganization | Reference<Organization> | 19.2% present |
Inter-organization relationships. 80.7% are 'Member' affiliations, defining healthcare network membership.
| Field | Type | Notes |
|---|---|---|
| organization | Reference<Organization> | Parent org (100% present) |
| participatingOrganization | Reference<Organization> | Member org (100% present) |
| code | CodeableConcept[] | Member (80.7%) or other |
| active | boolean | 100% active in sample |
Each file is Newline-Delimited JSON — one FHIR resource per line. Ideal for streaming, parallel processing, and bulk loading into databases.
Files use zstd level 12 compression, achieving ~93% size reduction (40.7 GB → 2.8 GB). Decompress with: zstdcat file.ndjson.zst | jq '.'
Full schema documentation available at the HTE Data Release Specifications on GitHub: ftrotter-gov/HTE_data_release_specifications