Clinical decision support in oncology pulls from the terminology server constantly: chemotherapy regimen lookup, staging-code validation, vocabulary-driven order sets, and pharmacy-side dose checking. Two FHIR terminology operations carry most of that traffic, `$expand` and `$validate-code`. Choosing which one a CDS path uses is not just a spec question; the operational latency and the implementation effort differ enough that the wrong choice creates a bottleneck. For more on healthcare integration, the broader reference covers the related decisions.
What Each Operation Actually Does
`$expand` materializes a ValueSet into the full list of concepts it contains. A CDS step that needs the universe of valid AJCC TNM combinations or the full list of approved chemotherapy regimens calls `$expand` once, caches the result, and answers downstream queries from the cached set.
`$validate-code` answers a single yes-or-no question: is this specific code part of this specific ValueSet, optionally with a display-name check. A CDS step that needs to confirm the code on an incoming order belongs to the formulary calls `$validate-code` per order with no caching layer.
The operations look similar at the API level. They diverge meaningfully under production load.
Where Oncology CDS Pushes the Choice One Way or the Other
Three oncology CDS scenarios surface the trade-off. Regimen lookup at order time: the oncology order entry has to know whether the selected regimen is in the institution's approved list. `$validate-code` wins because the question is a single boolean per order. Staging-code dropdown population: when the clinician opens the AJCC stage picker, the UI needs the full list of valid combinations. `$expand` wins because the result drives a multi-option select. Toxicity-grade validation against CTCAE: the CDS path checks each toxicity-grade entry as it arrives. `$validate-code` per entry is cheaper than `$expand` once and caching, since the CTCAE value set is large enough that caching it is non-trivial.
A useful rule for oncology CDS: use `$expand` when the answer drives a UI selection, use `$validate-code` when the answer is a yes-or-no gate. The latency profile and the caching story match this rule cleanly.
How to Architect Around the Choice
Most production oncology CDS stacks end up using both. The order-entry path uses `$validate-code` because the answer is a gate. The UI-population path uses `$expand` because the answer is a list. The terminology server has to be reasonably fast on both, but the choice of which operation a given CDS step uses changes the caching design and the failure-mode behavior.
The oncology cornerstone walks through the broader server-selection framework, and the genomics variant walkthrough gets into a related operation-choice question for a different vocabulary set.
The deciding factor is not which operation is better in the abstract. It is which one matches the question the CDS step is actually asking. Getting that right reduces terminology-server load by an order of magnitude in busy oncology services, which is more impactful than picking a different server.
The trick is to map each CDS step against the question it is actually asking, then pick `$expand` or `$validate-code` based on whether the answer drives a UI list or a single decision gate. That mapping done well changes the terminology-server load profile more than any other architectural choice the team can make.
Most production oncology CDS stacks end up using a mix of the two operations, with the choice mapped against the question each CDS step is asking. The team that documents that mapping explicitly avoids the slow drift where every CDS step uses the same operation regardless of fit.
Oncology services that document which operation each CDS step uses save themselves a slow refactor later. The discipline of mapping operation choice against question type pays back as the CDS catalog grows from a handful of rules in year one to dozens by year three.
