RT FHIR CarePlan Profile
EverOncologyRTCarePlan FHIR profile for radiation therapy.
| Field | Value |
|---|---|
| Profile name | EverOncologyRTCarePlan |
| Canonical URL | https://ever.med/fhir/StructureDefinition/oncology-rt-careplan |
| Version | 0.1.0 |
| Status | draft |
| FHIR base | R4 (4.0.1) |
| Profiles base | CarePlan |
| Conforms to / aligns with | HL7 mCODE (where applicable), IHE Radiation Oncology |
| Companion spec | BIA-RT-1 (claim vocabulary) |
| Date | 2026-05-07 |
1. Scope
EverOncologyRTCarePlan constrains FHIR CarePlan to represent a complete radiation oncology Course-of-treatment with phase/cycle decomposition, prescription detail, genomic attestation references (BIA-RT-1), tumor-conference linkage, and care-team structure sufficient for medOS oncology workflows.
It is the FHIR-side projection of the medOS internal event-sourced treatment_plan entity. The profile is exchange-format; the event log is the source of truth.
2. Why a profile and not a custom resource
Three reasons:
- Interoperability. Any FHIR-aware system (mCODE-conformant US oncology platforms, Japanese partner systems via FHIR-JP, Thai HIN gateway) can read it.
- Existing tooling. FHIR validators, code generators, server frameworks all work out-of-the-box.
- mCODE alignment. mCODE has settled on
Procedurefor delivered RT (mcode-cancer-related-radiation-procedure,mcode-radiotherapy-course-summary,mcode-radiotherapy-treatment-phase). mCODE is light on the planning side, which is exactly the gap this profile fills. Together with the mCODE delivery profiles, you get end-to-end coverage.
3. Conformance
A resource asserts conformance to this profile via meta.profile:
{ "meta": { "profile": ["https://ever.med/fhir/StructureDefinition/oncology-rt-careplan"] } }
Implementations claiming Full conformance MUST satisfy all MS (Must Support) elements, all extensions marked REQUIRED, and the slicing rules in §6.
4. Differential — base CarePlan constraints
| Element | Card. | Type | Constraint |
|---|---|---|---|
meta.profile |
1…1 | canonical | MUST include this profile’s URL |
status |
1…1 | code | MS — draft | active | on-hold | revoked | completed | entered-in-error |
intent |
1…1 | code | Fixed: plan for proposed, order once approved |
category |
1…* | CodeableConcept | MUST include http://snomed.info/sct|108290001 (radiotherapy procedure) AND http://ever.med/CodeSystem/care-plan-category|oncology-rt |
subject |
1…1 | Reference(Patient) | MS |
period |
1…1 | Period | MS — start = first fraction planned, end = last fraction planned (updated as plan evolves) |
created |
1…1 | dateTime | MS |
author |
1…1 | Reference(Practitioner) | MS — the responsible radiation oncologist |
careTeam |
1…* | Reference(CareTeam) | MS — single CareTeam covering RO, physicist, dosimetrist, RTT, oncology nurse |
addresses |
1…* | Reference(Condition) | MS — the cancer condition(s) being treated |
supportingInfo |
0…* | Reference(*) | MS — slicing per §5 |
goal |
0…* | Reference(Goal) | MS — local control, palliation, symptom relief, etc. |
activity |
1…* | BackboneElement | MS — slicing per §6 (phase decomposition) |
note |
0…* | Annotation |
basedOn MUST reference the RadiationServiceRequest that initiated the plan (covers TOR 3.12.1.1).
replaces (when present) MUST reference the predecessor EverOncologyRTCarePlan for replanning continuity.
5. supportingInfo slicing — tumor conferences and attestations
supportingInfo is sliced (open) on resource type and tag:
| Slice | Min…Max | Reference target | Purpose |
|---|---|---|---|
tumorConference |
0…* | ClinicalImpression (TumorBoard kind) |
Covers TOR 3.12.1.2; M:N to plan |
genomicAttestation |
0…* | DocumentReference carrying BIA-RT-1 VC |
Covers genomic decision basis |
priorImaging |
0…* | ImagingStudy |
Sim CT, diagnostic imaging |
priorTherapy |
0…* | Procedure | MedicationStatement |
Prior RT, prior systemic |
Tumor conference linkage (M:N). Each MDT discussion that touches the plan adds a supportingInfo entry. Conversely, the ClinicalImpression carries subject (patient) and an extension tumor-conference-plans-reviewed listing all plan IDs reviewed in that conference. This bidirectional linkage is the canonical M:N representation in FHIR.
"supportingInfo": [
{
"reference": "ClinicalImpression/mdt-2026-03-15-case-12",
"type": "ClinicalImpression",
"display": "Head & Neck MDT 2026-03-15"
},
{
"reference": "DocumentReference/genomic-vc-abc123",
"type": "DocumentReference",
"display": "BIA-RT genomic attestation (HPV+, ATM het, DPYD wt)"
}
]
6. activity slicing — phases / cycles
The core structural commitment of the profile.
activity is sliced (open) on extension[phase-number].valueInteger.
Each activity slice represents one Phase of the course (initial, boost, SIB, brachy insertion, re-irradiation, etc.). Slicing rules:
- Min cardinality 1, max unbounded.
- Slices ordered by phase number.
- Each slice MUST carry the
oncology-rt-phaseextension (§7.1) onactivity.detail. - Each slice’s
activity.detail.kindSHALL beServiceRequest. - Each slice’s
activity.detail.codeSHALL carry a procedure code from the radiation procedure value set (§9). - Each slice’s
activity.detail.scheduledTimingSHALL describe the fractionation pattern.
"activity": [
{
"extension": [
{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-phase",
"extension": [
{ "url": "phaseNumber", "valueInteger": 1 },
{ "url": "phaseName", "valueString": "Initial" },
{ "url": "intent", "valueCode": "definitive" }
]
}
],
"detail": {
"kind": "ServiceRequest",
"code": { "coding": [{ "system": "http://snomed.info/sct", "code": "1287742003", "display": "IMRT" }] },
"status": "in-progress",
"scheduledTiming": {
"repeat": {
"boundsPeriod": { "start": "2026-04-01", "end": "2026-05-09" },
"count": 25,
"frequency": 1,
"period": 1, "periodUnit": "d",
"dayOfWeek": ["mon","tue","wed","thu","fri"]
}
},
"performer": [{ "reference": "CareTeam/ct-vajira-rt-1" }],
"productCodeableConcept": {
"extension": [
{ "url": ".../oncology-rt-prescription", "valueReference": { "reference": "Basic/rx-phase1-..." } }
]
}
}
},
{
"extension": [
{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-phase",
"extension": [
{ "url": "phaseNumber", "valueInteger": 2 },
{ "url": "phaseName", "valueString": "Boost" },
{ "url": "intent", "valueCode": "definitive" }
]
}
],
"detail": { "...": "5 fx, 2 Gy/fx, sequential boost to GTV" }
}
]
The “phase” terminology is intentional. In RT, phase is the unambiguous term (initial, boost, SIB). cycle is borrowed from chemotherapy and is acceptable in patient-facing language but the FHIR structure SHOULD use phase to avoid confusion across modalities. The TOR’s “Cycle” requirement (3.12.1.6) is satisfied by phase scheduling — the system MAY surface “Cycle” labels in the UI for clinician familiarity.
7. Extension definitions
7.1 oncology-rt-phase (complex, on activity.detail)
Canonical: https://ever.med/fhir/StructureDefinition/oncology-rt-phase
Type: complex extension
Context: CarePlan.activity.detail
Cardinality: 1..1 within each activity slice
Sub-extensions:
phaseNumber : integer (1..1) 1-based ordinal
phaseName : string (1..1) free-form: Initial | Boost | SIB | Brachy_HDR_1 | ...
intent : code (1..1) curative | palliative | adjuvant | neoadjuvant | prophylactic | salvage | reirradiation
modality : code (1..1) EBRT-3DCRT | EBRT-IMRT | EBRT-VMAT | SBRT | SRS | Brachy-LDR | Brachy-HDR | Proton | Electron | TBI
technique : string (0..1) vendor-specific technique label
7.2 oncology-rt-prescription (resource-shaped, referenced from productCodeableConcept)
Modeled as a Basic resource (or a custom Logical Model) holding the RT prescription:
Fields:
totalDoseGy : decimal e.g., 50
fractionationGy : decimal e.g., 2
numberOfFractions : integer e.g., 25
fractionsPerWeek : integer e.g., 5
beamEnergy : string e.g., "6 MV", "Ir-192", "150 MeV"
targets[] : reference(BodyStructure)
organsAtRisk[] : { tissue, doseConstraint, volumeConstraint }
approvedBy : reference(Practitioner) the physicist co-sign
approvedDate : dateTime
protocolReference : reference(PlanDefinition) | uri RTOG/EORTC/local
A Basic carrier is acceptable for v0.1; v0.2 should evaluate moving to a PlanDefinition + ActivityDefinition pattern or a custom Logical Model published as an IG.
7.3 oncology-rt-genomic-attestation (complex, on CarePlan)
Canonical: https://ever.med/fhir/StructureDefinition/oncology-rt-genomic-attestation
Type: complex extension
Context: CarePlan (i.e., on the resource itself)
Cardinality: 0..1
Sub-extensions:
identityBinding : reference(DocumentReference) (1..1) REQUIRED — BIA-RT C-16
germlineRisk : reference(DocumentReference) (0..*) C-01, C-02, C-03
tumorMarkers : reference(DocumentReference) (0..*) C-04..C-08
radiosensitivityModel : reference(DocumentReference) (0..*) C-09, C-10
pharmacogenomics : reference(DocumentReference) (0..*) C-11, C-12
lateEffectRisk : reference(DocumentReference) (0..*) C-13, C-14
provenance : reference(DocumentReference) (1..*) C-15
Constraint: bia-rt-binding
Where any of {germlineRisk, tumorMarkers, radiosensitivityModel,
pharmacogenomics, lateEffectRisk} is present, identityBinding MUST be present
and MUST verify against all referenced credentials.
The referenced DocumentReference resources carry the BIA-RT-1 VC payloads as attachment.data (base64-encoded JSON-LD) or attachment.url pointing to the wallet-resolvable VC.
7.4 oncology-rt-replan-of (simple, on CarePlan)
Canonical: https://ever.med/fhir/StructureDefinition/oncology-rt-replan-of
Type: Reference(CarePlan)
Cardinality: 0..1
Context: CarePlan
Use: when an active plan is closed and a replan is opened mid-course
(setup change, anatomical change, toxicity-driven dose modification),
the new plan references the predecessor.
Distinct from CarePlan.replaces: replan-of is a soft link preserving
both plans as separate active artifacts during transition.
7.5 oncology-rt-clinical-intent (simple, on CarePlan)
Canonical: https://ever.med/fhir/StructureDefinition/oncology-rt-clinical-intent
Type: code
Cardinality: 1..1
Context: CarePlan
ValueSet: curative | palliative | adjuvant | neoadjuvant | prophylactic | salvage
This sits at the plan level (overall intent). Phase-level intent (§7.1) MAY differ for individual phases.
8. Required references — the linked resources
A complete EverOncologyRTCarePlan instance points to (or is pointed to by) the following:
| Resource | Direction | Profile | Purpose |
|---|---|---|---|
Patient |
CarePlan → | (any) | Subject |
Condition |
CarePlan → | mCODE Primary Cancer Condition | Diagnosis |
ServiceRequest |
CarePlan → (basedOn) |
EverRadiationServiceRequest |
The order — TOR 3.12.1.1 |
ClinicalImpression |
CarePlan → (supportingInfo) |
EverTumorBoardNote |
TOR 3.12.1.2 |
CareTeam |
CarePlan → | — | The RT team |
Goal |
CarePlan → | — | Clinical goals |
Appointment |
→ CarePlan (basedOn) |
EverRTFractionAppointment |
TOR 3.12.1.6 |
Procedure |
→ CarePlan (basedOn) |
mCODE Cancer-Related Radiation Procedure | Each delivered fraction |
Observation |
→ CarePlan (derivedFrom) |
mCODE Tumor Marker Test, etc. | Toxicity (CTCAE), QoL, dosimetry observations |
DocumentReference |
CarePlan → (extension) | — | BIA-RT VC payloads |
9. Code systems & value sets
The profile relies on:
- Procedures: SNOMED CT (1287742003 IMRT, 152181000119107 VMAT, etc.) plus a local CodeSystem
http://ever.med/CodeSystem/rt-procedurefor techniques not yet in SNOMED. - Modality:
http://ever.med/CodeSystem/rt-modality— covers EBRT-3DCRT, EBRT-IMRT, EBRT-VMAT, SBRT, SRS, Brachy-LDR, Brachy-HDR, Proton, Electron, TBI. - Intent:
http://ever.med/CodeSystem/rt-intent— curative, palliative, adjuvant, neoadjuvant, prophylactic, salvage, reirradiation. - Body sites: ICD-O-3 topography codes for tumor location, BodyStructure references for target volumes (CTV, PTV, GTV), AAPM TG-263 nomenclature for organ-at-risk naming (covers TOR 3.12.1.4 — radiation coding).
- Toxicity: NCI CTCAE v5.0 via
http://terminology.hl7.org/CodeSystem/ctcae. - Billing codes: ICD-9-CM Vol 3 / TMLT for Thai context, CPT for US, K-codes for Japan — carried on the
Procedureresources for delivered fractions, not on the plan.
10. Mapping to TOR requirements (3.12.1.x)
| TOR | Spec satisfaction |
|---|---|
| 3.12.1.1 สั่งรายการการตรวจรักษาด้วยรังสี | EverRadiationServiceRequest referenced from CarePlan.basedOn; the request initiates the plan |
| 3.12.1.2 Tumor Conference notes | ClinicalImpression (kind: TumorBoard) referenced via supportingInfo[tumorConference]; M:N supported via bidirectional reference |
| 3.12.1.3 Continuous history (cycle / same plan) | Single CarePlan.id carries treatment_plan_id semantics; all child Appointments and Procedures basedOn the plan; history view = _revinclude on Plan id |
| 3.12.1.4 Radiation coding | Procedure codes on activity.detail.code; AAPM TG-263 OAR naming; CTCAE for toxicity; billing codes on delivered Procedure resources |
| 3.12.1.6 Cycle-based appointment | activity[].detail.scheduledTiming.repeat declares the pattern; appointment generator service produces Appointment resources with basedOn → CarePlan and a custom phase extension |
3.12.1.5 is reserved (likely a TOR numbering gap) — confirm with Vajira documentation.
11. Example instance (abbreviated)
{
"resourceType": "CarePlan",
"id": "rt-plan-h-and-n-2026-04-001",
"meta": {
"profile": ["https://ever.med/fhir/StructureDefinition/oncology-rt-careplan"]
},
"extension": [
{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-clinical-intent",
"valueCode": "curative"
},
{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-genomic-attestation",
"extension": [
{ "url": "identityBinding",
"valueReference": { "reference": "DocumentReference/vc-bind-001" } },
{ "url": "tumorMarkers",
"valueReference": { "reference": "DocumentReference/vc-hpv-001" } },
{ "url": "germlineRisk",
"valueReference": { "reference": "DocumentReference/vc-atm-001" } },
{ "url": "pharmacogenomics",
"valueReference": { "reference": "DocumentReference/vc-dpyd-001" } },
{ "url": "provenance",
"valueReference": { "reference": "DocumentReference/vc-provenance-001" } }
]
}
],
"status": "active",
"intent": "order",
"category": [
{ "coding": [
{ "system": "http://snomed.info/sct", "code": "108290001", "display": "Radiotherapy procedure" },
{ "system": "http://ever.med/CodeSystem/care-plan-category", "code": "oncology-rt" }
]}
],
"subject": { "reference": "Patient/p-12345678", "display": "P. R., F 54" },
"period": { "start": "2026-04-01", "end": "2026-05-16" },
"created": "2026-03-28T14:22:00+07:00",
"author": { "reference": "Practitioner/dr-radonc-vajira-01" },
"careTeam": [{ "reference": "CareTeam/ct-vajira-rt-1" }],
"addresses": [{ "reference": "Condition/c-oropharyngeal-scc-001" }],
"basedOn": [{ "reference": "ServiceRequest/sr-rt-001" }],
"supportingInfo": [
{ "reference": "ClinicalImpression/mdt-2026-03-15-case-12",
"display": "Head & Neck MDT 2026-03-15" }
],
"goal": [{ "reference": "Goal/g-local-control" }],
"activity": [
{
"extension": [{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-phase",
"extension": [
{ "url": "phaseNumber", "valueInteger": 1 },
{ "url": "phaseName", "valueString": "Initial" },
{ "url": "intent", "valueCode": "curative" },
{ "url": "modality", "valueCode": "EBRT-IMRT" },
{ "url": "technique", "valueString": "VMAT 2-arc" }
]
}],
"detail": {
"kind": "ServiceRequest",
"code": { "coding": [
{ "system": "http://snomed.info/sct", "code": "1287742003", "display": "IMRT" }
]},
"status": "in-progress",
"scheduledTiming": {
"repeat": {
"boundsPeriod": { "start": "2026-04-01", "end": "2026-05-09" },
"count": 25, "frequency": 1, "period": 1, "periodUnit": "d",
"dayOfWeek": ["mon","tue","wed","thu","fri"]
}
},
"performer": [{ "reference": "CareTeam/ct-vajira-rt-1" }],
"productCodeableConcept": {
"extension": [{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-prescription",
"valueReference": { "reference": "Basic/rx-phase1-001" }
}]
}
}
},
{
"extension": [{
"url": "https://ever.med/fhir/StructureDefinition/oncology-rt-phase",
"extension": [
{ "url": "phaseNumber", "valueInteger": 2 },
{ "url": "phaseName", "valueString": "Boost" },
{ "url": "intent", "valueCode": "curative" },
{ "url": "modality", "valueCode": "EBRT-IMRT" }
]
}],
"detail": {
"kind": "ServiceRequest",
"code": { "coding": [{ "system": "http://snomed.info/sct", "code": "1287742003" }]},
"status": "scheduled",
"scheduledTiming": {
"repeat": {
"boundsPeriod": { "start": "2026-05-10", "end": "2026-05-16" },
"count": 5, "frequency": 1, "period": 1, "periodUnit": "d",
"dayOfWeek": ["mon","tue","wed","thu","fri"]
}
}
}
}
]
}
12. Operations & query patterns
Get the continuous history of a plan (TOR 3.12.1.3):
GET [base]/CarePlan/{id}?_revinclude=Procedure:based-on
&_revinclude=Appointment:based-on
&_revinclude=Observation:derived-from
&_include=CarePlan:supporting-info
&_include=CarePlan:based-on
Returns plan + all delivered fractions + all appointments + all toxicity observations + tumor conference notes + the originating service request, in a single Bundle. The medOS UI renders this as the Treatment Lane and event feed of the Plan Cockpit.
Bulk-create appointments for a phase (TOR 3.12.1.6):
POST [base]/$rt-generate-appointments
{
"carePlanId": "rt-plan-...",
"phaseNumber": 1
}
Custom operation that reads the phase’s scheduledTiming and produces N Appointment resources, each with basedOn → CarePlan and extension[fractionNumber]. Idempotent on (carePlanId, phaseNumber).
Diff between plan versions (replan workflow):
GET [base]/CarePlan/{id}/_history/{vid1}
GET [base]/CarePlan/{id}/_history/{vid2}
medOS computes a JSON-Patch-shaped diff between phase prescriptions and renders the change set in the Plan Cockpit.
Patient view of own plans (Ever HealthWallet):
GET [base]/CarePlan?subject=Patient/{id}
&category=oncology-rt
&_sort=-period
&_summary=true
Lightweight summary the patient companion app reads.
13. mCODE alignment
This profile composes cleanly with mCODE:
- mCODE Primary Cancer Condition — referenced from
addresses. No conflict. - mCODE Cancer Stage Group — Observation, referenced by Condition. No conflict.
- mCODE Cancer-Related Radiation Procedure — represents delivered fractions; references this CarePlan via
basedOn. - mCODE Radiotherapy Course Summary — produced at end of treatment as a summary
Procedure, references this plan viapartOf. - mCODE Radiotherapy Treatment Phase — produced per phase at phase completion, references this plan and its specific phase activity.
The relationship: EverOncologyRTCarePlan is the prospective planning artifact; mCODE Course Summary / Treatment Phase are the retrospective delivery artifacts. Both are valuable; both should exist.
14. Implementation notes for medOS
- Source of truth. The medOS internal
treatment_planevent log is authoritative. The FHIR CarePlan is a projection produced by a serializer that folds events into the resource shape above.meta.versionIdandmeta.lastUpdatedreflect the latest event. - Event types that mutate the plan.
PlanCreated,PhaseAdded,PrescriptionApproved,PlanLocked,AppointmentsGenerated,PlanAmended,PhaseCompleted,PlanClosed,TumorConferenceLinked,GenomicAttestationAttached. Each event is reified as aProvenanceresource pointing to the resultingCarePlanversion. - Air-gapped operation (Vajira context). The plan and all referenced VCs MUST be fully resolvable within the air-gapped network. BIA-RT credentials are mirrored locally; revocation lists are pulled on a scheduled basis with TTL-expiry semantics so a network partition does not block clinical operations beyond the cache window.
- AI Safety Gate. Any AI-generated suggestion that would mutate the plan (auto-prescription, auto-replan trigger, auto-toxicity grade) MUST pass through the AI Safety Gate. The gate’s pass/fail decision is itself recorded as a
Provenanceresource on the resulting plan version, with the suggestion content and the gate’s reasoning. This is the audit trail that makes AI-assisted RT planning insurable and regulatable. - Multi-country localization. Code system bindings are layered: the profile binds types of codes (procedure, intent, modality), and a country pack supplies the country-specific values (TMLT for Thailand, ICD-9-CM Vol 3 for Japan, CPT for US). The profile remains stable; country packs swap.
- Patient-facing projection. Ever HealthWallet renders a stripped-down view of the CarePlan: phases as journey stops, period as timeline, status as plain language, dose-to-date as a fuel gauge. This view is a separate render of the same CarePlan resource — no parallel data structure.
15. Open questions for v0.2
- Brachytherapy modeling. Each insertion is closer to a
Procedurethan a phase. Should brachy use a differentactivityshape (one activity per insertion) or stay in the phase model? Probably the former — brachy gets its own activity slice variant. - Adaptive RT. Daily plan modification (online adaptive workflow on Ethos / MR-linac). Is each adaptive plan a new
EverOncologyRTCarePlanversion or a dailyProcedure-level deviation note? Initial leaning: daily deviation note up to a threshold; full replan beyond it. - PlanDefinition. Should institutional protocols (RTOG-1016, EORTC-XX, local Vajira H&N protocol) be encoded as
PlanDefinitionresources that instantiateEverOncologyRTCarePlan? Yes, in v0.2 — this gives protocol governance a first-class home. - Outcome reporting. PROMs, QoL, late-toxicity follow-up — all
Observation, allderivedFromthe CarePlan. Need a follow-up schedule slice onactivityfor the survivorship phase? Probably yes. - Compatibility with IHE Radiation Oncology. Map onto IHE-RO TDW-II (Treatment Delivery Workflow) for the actual delivery side; this profile sits one layer above.
16. Files to ship in the IG
For a publishable Implementation Guide:
fsh/
StructureDefinition-EverOncologyRTCarePlan.fsh
StructureDefinition-EverRadiationServiceRequest.fsh
StructureDefinition-EverTumorBoardNote.fsh
StructureDefinition-EverRTFractionAppointment.fsh
StructureDefinition-Extension-oncology-rt-phase.fsh
StructureDefinition-Extension-oncology-rt-prescription.fsh
StructureDefinition-Extension-oncology-rt-genomic-attestation.fsh
StructureDefinition-Extension-oncology-rt-replan-of.fsh
StructureDefinition-Extension-oncology-rt-clinical-intent.fsh
CodeSystem-rt-modality.fsh
CodeSystem-rt-intent.fsh
CodeSystem-rt-procedure.fsh
ValueSet-rt-modality.fsh
ValueSet-rt-intent.fsh
ValueSet-rt-procedure.fsh
examples/
careplan-h-and-n-curative.json
careplan-palliative-bone-mets.json
careplan-replan-mid-course.json
FSH (FHIR Shorthand) authoring is the path of least resistance; SUSHI compiles to the IG. Estimated effort: ~2 weeks for first publishable IG given the differential above.
End of BIA-RT-2 v0.1