FHIR R4
Category: EHR interoperability standard
FHIR R4 is HL7's resource-based standard for exchanging health information. Convert-Pheno reads FHIR R4 JSON Bundles, resolves references, and groups supported resources by Patient. Current support covers generic R4 Bundles and the mCODE 4.0 oncology profile. The test fixtures do not cover every FHIR implementation guide.
What You Need
Supply one or more JSON or gzip-compressed JSON files. Each document must be a
FHIR Bundle with a standard R4 Bundle.type, an entry array, and at least
one Patient.
convert-pheno -ifhir bundle.json \
-obff --entities individuals biosamples datasets cohorts \
--out-dir bff_out/
Multiple Bundles may contribute resources to the same Patient. Relative,
absolute, and urn:uuid: references are supported. The clinical mapping is
built in. An optional compact Mapping V2 file
can override source-derived dataset and cohort metadata in entity-aware BFF
output. See the FHIR recipes for PXF and OMOP-CDM output.
What Is Converted
| FHIR resource | Main target content |
|---|---|
Patient | individual id, sex, birth date, vital status, supported ethnicity and birthplace extensions |
Condition | diseases, onset, resolution, and supported exclusion state |
Observation | quantitative or categorical measures, HPO phenotypic features, dates, methods, units, and reference ranges |
Procedure | interventions or procedures, body site, and date |
MedicationRequest, MedicationAdministration, MedicationStatement | treatments, route, and treatment timing |
Specimen | first-class BFF biosamples, collection details, and specimen-linked measurements |
ResearchStudy | source-derived dataset metadata |
Group | source-derived cohort metadata |
For field-level behavior, see FHIR to BFF.
mCODE
mCODE 4.0 is an oncology profile of FHIR R4,
not a separate input format. Use the same -ifhir command. Convert-Pheno
detects supported meta.profile URLs and maps primary-cancer stage from
Condition.stage or a referenced stage Observation. Other supported resources
continue through the generic FHIR mapper.
An explicitly different mCODE version is treated as generic FHIR R4 rather than interpreted using the 4.0-specific rule.
Terminology And Source Data
Known coding systems are converted to stable prefixes such as SNOMEDCT:,
LOINC:, RxNorm:, UCUM:, HP:, and NCIT:. A coding from another system
keeps a source-derived identifier. Text without a coding receives a local
FHIR: identifier; neither fallback claims an external ontology mapping.
By default, the Patient and associated resources are retained under
info.fhir, while each BFF biosample retains its source Specimen and linked
Observations. Use --no-source-info to omit those raw copies without removing
mapped fields.
FHIR input is currently non-streaming. All supplied Bundles and normalized patient records must fit in memory. This route does not read FHIR XML, Bulk Data NDJSON, or a live FHIR server. Arbitrary extensions and slices are not interpreted beyond the documented mappings.