use core::error::Error;
use core::fmt;
use fhir_types::r4::coding::Coding;
use fhir_types::r4::operations::code_system_lookup::CodeSystemLookupRequest;
use fhir_types::r4::operations::code_system_lookup::CodeSystemLookupResponse;
use fhir_types::r4::operations::concept_map_translate::ConceptMapTranslateRequest;
use fhir_types::r4::operations::concept_map_translate::ConceptMapTranslateResponse;
use fhir_types::r4::primitives;
use fhir_types::r4::primitives::Code;
use fhir_types::r4::primitives::Uri;
pub trait Terminology: fmt::Debug + Send + Sync {
fn translate(
&self,
request: &ConceptMapTranslateRequest,
) -> Result<ConceptMapTranslateResponse, TerminologyError>;
fn lookup(
&self,
_request: &CodeSystemLookupRequest,
) -> Result<Option<CodeSystemLookupResponse>, TerminologyError> {
Err(TerminologyError::NotConfigured)
}
fn display_fallback(&self) -> bool {
false
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct NoTerminology;
impl Terminology for NoTerminology {
fn translate(
&self,
_request: &ConceptMapTranslateRequest,
) -> Result<ConceptMapTranslateResponse, TerminologyError> {
Err(TerminologyError::NotConfigured)
}
}
#[derive(Debug, thiserror::Error)]
pub enum TerminologyError {
#[error("no terminology server is configured to translate through")]
NotConfigured,
#[error("the terminology server did not translate the code")]
Upstream {
#[source]
source: Box<dyn Error + Send + Sync>,
},
#[error("the coding carries no system and code to translate")]
Uncoded,
#[error("the translation is ambiguous: {concepts} distinct concepts are equivalent")]
Ambiguous {
concepts: usize,
},
}
pub fn request(url: &str, coding: &Coding) -> Result<ConceptMapTranslateRequest, TerminologyError> {
let system = text(coding.system.as_ref().map(|uri| &uri.value));
let code = text(coding.code.as_ref().map(|code| &code.value));
let (Some(system), Some(code)) = (system, code) else {
return Err(TerminologyError::Uncoded);
};
Ok(ConceptMapTranslateRequest {
url: Some(Uri::from(url)),
system: Some(Uri::from(system)),
code: Some(Code::from(code)),
version: text(coding.version.as_ref().map(|version| &version.value))
.map(primitives::String::from),
..ConceptMapTranslateRequest::default()
})
}
#[must_use]
pub fn lookup_request(system: &str, code: &str, version: Option<&str>) -> CodeSystemLookupRequest {
CodeSystemLookupRequest {
system: Some(Uri::from(system)),
code: Some(Code::from(code)),
version: version.map(primitives::String::from),
..CodeSystemLookupRequest::default()
}
}
pub fn accepted(
response: &ConceptMapTranslateResponse,
) -> Result<Option<Coding>, TerminologyError> {
if response.result.value != Some(true) {
return Ok(None);
}
let mut concepts: Vec<&Coding> = Vec::new();
for found in &response.r#match {
let equivalence = text(found.equivalence.as_ref().map(|code| &code.value));
if !matches!(equivalence, Some("equivalent" | "equal")) {
continue;
}
let Some(concept) = found.concept.as_ref() else {
continue;
};
if !concepts.iter().any(|held| same_concept(held, concept)) {
concepts.push(concept);
}
}
match concepts.as_slice() {
[] => Ok(None),
[concept] => Ok(Some((*concept).clone())),
more => Err(TerminologyError::Ambiguous {
concepts: more.len(),
}),
}
}
#[must_use]
pub fn translated(source: &Coding, concept: &Coding) -> Coding {
let display = concept
.display
.clone()
.filter(|display| text(Some(&display.value)).is_some())
.or_else(|| source.display.clone());
Coding {
system: concept.system.clone(),
version: concept.version.clone(),
code: concept.code.clone(),
display,
..Coding::default()
}
}
fn same_concept(left: &Coding, right: &Coding) -> bool {
text(left.system.as_ref().map(|uri| &uri.value))
== text(right.system.as_ref().map(|uri| &uri.value))
&& text(left.code.as_ref().map(|code| &code.value))
== text(right.code.as_ref().map(|code| &code.value))
}
fn text(value: Option<&Option<String>>) -> Option<&str> {
value
.and_then(Option::as_deref)
.filter(|text| !text.is_empty())
}
#[cfg(test)]
mod tests {
use super::NoTerminology;
use super::Terminology;
use super::TerminologyError;
use super::accepted;
use super::request;
use super::translated;
use fhir_types::r4::coding::Coding;
use fhir_types::r4::operations::concept_map_translate::ConceptMapTranslateRequest;
use fhir_types::r4::operations::concept_map_translate::ConceptMapTranslateResponse;
use fhir_types::r4::operations::concept_map_translate::ConceptMapTranslateResponseMatch;
use fhir_types::r4::primitives;
use fhir_types::r4::primitives::Boolean;
use fhir_types::r4::primitives::Code;
use fhir_types::r4::primitives::Uri;
fn coding(system: &str, code: &str, display: Option<&str>) -> Coding {
Coding {
system: Some(Uri::from(system)),
code: Some(Code::from(code)),
display: display.map(primitives::String::from),
..Coding::default()
}
}
fn found(equivalence: &str, concept: Coding) -> ConceptMapTranslateResponseMatch {
ConceptMapTranslateResponseMatch {
equivalence: Some(Code::from(equivalence)),
concept: Some(concept),
..ConceptMapTranslateResponseMatch::default()
}
}
fn answer(
result: bool,
matches: Vec<ConceptMapTranslateResponseMatch>,
) -> ConceptMapTranslateResponse {
ConceptMapTranslateResponse {
result: Boolean {
value: Some(result),
..Boolean::default()
},
r#match: matches,
..ConceptMapTranslateResponse::default()
}
}
#[test]
fn no_terminology_fails_closed() {
let outcome = NoTerminology.translate(&ConceptMapTranslateRequest::default());
assert!(
matches!(outcome, Err(TerminologyError::NotConfigured)),
"a run with no server refuses: {outcome:?}"
);
}
#[test]
fn the_request_carries_the_source_system_code_and_version() {
let mut source = coding("http://example.org/source", "S-1", Some("Source"));
source.version = Some(primitives::String::from("2026"));
let sent =
request("http://example.org/ConceptMap/a", &source).expect("the coding is coded");
assert_eq!(
sent.url.and_then(|uri| uri.value).as_deref(),
Some("http://example.org/ConceptMap/a")
);
assert_eq!(
sent.system.and_then(|uri| uri.value).as_deref(),
Some("http://example.org/source")
);
assert_eq!(
sent.code.and_then(|code| code.value).as_deref(),
Some("S-1")
);
assert_eq!(
sent.version.and_then(|version| version.value).as_deref(),
Some("2026")
);
assert_eq!(sent.targetsystem, None, "the map alone names the target");
}
#[test]
fn a_coding_with_no_system_is_refused_before_any_call() {
let source = Coding {
code: Some(Code::from("S-1")),
..Coding::default()
};
assert!(matches!(
request("http://example.org/ConceptMap/a", &source),
Err(TerminologyError::Uncoded)
));
}
#[test]
fn only_equivalent_and_equal_count() {
let target = coding("http://example.org/target", "T-1", Some("Target"));
for code in ["equivalent", "equal"] {
let concept = accepted(&answer(true, vec![found(code, target.clone())]))
.expect("one concept is no ambiguity");
assert_eq!(concept, Some(target.clone()), "{code} is a translation");
}
for code in [
"relatedto",
"wider",
"subsumes",
"narrower",
"specializes",
"inexact",
"unmatched",
"disjoint",
] {
let concept = accepted(&answer(true, vec![found(code, target.clone())]))
.expect("no accepted concept is no ambiguity");
assert_eq!(concept, None, "{code} is no translation");
}
}
#[test]
fn a_false_result_translates_to_nothing() {
let target = coding("http://example.org/target", "T-1", None);
let concept = accepted(&answer(false, vec![found("equivalent", target)]))
.expect("a false result is no ambiguity");
assert_eq!(concept, None);
}
#[test]
fn two_distinct_accepted_concepts_are_ambiguous() {
let first = coding("http://example.org/target", "T-1", None);
let second = coding("http://example.org/target", "T-2", None);
let outcome = accepted(&answer(
true,
vec![
found("equivalent", first.clone()),
found("equal", second),
found("equal", first),
],
));
assert!(
matches!(outcome, Err(TerminologyError::Ambiguous { concepts: 2 })),
"two concepts refuse: {outcome:?}"
);
}
#[test]
fn the_translated_display_wins_over_the_source_display() {
let source = coding("http://example.org/source", "S-1", Some("Source text"));
let concept = coding("http://example.org/target", "T-1", Some("Target display"));
let written = translated(&source, &concept);
assert_eq!(written, concept);
let bare = coding("http://example.org/target", "T-1", None);
assert_eq!(
translated(&source, &bare).display,
Some(primitives::String::from("Source text")),
"the source text stands in only when the concept names no display"
);
}
}