Use ServiceRequest.reasonCode for "Diagnostic" (free-text now, coded later)

[lionel-cremer]

The “Diagnostic” field is currently a free-text input and is mapped to ServiceRequest.note.

According to the IG, the diagnosis (or justification) of the requested service is expected in ServiceRequest.reasonCode (see IG extract).

The BeSafeShare team’s intention is to move this field to a coded value set (as already mentioned in the IG > see screenshot), but we’d like to avoid changing the target FHIR element later on.

Suggested approach

Always map Diagnostic to ServiceRequest.reasonCode, even when the content is free-text.

Proposed structure:

"reasonCode":[
  {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "261004008",
        "display": "Diagnostic intent (qualifier value)"
      }
    ],
    "text": "Prescriber free-text input"
  }
]

Why this helps

• Keeps the mapping aligned with the IG from day one
• Avoids a breaking change for integrators when switching to coded diagnostics
• Keeps note for actual narrative comments instead of clinical intent

[lionel-cremer]

Below is a factual list of IG changes to apply, summarizing what was agreed during the meeting between INAMI, eHealth and Smals on 02 February.

Agreed IG changes

Use ServiceRequest.reasonCode to store the diagnosis instead of the ServiceRequest.note, as already described in the IG.

To Do

• Create ValueSet DRP Diagnostic
  • Initial content:
    • 439401001 | Diagnosis (observable entity)
• Remove ValueSet BeVSRequestNoteType which is replaced by DRP Note Type

Usage

• ServiceRequest.reasonCode remains free-text capable for now.
• This ValueSet is designed to evolve towards a fully coded diagnosis list in future releases.
• When none of the codes (future list) will be relevant enough to express the diagnosis, then the code '439401001' will be used to indicate an “other / free-text diagnosis”.
• The same mechanism will be reused, ensuring a single and consistent approach for current and future needs.

Binding constraints

As requested by eHealth, BeSafeShare and José, bindings on the different profiles of the ServiceRequest in the IG are illustrative only and permissive, so no binding necessary to indicate where this code must be stored.

[costateixeira]

1. Servicerequest.reasonCode already supports free text - we do not need to add the 439401001 code. In fact, adding that code seems contrary to the expected list (because the valueset would contain 439401001 (observable entity, where it would normally be a finding, or a disorder. In short, we don't necessarily need a code for "Other diagnosis" and this code isn't it, and we don't need it). 2. for replacing the ValueSet - do you confirm you want to remove snomed? was business agreeing with this?

…

On Wed, Feb 4, 2026 at 10:54 AM lionel-cremer ***@***.***> wrote: *lionel-cremer* left a comment (hl7-be/referral#481) <#481 (comment)> Below is a factual list of IG changes to apply, summarizing what was agreed during the meeting between INAMI, eHealth and Smals on 02 February. Agreed IG changes Use ServiceRequest.reasonCode to store the diagnosis instead of the ServiceRequest.note, as already described in the IG. To Do - Create ValueSet *DRP Diagnostic* - Initial content: - 439401001 | Diagnosis (observable entity) - Remove ValueSet BeVSRequestNoteType <https://build.fhir.org/ig/hl7-be/referral/branches/nursing-pilot/ValueSet-be-vs-request-note-type.html> which is replaced by DRP Note Type <https://build.fhir.org/ig/hl7-be/referral/branches/nursing-pilot/ValueSet-be-vs-note-type.html> Usage - ServiceRequest.reasonCode remains free-text capable for now. - This ValueSet is designed to evolve towards a fully coded diagnosis list in future releases. - When none of the codes (future list) will be relevant enough to express the diagnosis, then the code '439401001' will be used to indicate an “other / free-text diagnosis”. - The same mechanism will be reused, ensuring a single and consistent approach for current and future needs. Binding constraints As requested by eHealth, BeSafeShare and José, bindings on the different profiles of the ServiceRequest in the IG are illustrative only and permissive. — Reply to this email directly, view it on GitHub <#481 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD3HUUHK4T5P5DINW47BSGD4KG6UHAVCNFSM6AAAAACTJMCBUSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNBWGQZTGOJVG4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[lionel-cremer]

1. The point is not to “code the diagnosis” today, but to qualify what a given free-text represents.
   ServiceRequest.reasonCode does allow free text, but if multiple business fields are mapped to reasonCode and are all free text, consuming systems have no way to distinguish their meaning.

Concrete example

Imagine the following business inputs on a prescription:

• Medical diagnosis (free text)
• Motivation / justification (free text)

If both are mapped as free text to ServiceRequest.reasonCode, the resulting payload looks like:

"reasonCode": [
  { "text": "Type 2 diabetes with poor glycemic control" },
  { "text": "Patient needs additional follow-up after hospital discharge" }
]

From a system perspective (UHMEP, integrators, ...):

• both entries are just free text
• there is no way to know which one is the diagnosis and which one is the motivation
• any downstream logic becomes ambiguous or impossible

What the code brings (even with free text)
By adding a code, we make the intent explicit:

"reasonCode": [
  {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "439401001",
        "display": "Diagnosis"
      }
    ],
    "text": "Type 2 diabetes with poor glycemic control"
  },
  { 
     "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "363882003",
        "display": "Motivation"
      }
    ],
    "text": "Patient needs additional follow-up after hospital discharge"
  }
]

