Simplified Formats (FLAT) completing partial DV_CODED_TEXT input

Specifications RM
, , ,
1

Hi!

The fun thing when trying to implement software (like Ehrtslib) from specifications is that you discover possible ambiguities in them; that is yet another reason to love new implementations!

The fairly recently added Simplified Formats §5.27 specification makes |value and |terminology optional for local/openehr codes, but does not say how a receiver should complete them. It marks |code as required, but does not say whether value-only input must be rejected, and is silent on a bare key with no suffix, input that matches nothing, and a |code/|value conflict. Actual implementations differ:

Input EHRbase 2.36.0 FerroEHR 5.5.0 Better web-template 5.0.1 (source)
|code only template default-language rubric template default-language rubric composition-language rubric (test)
|value only exact label match 422 stored without defining_code
bare key code, then label 422 treated as code; also accepts terminology::code::value
value-only/bare key, no match 422 422 bare key: exception; |value: stored without defining_code
|value = another code’s term value replaced by rubric sent value kept sent value kept

Language test:

With a template whose original language is Swedish, with English as an included translation (Region Stockholm chemotherapy symptom form), sending only |code with ctx/language set to en made EHRbase 2.36.0 and FerroEHR 5.5.0 store the Swedish rubric “Ja” instead of the English “Yes”, while the Better web-template library (3.2.9 and 5.0.1) stored “Yes”.

Sending an English |value “Yes” without |code in an English composition was rejected with 422 by EHRbase, which matches the text against the Swedish rubrics only (Swedish “Ja” was accepted in the same composition), and by FerroEHR, which requires |code for every coded value; the Better library accepted it but produced a DV_CODED_TEXT without defining_code. (Better was tested as a library only, not as a CDR, so the missing defining_code might be caught by validation in Better’s server. Test details)

Display text for DV_CODED_TEXT:

Can I assume defining_code.code_string and preferred_term must correspond, while value may differ to record what the user saw in the user interface (e.g. a synonym or form label), as intended by SPECPR-165 and the RM integration scenarios?

The RM data types design text instead requires the “exact term text”, else a DV_TEXT. EHRbase overwrites such a |value in FLAT and rejects it in canonical; FerroEHR keeps it, having reverted value = rubric enforcement as spec overreach (#254, #262, #1507). @ian.mcnicoll has proposed the same reading (11606, 5063, 1998). To @sebastian.iancu’s question regarding how to validate: validation applies to code_string and preferred_term; value is display text, and a value equal to another code’s term is a conflict and an error (Q4).

What ehrtslib currently does (PR #236):

  • |code only: rubric in the composition language.
  • codedTextMismatch: "reject" (default), "keep" or "correct", for case-only mismatches, no match, |value = another code’s term, and another language’s rubric.
  • Valid |code + unlisted |value is display text, per codedTextDisplayValue: "keep" (default, like Better and FerroEHR), "keep-and-set-preferred-term" (rubric into |preferred_term), or "replace-with-rubric" (EHRbase compatibility, not recommended).
  • These are options because ehrtslib can be used as a front end for, and converter between, platforms that behave differently. A CDR likely wants fewer or no options.

Questions:

  1. Should code-only completion be normative, using the composition language with the template default as fallback? (SPECPR-171 leaves the language to the implementation.)
  2. Is value-only or bare-key input conformant, or a receiver-side extension that producers must not rely on? If it is allowed, should matching be exact by default, with case-insensitive matching as an opt-in?
  3. Should value-only or bare-key input that matches nothing be rejected, or kept with a warning?
  4. When |value equals the term of a different code than |code, I suggest rejecting with an error by default. Agreed?
  5. Better parses bare keys as terminology::code::value, while its 2020 SDT description was terminology::code|value|. Neither is documented. Should one be documented, or both deprecated?
  6. Should the RM text be refined accordingly, so a valid |code with an unlisted |value is kept as display text?Se related alternatives in “Points for the SEC to decide” in Veredictum #718 issue by @rubentalstra.

After we have some feedback on the questions we can turn the outcome into a SPECITS problem report.