# b(10) EHI Export Data Dictionary and Field Definitions
**Status:** Active reference
**Version:** 1.0
**Date:** 2026-06-24
**Applies To:** ONC 170.315(b)(10) — `ndjson-v1` export packages
**Companion Documents:**
- [`b10-ehi-export-format-specification.md`](b10-ehi-export-format-specification.md) — Package structure and conformance
- [`b10-drs-inventory.md`](b10-drs-inventory.md) — Designated Record Set scope decisions
- [`b10-ehi-export-manifest-contract.md`](b10-ehi-export-manifest-contract.md) — Manifest schema contract
---
## Table of Contents
1. [Layperson Summary](#layperson-summary)
2. [How to Use This Document](#how-to-use-this-document)
3. [Export Data Organization](#export-data-organization)
4. [Terminology and Coding Systems](#terminology-and-coding-systems)
5. [Canonical FHIR R4 Resource Definitions](#canonical-fhir-r4-resource-definitions)
- [Patient](#patient)
- [Encounter](#encounter)
- [Condition](#condition)
- [Observation](#observation)
- [MedicationRequest](#medicationrequest)
- [AllergyIntolerance](#allergyintolerance)
- [Procedure](#procedure)
- [Immunization](#immunization)
- [DiagnosticReport](#diagnosticreport)
- [DocumentReference](#documentreference)
- [CareTeam](#careteam)
- [Consent](#consent)
- [EpisodeOfCare](#episodeofcare)
- [List](#list)
- [Media](#media)
- [Provenance](#provenance)
- [Communication](#communication)
- [Appointment](#appointment)
6. [Supplemental File Definitions](#supplemental-file-definitions)
- [Clinical Notes (Raw Text)](#clinical-notes-raw-text)
- [C-CDA XML Documents](#c-cda-xml-documents)
- [Direct Message Attachments](#direct-message-attachments)
- [Raw HL7 v2 Messages](#raw-hl7-v2-messages)
7. [Data Provenance and Source Tagging](#data-provenance-and-source-tagging)
8. [Deduplication and Merge Strategy](#deduplication-and-merge-strategy)
9. [Null Handling and Optional Fields](#null-handling-and-optional-fields)
10. [Importing and Interpreting Export Data](#importing-and-interpreting-export-data)
11. [FHIR R4 Conformance Notes](#fhir-r4-conformance-notes)
12. [Change Log](#change-log)
---
## Layperson Summary
This document is the **field-level reference** for interpreting data in Scribe Mutual EHI export packages. It explains every data element that can appear in the export: what each field means, what coding systems are used, and how a receiving system should interpret the data.
In plain terms: the [format specification](b10-ehi-export-format-specification.md) tells you *where* each file lives in the ZIP package and *how* to parse it. This document tells you *what each field inside those files means* and *how to use the data correctly*.
All clinical data in the NDJSON files follows the **HL7 FHIR R4** standard (version 4.0.1). Supplemental files use national standards: **HL7 C-CDA R2.1** for clinical document XML, **HL7 v2.x** for interoperability messages, and **plain text** for clinical note content.
---
## How to Use This Document
1. **Unzip the export package** per the [format specification](b10-ehi-export-format-specification.md).
2. **Parse `clinical.ndjson`** — each line is a standalone JSON object. The `resourceType` field on each line tells you which section of this document describes its fields.
3. **Look up the resource type** in Section 5 below to understand every field in that JSON object.
4. **Check the `meta.tag` array** — if a resource carries a tag with `system: "urn:scribe-mutual:ehi:source"`, it was synthesized from a legacy data store rather than stored natively as FHIR. See [Data Provenance and Source Tagging](#data-provenance-and-source-tagging).
5. **Open supplemental files** (documents, HL7, C-CDA) using the guidance in Section 6.
---
## Export Data Organization
Each patient's data is exported in two layers:
| Layer | Location in ZIP | Format | Description |
|-------|----------------|--------|-------------|
| **Canonical clinical data** | `patients/{patientId}/clinical.ndjson` | FHIR R4 NDJSON | One JSON object per line. Each object is a FHIR R4 resource. |
| **Supplemental artifacts** | `patients/{patientId}/documents/`, `patients/{patientId}/media/`, `interoperability/{patientId}/` | Native format (XML, text, HL7, binary) | Raw clinical artifacts preserved in their original format because lossless FHIR conversion is not possible or would lose clinically relevant detail. |
The canonical NDJSON layer is always present for each patient. Supplemental folders appear only when the patient has corresponding data.
---
## Terminology and Coding Systems
Coded clinical data elements use nationally recognized terminology systems. The `system` field within `coding` arrays identifies which terminology is in use.
| System URI | Name | Used For | Reference |
|------------|------|----------|-----------|
| `http://snomed.info/sct` | SNOMED CT | Conditions, procedures, clinical findings, body sites | [SNOMED International](https://www.snomed.org/) |
| `http://loinc.org` | LOINC | Observations, lab results, vital signs, document types | [LOINC.org](https://loinc.org/) |
| `http://www.nlm.nih.gov/research/umls/rxnorm` | RxNorm | Medications (drug names, ingredients, strengths) | [NLM RxNorm](https://www.nlm.nih.gov/research/umls/rxnorm/) |
| `urn:oid:2.16.840.1.113883.6.88` | RxNorm (OID form) | Medications (alternate system identifier) | Same as above |
| `http://hl7.org/fhir/sid/cvx` | CVX | Vaccine codes | [CDC CVX](https://www2a.cdc.gov/vaccines/iis/iisstandards/vaccines.asp) |
| `http://hl7.org/fhir/sid/icd-10-cm` | ICD-10-CM | Diagnosis codes | [CMS ICD-10](https://www.cms.gov/medicare/coding-billing/icd-10-codes) |
| `http://hl7.org/fhir/sid/icd-10-pcs` | ICD-10-PCS | Procedure codes | [CMS ICD-10-PCS](https://www.cms.gov/medicare/coding-billing/icd-10-codes) |
| `http://www.ama-assn.org/go/cpt` | CPT | Procedure codes | [AMA CPT](https://www.ama-assn.org/amaone/cpt-current-procedural-terminology) |
| `http://terminology.hl7.org/CodeSystem/v3-ActCode` | HL7 Act Code | Encounter types, consent scopes | [HL7 Terminology](https://terminology.hl7.org/) |
| `http://terminology.hl7.org/CodeSystem/condition-clinical` | Condition Clinical Status | active, recurrence, relapse, inactive, remission, resolved | [FHIR R4 Spec](https://hl7.org/fhir/R4/valueset-condition-clinical.html) |
| `http://terminology.hl7.org/CodeSystem/condition-ver-status` | Condition Verification Status | unconfirmed, provisional, differential, confirmed, refuted, entered-in-error | [FHIR R4 Spec](https://hl7.org/fhir/R4/valueset-condition-ver-status.html) |
| `http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical` | Allergy Clinical Status | active, inactive, resolved | [FHIR R4 Spec](https://hl7.org/fhir/R4/valueset-allergyintolerance-clinical.html) |
| `http://terminology.hl7.org/CodeSystem/allergyintolerance-verification` | Allergy Verification Status | unconfirmed, confirmed, refuted, entered-in-error | [FHIR R4 Spec](https://hl7.org/fhir/R4/valueset-allergyintolerance-verification.html) |
| `urn:scribe-mutual:ehi:source` | Scribe Mutual Source Tag | Identifies resources synthesized from legacy/fallback data stores | See [Data Provenance](#data-provenance-and-source-tagging) |
### How to Interpret Coded Fields
Most clinical data elements use the FHIR `CodeableConcept` structure:
```json
{
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "73211009",
"display": "Diabetes mellitus"
}
],
"text": "Diabetes mellitus"
}
}
```
| Field | Meaning |
|-------|---------|
| `coding[].system` | The terminology system URI (see table above). Use this to look up the code in the correct reference database. |
| `coding[].code` | The machine-readable code within that system. This is the primary identifier for interoperability. |
| `coding[].display` | Human-readable display text for the code. This is informational and may not match the official preferred term exactly. |
| `text` | Free-text description. Present when a human-readable summary is available. May differ from `coding[].display`. |
A `CodeableConcept` may contain multiple `coding` entries when the same concept is represented in more than one terminology system (e.g., both SNOMED CT and ICD-10-CM for a diagnosis).
---
## Canonical FHIR R4 Resource Definitions
Every JSON line in `clinical.ndjson` is a FHIR R4 resource. The `resourceType` field identifies which definition applies.
### Patient
**Clinical Domain:** Demographics
**Description:** Core demographic and administrative information for the patient. Every export contains exactly one Patient resource per patient.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Patient"` | Identifies this as a Patient resource |
| `id` | string | Yes | Patient logical identifier (ULID) | Unique within the Scribe Mutual system |
| `meta` | Meta | No | Resource metadata (version, lastUpdated, tags) | See [Data Provenance](#data-provenance-and-source-tagging) for `meta.tag` interpretation |
| `identifier` | Identifier[] | No | External identifiers (MRN, SSN, etc.) | `identifier[].system` identifies the assigning authority; `identifier[].value` is the ID value |
| `active` | boolean | No | Whether this patient record is active | `false` indicates the record has been deactivated |
| `name` | HumanName[] | No | Patient name(s) | `name[].use` indicates purpose (official, usual, nickname). `name[].family` is surname; `name[].given[]` are first/middle names |
| `telecom` | ContactPoint[] | No | Phone numbers, email addresses | `telecom[].system` = phone/email/fax; `telecom[].value` = the number/address; `telecom[].use` = home/work/mobile |
| `gender` | code | No | Administrative gender | Values: `male`, `female`, `other`, `unknown` |
| `birthDate` | date | No | Date of birth | Format: `YYYY-MM-DD` |
| `deceasedBoolean` | boolean | No | Whether the patient is deceased | |
| `deceasedDateTime` | dateTime | No | Date/time of death if known | ISO 8601 format |
| `address` | Address[] | No | Patient address(es) | `address[].use` = home/work/temp; `address[].line[]`, `address[].city`, `address[].state`, `address[].postalCode`, `address[].country` |
| `maritalStatus` | CodeableConcept | No | Marital status | HL7 v3 MaritalStatus codes |
| `contact` | BackboneElement[] | No | Emergency contacts, next of kin | Each entry has `relationship`, `name`, `telecom`, `address` |
| `communication` | BackboneElement[] | No | Languages spoken | `communication[].language` is a CodeableConcept; `communication[].preferred` indicates primary language |
| `generalPractitioner` | Reference[] | No | Primary care provider(s) | Reference to `Practitioner` or `Organization` |
| `managingOrganization` | Reference | No | Organization responsible for the record | Reference to `Organization` |
| `extension` | Extension[] | No | US Core extensions | May include race, ethnicity, birth sex per US Core Patient profile |
### Encounter
**Clinical Domain:** Encounters
**Description:** A clinical interaction between a patient and healthcare provider(s). Represents visits, appointments that occurred, telehealth sessions, and other care events.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Encounter"` | |
| `id` | string | Yes | Encounter logical identifier | |
| `status` | code | Yes | Current encounter state | Values: `planned`, `arrived`, `triaged`, `in-progress`, `onleave`, `finished`, `cancelled`, `entered-in-error`, `unknown` |
| `class` | Coding | Yes | Classification of the encounter | Common values: `AMB` (ambulatory), `IMP` (inpatient), `EMER` (emergency), `VR` (virtual/telehealth) |
| `type` | CodeableConcept[] | No | Specific encounter type | Coded with SNOMED CT or local codes |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `participant` | BackboneElement[] | No | Providers involved in the encounter | Each has `type` (role), `individual` (Practitioner reference), `period` |
| `period` | Period | No | Start and end time of the encounter | `period.start` and `period.end` in ISO 8601 format |
| `reasonCode` | CodeableConcept[] | No | Reason for the encounter | Typically SNOMED CT or ICD-10-CM codes |
| `diagnosis` | BackboneElement[] | No | Diagnoses relevant to the encounter | Each has `condition` (Reference to Condition), `use` (role), `rank` |
| `serviceProvider` | Reference | No | Organization providing the service | Reference to `Organization` |
| `location` | BackboneElement[] | No | Location(s) where the encounter took place | |
### Condition
**Clinical Domain:** Conditions / Problems
**Description:** A clinical condition, problem, or diagnosis recorded for the patient. Includes active problems, historical diagnoses, and resolved conditions.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Condition"` | |
| `id` | string | Yes | Condition logical identifier | |
| `clinicalStatus` | CodeableConcept | No | Whether the condition is active | Coded values: `active`, `recurrence`, `relapse`, `inactive`, `remission`, `resolved`. System: `http://terminology.hl7.org/CodeSystem/condition-clinical` |
| `verificationStatus` | CodeableConcept | No | Degree of certainty | Values: `unconfirmed`, `provisional`, `differential`, `confirmed`, `refuted`, `entered-in-error` |
| `category` | CodeableConcept[] | No | Category of condition | Values: `problem-list-item`, `encounter-diagnosis`, `health-concern` |
| `code` | CodeableConcept | Yes | The condition code | Typically SNOMED CT or ICD-10-CM. See [Terminology and Coding Systems](#terminology-and-coding-systems) |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `onsetDateTime` | dateTime | No | When the condition started | ISO 8601 format |
| `recordedDate` | dateTime | No | When the condition was first recorded in the system | ISO 8601 format |
| `meta.tag` | Coding[] | No | Source provenance tags | See [Data Provenance](#data-provenance-and-source-tagging) |
### Observation
**Clinical Domain:** Observations / Vitals / Lab Results
**Description:** Clinical measurements and findings including vital signs (blood pressure, heart rate, temperature, weight), laboratory results, social history assessments, and other recorded observations.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Observation"` | |
| `id` | string | Yes | Observation logical identifier | |
| `status` | code | Yes | Observation lifecycle status | Values: `registered`, `preliminary`, `final`, `amended`, `corrected`, `cancelled`, `entered-in-error`, `unknown` |
| `category` | CodeableConcept[] | No | Classification of observation | Common categories: `vital-signs`, `laboratory`, `social-history`, `exam`. System: `http://terminology.hl7.org/CodeSystem/observation-category` |
| `code` | CodeableConcept | Yes | What was observed | Coded with LOINC (preferred for lab/vitals) or SNOMED CT |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `effectiveDateTime` | dateTime | No | Clinically relevant time of observation | When the observation was made or the specimen was collected |
| `issued` | instant | No | When the result was made available | System timestamp |
| `valueQuantity` | Quantity | No | Numeric result with unit | `valueQuantity.value` (number), `.unit` (display), `.system` (typically `http://unitsofmeasure.org`), `.code` (UCUM code) |
| `valueCodeableConcept` | CodeableConcept | No | Coded result (e.g., positive/negative) | Used for qualitative results |
| `valueString` | string | No | Free-text result | Used when result is not numeric or coded |
| `interpretation` | CodeableConcept[] | No | Abnormal flag | Values: `N` (normal), `H` (high), `L` (low), `A` (abnormal), `HH` (critically high), `LL` (critically low) |
| `referenceRange` | BackboneElement[] | No | Normal range for the observation | `low`, `high`, `text` sub-fields |
| `component` | BackboneElement[] | No | Component results (e.g., systolic/diastolic for blood pressure) | Each component has its own `code`, `value[x]`, `interpretation` |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### MedicationRequest
**Clinical Domain:** Medications
**Description:** An order or prescription for a medication. Includes active prescriptions, historical medication orders, and discontinued medications.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"MedicationRequest"` | |
| `id` | string | Yes | Medication request logical identifier | |
| `status` | code | Yes | Order status | Values: `active`, `on-hold`, `cancelled`, `completed`, `entered-in-error`, `stopped`, `draft`, `unknown` |
| `intent` | code | Yes | Purpose of the request | Values: `proposal`, `plan`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option` |
| `medicationCodeableConcept` | CodeableConcept | Yes | The medication ordered | Coded with RxNorm. `coding[].system` = `http://www.nlm.nih.gov/research/umls/rxnorm` |
| `medicationReference` | Reference | No | Reference to a Medication resource | Alternative to `medicationCodeableConcept` |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `authoredOn` | dateTime | No | When the prescription was written | ISO 8601 format |
| `requester` | Reference | No | Prescribing provider | Reference to `Practitioner` or `PractitionerRole` |
| `dosageInstruction` | Dosage[] | No | How the medication should be taken | Each entry has `text`, `timing`, `route`, `doseAndRate` |
| `dispenseRequest` | BackboneElement | No | Dispensing details | `numberOfRepeatsAllowed`, `quantity`, `expectedSupplyDuration` |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### AllergyIntolerance
**Clinical Domain:** Allergies
**Description:** A record of a clinical allergy or intolerance to a substance. Includes drug allergies, food allergies, and environmental allergies.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"AllergyIntolerance"` | |
| `id` | string | Yes | Allergy record logical identifier | |
| `clinicalStatus` | CodeableConcept | No | Whether the allergy is active | Values: `active`, `inactive`, `resolved` |
| `verificationStatus` | CodeableConcept | No | Certainty of the allergy | Values: `unconfirmed`, `confirmed`, `refuted`, `entered-in-error` |
| `type` | code | No | Whether it is an allergy or intolerance | Values: `allergy`, `intolerance` |
| `category` | code[] | No | Category of substance | Values: `food`, `medication`, `environment`, `biologic` |
| `criticality` | code | No | Potential seriousness | Values: `low`, `high`, `unable-to-assess` |
| `code` | CodeableConcept | Yes | The substance or product | Coded with RxNorm (medications), SNOMED CT (substances), or NDF-RT |
| `patient` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `onsetDateTime` | dateTime | No | When the allergy was first identified | |
| `recordedDate` | dateTime | No | When the allergy was recorded in the system | |
| `reaction` | BackboneElement[] | No | Adverse reaction details | Each has `substance`, `manifestation[]` (symptoms), `severity` (mild/moderate/severe) |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### Procedure
**Clinical Domain:** Procedures
**Description:** A clinical procedure that has been performed on the patient. Includes surgical procedures, diagnostic procedures, counseling, and other clinical actions.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Procedure"` | |
| `id` | string | Yes | Procedure logical identifier | |
| `status` | code | Yes | Procedure status | Values: `preparation`, `in-progress`, `not-done`, `on-hold`, `stopped`, `completed`, `entered-in-error`, `unknown` |
| `code` | CodeableConcept | Yes | The procedure performed | Coded with SNOMED CT, CPT, or ICD-10-PCS |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `performedDateTime` | dateTime | No | When the procedure was performed | ISO 8601 format |
| `performedPeriod` | Period | No | Time range if the procedure spanned a period | `start` and `end` in ISO 8601 |
| `performer` | BackboneElement[] | No | Who performed the procedure | Each has `actor` (Practitioner reference) and `function` (role) |
| `reasonCode` | CodeableConcept[] | No | Why the procedure was performed | |
| `bodySite` | CodeableConcept[] | No | Body site(s) involved | Coded with SNOMED CT body structure codes |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### Immunization
**Clinical Domain:** Immunizations
**Description:** A record of a vaccine administration. Includes the vaccine given, date administered, and administration details.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Immunization"` | |
| `id` | string | Yes | Immunization record logical identifier | |
| `status` | code | Yes | Event status | Values: `completed`, `entered-in-error`, `not-done` |
| `vaccineCode` | CodeableConcept | Yes | Vaccine product administered | Coded with CVX (CDC vaccine codes). `coding[].system` = `http://hl7.org/fhir/sid/cvx` |
| `patient` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `occurrenceDateTime` | dateTime | No | Date the vaccine was administered | ISO 8601 format |
| `occurrenceString` | string | No | Approximate date if exact date unknown | Free text |
| `primarySource` | boolean | No | Whether the record comes from the administering provider | `true` = administered here; `false` = reported by patient or transferred |
| `lotNumber` | string | No | Vaccine lot number | |
| `site` | CodeableConcept | No | Body site of injection | |
| `route` | CodeableConcept | No | Route of administration | e.g., intramuscular, subcutaneous |
| `performer` | BackboneElement[] | No | Who administered the vaccine | |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### DiagnosticReport
**Clinical Domain:** Diagnostics
**Description:** Findings and interpretation of diagnostic tests including laboratory results, imaging studies, and other diagnostic procedures.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"DiagnosticReport"` | |
| `id` | string | Yes | Report logical identifier | |
| `status` | code | Yes | Report status | Values: `registered`, `partial`, `preliminary`, `final`, `amended`, `corrected`, `appended`, `cancelled`, `entered-in-error`, `unknown` |
| `category` | CodeableConcept[] | No | Report category | Common: `LAB` (laboratory), `RAD` (radiology), `PATH` (pathology) |
| `code` | CodeableConcept | Yes | Type of report | Coded with LOINC |
| `subject` | Reference | Yes | Reference to the Patient | |
| `effectiveDateTime` | dateTime | No | Clinically relevant time | When specimens were collected or imaging performed |
| `issued` | instant | No | When the report was released | |
| `performer` | Reference[] | No | Responsible laboratory or radiologist | |
| `result` | Reference[] | No | References to Observation resources containing individual results | |
| `conclusion` | string | No | Clinical interpretation text | |
| `presentedForm` | Attachment[] | No | Entire report as a rendered document | `contentType`, `data` (base64), or `url` |
### DocumentReference
**Clinical Domain:** Documents
**Description:** A reference to a clinical document. Points to external or embedded documents such as clinical notes, discharge summaries, C-CDA documents, uploaded files, and other unstructured clinical content.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"DocumentReference"` | |
| `id` | string | Yes | Document reference logical identifier | |
| `status` | code | Yes | Document status | Values: `current`, `superseded`, `entered-in-error` |
| `type` | CodeableConcept | No | Type of document | Coded with LOINC document type codes |
| `category` | CodeableConcept[] | No | Document category | e.g., clinical-note, discharge-summary |
| `subject` | Reference | Yes | Reference to the Patient | |
| `date` | instant | No | When the document was created | |
| `author` | Reference[] | No | Who created the document | |
| `description` | string | No | Human-readable description | |
| `content` | BackboneElement[] | Yes | Document content pointer(s) | Each has `attachment` with `contentType`, `url`, `data`, `title`, `size` |
| `context` | BackboneElement | No | Clinical context | `encounter` (Reference), `period`, `facilityType`, `practiceSetting` |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### CareTeam
**Clinical Domain:** Care Coordination
**Description:** The team of healthcare professionals involved in the patient's care. Includes assigned clinicians, care coordinators, and their roles.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"CareTeam"` | |
| `id` | string | Yes | Care team logical identifier | |
| `status` | code | No | Team status | Values: `proposed`, `active`, `suspended`, `inactive`, `entered-in-error` |
| `name` | string | No | Name for the care team | |
| `subject` | Reference | Yes | Reference to the Patient | |
| `participant` | BackboneElement[] | No | Team members | Each has `role[]` (CodeableConcept), `member` (Reference to Practitioner/Organization), `period` |
| `managingOrganization` | Reference[] | No | Organization(s) responsible | |
### Consent
**Clinical Domain:** Consent / Advance Directives
**Description:** A record of a patient's consent decisions, including treatment consent, data sharing preferences, and advance directives.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Consent"` | |
| `id` | string | Yes | Consent record logical identifier | |
| `status` | code | Yes | Consent status | Values: `draft`, `proposed`, `active`, `rejected`, `inactive`, `entered-in-error` |
| `scope` | CodeableConcept | Yes | Type of consent | Values: `adr` (advance directive), `research`, `patient-privacy`, `treatment` |
| `category` | CodeableConcept[] | No | Consent category | |
| `patient` | Reference | Yes | Reference to the Patient | |
| `dateTime` | dateTime | No | When consent was given or recorded | |
| `performer` | Reference[] | No | Who granted consent | |
| `sourceReference` | Reference | No | Source document for the consent | Reference to `DocumentReference` if the consent relates to a signed document |
| `provision` | BackboneElement | No | Consent constraints and provisions | `type` (deny/permit), `period`, `actor[]`, `data[]` |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### EpisodeOfCare
**Clinical Domain:** Episodes of Care
**Description:** An association between a patient and an organization for a specific period of care management. Groups related encounters and activities under a shared care context.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"EpisodeOfCare"` | |
| `id` | string | Yes | Episode logical identifier | |
| `status` | code | Yes | Episode status | Values: `planned`, `waitlist`, `active`, `onhold`, `finished`, `cancelled`, `entered-in-error` |
| `type` | CodeableConcept[] | No | Type of care episode | |
| `diagnosis` | BackboneElement[] | No | Diagnoses relevant to this episode | Each has `condition` (Reference to Condition), `role`, `rank` |
| `patient` | Reference | Yes | Reference to the Patient | |
| `managingOrganization` | Reference | No | Organization managing the episode | |
| `period` | Period | No | Time span of the episode | |
| `careManager` | Reference | No | Care manager responsible | Reference to `Practitioner` |
### List
**Clinical Domain:** Clinical Lists
**Description:** A curated collection of clinical items such as problem lists, medication lists, allergy lists, or other clinically grouped records.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"List"` | |
| `id` | string | Yes | List logical identifier | |
| `status` | code | Yes | List status | Values: `current`, `retired`, `entered-in-error` |
| `mode` | code | Yes | How the list was built | Values: `working`, `snapshot`, `changes` |
| `title` | string | No | Descriptive name for the list | |
| `code` | CodeableConcept | No | What kind of list | e.g., problem list, medication list |
| `subject` | Reference | Yes | Reference to the Patient | |
| `date` | dateTime | No | When the list was last revised | |
| `entry` | BackboneElement[] | No | Items in the list | Each has `item` (Reference to the clinical resource), `date`, `deleted` (boolean) |
### Media
**Clinical Domain:** Media
**Description:** A photo, video, or audio recording acquired or used in the clinical context. Includes clinical images, wound photos, and other media attachments.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Media"` | |
| `id` | string | Yes | Media logical identifier | |
| `status` | code | Yes | Media status | Values: `preparation`, `in-progress`, `not-done`, `on-hold`, `stopped`, `completed`, `entered-in-error`, `unknown` |
| `type` | CodeableConcept | No | Classification of media | |
| `modality` | CodeableConcept | No | Imaging modality | For DICOM images |
| `subject` | Reference | Yes | Reference to the Patient | |
| `createdDateTime` | dateTime | No | When the media was collected | |
| `content` | Attachment | Yes | Actual media content | `contentType` (MIME), `data` (base64) or `url`, `title`, `size` |
### Provenance
**Clinical Domain:** Provenance
**Description:** Tracks the origin, authorship, and modification history of clinical resources. Records who created or modified a resource, when, and why.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Provenance"` | |
| `id` | string | Yes | Provenance logical identifier | |
| `target` | Reference[] | Yes | Resources this provenance record applies to | References to the clinical resources being described |
| `recorded` | instant | Yes | When the provenance was recorded | |
| `agent` | BackboneElement[] | Yes | Who was involved | Each has `type` (role), `who` (Reference to Practitioner/Organization/Device) |
| `entity` | BackboneElement[] | No | Related entities | Each has `role` (derivation/revision/quotation/source/removal), `what` (Reference) |
### Communication
**Clinical Domain:** Communications
**Description:** A clinical communication or notification related to the patient. Includes patient portal messages, care coordination notes, appointment reminders, and Direct messaging content.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Communication"` | |
| `id` | string | Yes | Communication logical identifier | |
| `status` | code | Yes | Message status | Values: `preparation`, `in-progress`, `not-done`, `on-hold`, `stopped`, `completed`, `entered-in-error`, `unknown` |
| `category` | CodeableConcept[] | No | Message type/category | Values indicate the type of communication (notification, alert, reminder, clinical message) |
| `subject` | Reference | Yes | Reference to the Patient | Format: `Patient/{patientId}` |
| `sent` | dateTime | No | When the message was sent | ISO 8601 format |
| `received` | dateTime | No | When the message was received | |
| `sender` | Reference | No | Who sent the message | Reference to `Practitioner`, `Organization`, or `Device` |
| `recipient` | Reference[] | No | Intended recipient(s) | |
| `payload` | BackboneElement[] | No | Message content | Each has `contentString` (text), `contentAttachment`, or `contentReference` |
| `meta.tag` | Coding[] | No | Source provenance tags | |
### Appointment
**Clinical Domain:** Appointments
**Description:** A scheduled appointment or calendar event involving the patient. Includes past, current, and future appointments with all statuses.
| Field | FHIR Type | Required | Description | Interpretation Notes |
|-------|-----------|----------|-------------|---------------------|
| `resourceType` | string | Yes | Always `"Appointment"` | |
| `id` | string | Yes | Appointment logical identifier | |
| `status` | code | Yes | Appointment status | Values: `proposed`, `pending`, `booked`, `arrived`, `fulfilled`, `cancelled`, `noshow`, `entered-in-error`, `checked-in`, `waitlist` |
| `description` | string | No | Description or title of the appointment | |
| `start` | instant | No | Scheduled start time | ISO 8601 format (UTC) |
| `end` | instant | No | Scheduled end time | ISO 8601 format (UTC) |
| `participant` | BackboneElement[] | Yes | Who is involved | Each has `actor` (Reference to Patient/Practitioner/Location), `status` (accepted/declined/tentative/needs-action) |
| `reasonCode` | CodeableConcept[] | No | Reason for the appointment | |
| `meta.tag` | Coding[] | No | Source provenance tags | |
---
## Supplemental File Definitions
Supplemental files are included alongside the canonical NDJSON data when the original artifact format carries clinically significant information that cannot be losslessly represented in FHIR R4 JSON.
### Clinical Notes (Raw Text)
**Location:** `patients/{patientId}/documents/note-{noteId}.txt` and `patients/{patientId}/documents/note-section-{sectionType}.txt`
**Format:** UTF-8 plain text
**MIME Type:** `text/plain`
**Manifest Category:** `document-binary`
These files contain the finalized, clinician-accepted clinical note content. Only notes with status `accepted`, `signed`, or `finalized` are exported. Draft notes and intermediate LLM-generated compositions are excluded.
| File Pattern | Source | Content |
|-------------|--------|---------|
| `note-{noteId}.txt` | `notes` table (`content` or `raw_text` column) | Complete note text as authored and accepted by the clinician |
| `note-section-{sectionType}.txt` | `note_sections` table (`section_text` column) | Individual note sections (e.g., HPI, Assessment, Plan) when structured section data is available |
**Interpretation:** These are the canonical clinical narrative. The note text represents the clinician's final documentation of the patient encounter. A corresponding `DocumentReference` FHIR resource in the NDJSON file links to this content.
### C-CDA XML Documents
**Location:** `patients/{patientId}/documents/ccda-{documentId}.xml` and `patients/{patientId}/documents/ccda-blob-{blobId}.xml`
**Format:** HL7 C-CDA R2.1 XML
**MIME Type:** `application/xml`
**Manifest Category:** `document-binary`
C-CDA (Consolidated Clinical Document Architecture) documents are exported in their native XML format. These include Continuity of Care Documents (CCD), referral notes, discharge summaries, and other C-CDA document types received from or generated for external systems.
| File Pattern | Source | Content |
|-------------|--------|---------|
| `ccda-{documentId}.xml` | `ccda_documents` table (`xml_content` column) | C-CDA XML stored inline in the database |
| `ccda-blob-{blobId}.xml` | `ccda_blobs` table + filesystem (`storage/ccda/{blobId}.xml`) | C-CDA XML stored as blob files, linked through `document_references_core` |
**Interpretation:** These are complete, self-contained C-CDA XML documents conforming to HL7 C-CDA R2.1. They can be parsed with any C-CDA-compliant reader. The internal structure follows the C-CDA template hierarchy (ClinicalDocument → component → sections → entries). A corresponding `DocumentReference` FHIR resource in the NDJSON file provides metadata about each document.
### Direct Message Attachments
**Location:** `patients/{patientId}/documents/direct-{messageId}-{filename}`
**Format:** Varies (PDF, XML, images, etc.)
**MIME Type:** As specified in `manifest.files[].mediaType`
**Manifest Category:** `document-binary`
Attachments from Direct secure health messaging exchanges. Direct is the healthcare-specific secure email protocol used for transmitting clinical documents between providers.
**Interpretation:** Each file is a clinical attachment that was sent or received as part of a Direct secure message exchange involving this patient. The `mediaType` in the manifest indicates the file format. Common types include C-CDA XML documents, PDF reports, and clinical images.
### Raw HL7 v2 Messages
**Location:** `interoperability/{patientId}/{messageId}.hl7`
**Format:** HL7 v2.x pipe-delimited text
**MIME Type:** `text/plain`
**Manifest Category:** `interoperability-raw`
Raw HL7 v2 messages are included as supplemental artifacts because the system's HL7-to-FHIR conversion is significantly lossy. The following information is present in raw HL7 but lost or partially lost during FHIR conversion:
| HL7 Segment | Content Lost in Conversion |
|-------------|---------------------------|
| NTE | Clinical notes/comments |
| OBR | Order/report details |
| NK1 | Next of kin / emergency contacts |
| IN1 | Insurance information |
| AL1 | Allergy data (separate from PID allergies) |
| DG1 | Diagnosis details |
| GT1 | Guarantor information |
| EVN | Event type and timestamps |
| Z-segments | All site-specific custom segments |
| PID (partial) | Race, ethnicity, language, religion, marital status, SSN, multiple names/identifiers |
| PV1 (partial) | Visit number, location details, discharge info, financial fields |
| OBX (partial) | Precise observation timestamps, complex coded types, OBR linkage |
**Interpretation:** These files contain the complete, unmodified HL7 v2 message as received by the system. Each file is a single HL7 message. Segments are separated by carriage-return (`\r`) characters. Fields within segments are pipe (`|`) delimited. The PID-3 field contains the patient identifier used to link the message to this patient.
To parse HL7 v2 messages, use an HL7 v2 parser library. The `MSH` (Message Header) segment identifies the message type and version.
---
## Data Provenance and Source Tagging
### The `urn:scribe-mutual:ehi:source` Tag
Some FHIR resources in the export were not stored natively as FHIR in the system's primary `fhir_resources` table. Instead, they were synthesized at export time from legacy or supplemental data stores to ensure complete DRS coverage. These resources carry a provenance tag:
```json
{
"meta": {
"tag": [
{
"system": "urn:scribe-mutual:ehi:source",
"code": "patient_conditions"
}
]
}
}
```
| Tag System | Tag Code (examples) | Meaning |
|-----------|---------------------|---------|
| `urn:scribe-mutual:ehi:source` | `conditions_core` | Resource was synthesized from the `conditions_core` projection table |
| `urn:scribe-mutual:ehi:source` | `patient_conditions` | Resource was synthesized from the unified fact model `patient_conditions` table |
| `urn:scribe-mutual:ehi:source` | `observations_core` | Resource was synthesized from the `observations_core` projection table |
| `urn:scribe-mutual:ehi:source` | `patient_observations` | Resource was synthesized from `patient_observations` |
| `urn:scribe-mutual:ehi:source` | `medication_requests_core` | Resource was synthesized from `medication_requests_core` |
| `urn:scribe-mutual:ehi:source` | `patient_medications` | Resource was synthesized from `patient_medications` |
| `urn:scribe-mutual:ehi:source` | `allergies_core` | Resource was synthesized from `allergies_core` |
| `urn:scribe-mutual:ehi:source` | `patient_allergies` | Resource was synthesized from `patient_allergies` |
| `urn:scribe-mutual:ehi:source` | `procedures_core` | Resource was synthesized from `procedures_core` |
| `urn:scribe-mutual:ehi:source` | `patient_procedures` | Resource was synthesized from `patient_procedures` |
| `urn:scribe-mutual:ehi:source` | `immunizations_core` | Resource was synthesized from `immunizations_core` |
| `urn:scribe-mutual:ehi:source` | `patient_immunizations` | Resource was synthesized from `patient_immunizations` |
| `urn:scribe-mutual:ehi:source` | `patient_notifications` | Resource was synthesized from `patient_notifications` |
| `urn:scribe-mutual:ehi:source` | `direct_messages` | Resource was synthesized from `direct_messages` |
| `urn:scribe-mutual:ehi:source` | `calendar_events` | Resource was synthesized from `calendar_events` |
| `urn:scribe-mutual:ehi:source` | `advance_directives` | Resource was synthesized from `advance_directives` |
| `urn:scribe-mutual:ehi:source` | `document_references_core` | Resource was synthesized from `document_references_core` |
**Resources without this tag** were stored natively as FHIR R4 in the system's canonical `fhir_resources` store and are exported as-is.
### Interpreting Synthesized Resources
Synthesized (fallback) resources contain the same FHIR R4 fields as canonical resources but may have fewer populated fields because the source data store does not capture all FHIR attributes. The clinical content (codes, dates, statuses) is faithfully mapped. The following table shows the field mapping from legacy stores to FHIR:
| Legacy Field | FHIR Field | Applies To |
|-------------|------------|------------|
| `primary_code` | `code.coding[].code` | Condition, Observation, Procedure |
| `primary_display` | `code.coding[].display` and `code.text` | Condition, Observation, Procedure |
| `primary_code_system` | `code.coding[].system` | Condition, Observation, Procedure |
| `clinical_status` | `clinicalStatus.coding[].code` | Condition, AllergyIntolerance |
| `verification_status` | `verificationStatus.coding[].code` | AllergyIntolerance |
| `onset_datetime` / `onset_date` | `onsetDateTime` | Condition |
| `recorded_date` | `recordedDate` | Condition, AllergyIntolerance |
| `observation_code` | `code.coding[].code` | Observation |
| `effective_datetime` | `effectiveDateTime` | Observation |
| `med_code` / `medication_code` | `medicationCodeableConcept.coding[].code` | MedicationRequest |
| `med_display` / `medication_display` | `medicationCodeableConcept.coding[].display` | MedicationRequest |
| `med_code_system` / `medication_code_system` | `medicationCodeableConcept.coding[].system` | MedicationRequest |
| `authored_on` | `authoredOn` | MedicationRequest |
| `substance_code` | `code.coding[].code` | AllergyIntolerance |
| `substance_display` | `code.coding[].display` | AllergyIntolerance |
| `procedure_code` | `code.coding[].code` | Procedure |
| `performed_datetime` / `performed_date` | `performedDateTime` | Procedure |
| `vaccine_code` | `vaccineCode.coding[].code` | Immunization |
| `vaccine_display` | `vaccineCode.coding[].display` | Immunization |
| `occurrence_datetime` / `occurrence_date` | `occurrenceDateTime` | Immunization |
| `start_utc` | `start` | Appointment |
| `end_utc` | `end` | Appointment |
| `description` / `title` | `description` | Appointment |
| `sent_at` / `created_at` | `sent` | Communication |
| `body` / `body_text` / `title` / `subject` | `payload[].contentString` | Communication |
---
## Deduplication and Merge Strategy
When data for the same clinical concept exists in both the canonical FHIR store and a legacy table, the export applies a deduplication strategy to prevent duplicate records:
1. **Canonical FHIR resources are preferred.** Data from the `fhir_resources` table is always included first.
2. **Fallback resources are added only when not already represented.** The deduplication key is built from the resource's clinical semantics (code + date + status), not just the database ID.
3. **Semantic deduplication keys by resource type:**
| Resource Type | Dedup Key Components |
|---------------|---------------------|
| Condition | `code` + `onsetDateTime` + `recordedDate` |
| Observation | `code` + `effectiveDateTime` + `status` |
| MedicationRequest | `medicationCodeableConcept` + `authoredOn` + `status` |
| AllergyIntolerance | `code` + `recordedDate` + `clinicalStatus` |
| Procedure | `code` + `performedDateTime` + `status` |
| Immunization | `vaccineCode` + `occurrenceDateTime` + `status` |
| Communication | `sent` + `status` + `subject.reference` |
| Appointment | `start` + `end` + `status` |
| Consent | `status` + `scope` + `patient.reference` |
If neither the semantic key nor a direct ID match is found, the fallback resource is included with its source tag, ensuring no patient data is lost.
---
## Null Handling and Optional Fields
- **Absent fields** are omitted from the JSON entirely (not present as `null` values). Per FHIR R4 rules, an absent field means "no information available."
- **Explicit `null`** is not used in FHIR resource JSON. If a field has no value, it is omitted.
- **Empty arrays** (`[]`) are omitted.
- **Empty strings** (`""`) are omitted.
- **Date precision varies.** Dates may be `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`. DateTimes include time: `YYYY-MM-DDThh:mm:ss.sssZ` (UTC) or with timezone offset.
- **The `id` and `resourceType` fields are always present** on every resource.
---
## Importing and Interpreting Export Data
### For Receiving EHR Systems
1. **Parse `clinical.ndjson` line by line.** Each line is an independent FHIR R4 resource.
2. **Use `resourceType` to route each resource** to the appropriate handler in your system.
3. **Check `meta.tag`** for the `urn:scribe-mutual:ehi:source` system. If present, the resource was synthesized from a legacy store and may have fewer populated fields than a natively-stored FHIR resource.
4. **Resolve references** using the `id` field. References between resources use the format `ResourceType/id` (e.g., `Patient/01HXYZ...`).
5. **Import supplemental files** alongside their FHIR metadata. `DocumentReference` resources in the NDJSON describe the supplemental documents in `patients/{patientId}/documents/`.
6. **Parse C-CDA XML** with a C-CDA R2.1 compliant parser for full clinical document content.
7. **Parse HL7 v2 messages** with an HL7 v2 parser if you need the complete interoperability record.
### For Data Analysts and Researchers
1. **NDJSON can be loaded into any JSON-processing tool** (Python `json`, `jq`, Spark, BigQuery, etc.).
2. **Each line is self-contained** — no need to correlate across lines to understand a single resource.
3. **`coding[].code`** is the primary machine-readable identifier for clinical concepts. Use `coding[].system` to determine which terminology database to look up the code in.
4. **`text` and `display`** fields provide human-readable labels but should not be used as primary keys.
### For Certification Auditors
1. **All 18 canonical FHIR resource types** listed in Section 5 are represented in the NDJSON when data exists for that domain.
2. **Supplemental artifacts** preserve information that would be lost in FHIR conversion (see Section 6).
3. **The `manifest.json` file** provides a machine-readable inventory of all exported content with checksums for integrity verification.
4. **No data is silently dropped.** The [DRS inventory](b10-drs-inventory.md) documents every include/exclude decision with rationale.
---
## FHIR R4 Conformance Notes
- All FHIR resources conform to the **FHIR R4 (v4.0.1)** specification published by HL7 International.
- Resources use **US Core profiles** where applicable (Patient, Condition, Observation, etc.).
- The NDJSON media type is `application/fhir+ndjson` as registered per FHIR Bulk Data specification.
- Resource identifiers (`id` field) use **ULID** format (Universally Unique Lexicographically Sortable Identifier), which is a valid FHIR `id` type.
- All timestamps are **ISO 8601** formatted.
- The FHIR specification is available at [https://hl7.org/fhir/R4/](https://hl7.org/fhir/R4/).
---
## Change Log
| Date | Version | Changes |
|------|---------|---------|
| 2026-06-24 | 1.0 | Initial data dictionary created with field definitions for all 18 canonical resource types, 4 supplemental file types, coding system reference, provenance tagging, deduplication strategy, and interpretation guidance |