Here:

• the text stays free
• the code does not pretend to be the diagnosis itself
• it simply says: “this free text represents a diagnosis”

This allows:

• deterministic interpretation by systems,
• a single, consistent pattern today,
• and a smooth evolution later towards a fully coded diagnosis list without changing the structure.

2. About the choice of code
   The initial suggestion was to used the one currently present in the IG: 261004008 | Diagnostic intent (qualifier value).
   But Delphine ask to change for : 439401001 | Diagnosis (observable entity).
   If you're not confident with this code, I've no objection to use a more generic one like "404684003 | Clinical finding (finding)" or an internal code. The usage of a "high level" code has been decided for other "free-text" fields like in the ValueSet "DRP Sample Substance Type" or "DRP Parameter Type".

[costateixeira]

IIRC Medical diagnosis (free text) would be in supportingInfo, right?

…

On Wed, Feb 4, 2026 at 12:42 PM lionel-cremer ***@***.***> wrote: *lionel-cremer* left a comment (hl7-be/referral#481) <#481 (comment)> 1. The point is not to “code the diagnosis” today, but to qualify what a given free-text represents. ServiceRequest.reasonCode does allow free text, but if multiple business fields are mapped to reasonCode and are all free text, consuming systems have no way to distinguish their meaning. Concrete example Imagine the following business inputs on a prescription: - Medical diagnosis (free text) - Motivation / justification (free text) If both are mapped as free text to ServiceRequest.reasonCode, the resulting payload looks like: "reasonCode": [ { "text": "Type 2 diabetes with poor glycemic control" }, { "text": "Patient needs additional follow-up after hospital discharge" } ] From a system perspective (UHMEP, integrators, ...): - both entries are just free text - there is no way to know which one is the diagnosis and which one is the motivation - any downstream logic becomes ambiguous or impossible What the code brings (even with free text) By adding a code, we make the intent explicit: "reasonCode": [ { "coding": [ { "system": "http://snomed.info/sct", "code": "439401001", "display": "Diagnosis" } ], "text": "Type 2 diabetes with poor glycemic control" }, { "coding": [ { "system": "http://snomed.info/sct", "code": "363882003", "display": "Motivation" } ], "text": "Patient needs additional follow-up after hospital discharge" } ] Here: - the text stays free - the code does not pretend to be the diagnosis itself - it simply says: “this free text represents a diagnosis” This allows: - deterministic interpretation by systems, - a single, consistent pattern today, - and a smooth evolution later towards a fully coded diagnosis list without changing the structure. 2. About the choice of code The initial suggestion was to used the one currently present in the IG: 261004008 | Diagnostic intent (qualifier value). But Delphine ask to change for : 439401001 | Diagnosis (observable entity). If you're not confident with this code, I've no objection to use a more generic one like "404684003 | Clinical finding (finding)" or an internal code. The usage of a "high level" code has been decided for other "free-text" fields like in the ValueSet "DRP Sample Substance Type <https://build.fhir.org/ig/hl7-be/referral/branches/nursing-pilot/ValueSet-be-vs-sample-substance-type.html>" or "DRP Parameter Type <https://build.fhir.org/ig/hl7-be/referral/branches/nursing-pilot/ValueSet-be-vs-parameter-type.html> ". — Reply to this email directly, view it on GitHub <#481 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD3HUUHKIKXFC7QACHTVLSL4KHLJZAVCNFSM6AAAAACTJMCBUSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNBWHE2TAOJQGY> . You are receiving this because you commented.Message ID: ***@***.***>

[lionel-cremer]

From my understanding, whether the diagnosis is mapped to reasonCode, supportingInfo, or any other repeatable element is not your main concern. Your concern is about using a code + a free-text.

But the problem is that as soon as multiple business fields are mapped as free text to the same FHIR element, systems cannot distinguish their meaning anymore.

Regarding the field ".reasonCode", at this stage, this is indeed a hypothesis, but the reasoning comes directly from our experience with orderDetail, where the exact same issue already occurred.

Adding a simple qualifying code proved to be a reliable way to make the content unambiguous.

Introducing such a code now provides a solution that is valid both today and in the future.
Waiting for the problem to reappear before adding this safeguard would create a risk for integrators, who would then have to support two different approaches over time.

From our perspective, proactively adding this qualification mechanism is the safer and more professional option.

Out of curiosity, how would you suggest addressing this ambiguity if it were to occur today for the field ".reasonCode"?

[costateixeira]

The concern is that we don't need to use a code to allow free text. And if we use a code, the code should not "categorise" the element ocurrence, e.g. to say "this entry is about diagnosis". And if we would use a code, the code should be in the same category or the top concept as the other ones, for example
91720002 | Body substance (substance)
256897009 | Saliva (substance) |

"Diagnosis" is an observable entity and is not in the same dimension as all the other codes we would have in reasonCode - "diabetes, headache, fracture..." which are disorders, or findings..

So, if we have a "other/not specified diagnosis" code - using it is optional and interoperable. If not, we should not use .code to categorize the .text.

Out of curiosity, how would you suggest addressing this ambiguity if it were to occur today for the field ".reasonCode"?

that is why i asked - if we dont use the same element to contain diferent types of information, the problem doesn't exist, right?
If we have 2 condition in reasoncode, then the interpretation is "patient needs this service because they have these 2 conditions"

Adding a simple qualifying code proved to be a reliable way to make the content unambiguous.
Introducing such a code now provides a solution that is valid both today and in the future.

Yes, but seems an immediate and local invention, not agreed, not interoperable, difficult to maintain. Not really "professional" nor "safer"

[lionel-cremer]

Thanks, that helps — I think we are actually aligned here.

I agree that we should not use a code to categorise the element arbitrarily, and that the code should stay in the same semantic dimension as the other entries (finding / disorder).

What we are looking for is exactly what you mention:
an “other / not specified diagnosis” code, used optionally, to make explicit that a given free text represents a diagnosis when no more specific coding is available.

This would:

• remain interoperable,
• avoid misusing a code like “Diagnosis (observable entity)” as a category,
• and still allow systems to distinguish intent when free text is used.

The goal is not to force this code everywhere, but to have a single, consistent pattern that works today with free text and can smoothly evolve towards more specific coded diagnoses later.

Would you see this as an acceptable compromise, assuming we agree on the appropriate code ?

Does the code "404684003 | Clinical finding (finding)" a good candidate as it's a finding?

[costateixeira]

finding is one thing, but we would need symptom as well. and others. If it were needed, we could do that. But there is no need, is there?

…

On Wed, Feb 4, 2026 at 2:27 PM lionel-cremer ***@***.***> wrote: *lionel-cremer* left a comment (hl7-be/referral#481) <#481 (comment)> Thanks, that helps — I think we are actually aligned here. I agree that we should not use a code to categorise the element arbitrarily, and that the code should stay in the same semantic dimension as the other entries (finding / disorder). What we are looking for is exactly what you mention: an “other / not specified diagnosis” code, used optionally, to make explicit that a given free text represents a diagnosis when no more specific coding is available. This would: - remain interoperable, - avoid misusing a code like “Diagnosis (observable entity)” as a category, - and still allow systems to distinguish intent when free text is used. The goal is not to force this code everywhere, but to have a single, consistent pattern that works today with free text and can smoothly evolve towards more specific coded diagnoses later. Would you see this as an acceptable compromise, assuming we agree on the appropriate code ? Does the code "404684003 | Clinical finding (finding)" a good candidate as it's a finding? — Reply to this email directly, view it on GitHub <#481 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD3HUUHHKCZWDGCY3IGUOYL4KHXVJAVCNFSM6AAAAACTJMCBUSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTQNBXGQ2TIMJSGU> . You are receiving this because you commented.Message ID: ***@***.***>

[costateixeira]

We will use freetext as "normal" - without any auxilliary code