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. Generic R4 and the mCODE 4.0 oncology profile are regression-tested; independent implementation coverage is still limited.
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. A mapping file is not
used. 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.