Proposal for ConceptReference

From HL7Wiki
Revision as of 14:16, 17 October 2019 by Jlyle (talk | contribs) (→‎Definition: added notes on candidate names)
Jump to navigation Jump to search

This page documents rationale for a proposed enhancement for FHIR, the creation of a new datatype called ConceptReference

Rationale

As of R4, it's pretty common to see this pattern in FHIR:

   MedicationRequest
   - reasonCode : CodeableConcept [0..*] //  Reason or indication for ordering or not ordering the medication
   - reasonReference : Reference(Condition | Observation) [0..*] // Condition or observation that supports why the prescription is being written
   

Or, a variant:

   MedicationRequest
   - medication[x] : CodeableConcept | Reference(Medication) [1..1] // Medication to be taken

These differ because of cardinality of the element, and a methodology limitation from the way we use JSON - choice elements can't repeat.

This pattern - in either form - is pretty clunky; no one likes it. But the idea of en element that provides information about what or why is happening, and that does so by referencing either a very specific piece of information, or just a general conceptual description of it by reference to some concept in a code system or ontology is a pretty common pattern in FHIR.

Common enough to want a better way to do the two examples above, that's for sure.

Proposal

Definition

The proposal is define a new type, ConceptReference.

   ConceptReference  : Reference {
     concept : CodeableConcept [0..1] // a reference to a code system or ontology that describes the essential properties of what is/might be referenced
   }

This type is a specialization of Reference, so shares the same properties. Note, for clarity, that this doesn't mean it can be substituted for any Reference - all FHIR data type bindings are final (in the OO sense), so this type could only be used where it is explicitly defined as the type for the element.

The ConceptReference type can have a binding to a value set, which just automatically applies to the concept element (pass through). It can also - like Reference - have parameters that define what it can reference. It could have both type parameters and a value set binding.

The ConceptReference type cannot have both reference|display and coding

btw, Alternative possible names: ReferenceOrConcept, CodeableReference

  • ConceptReference implies that it's a reference to a concept.
  • CodeableReference implies that it's a reference that might have a code.
  • ReferenceOrConcept is clumsy but probably the most correct.

Note that since this type doesn't introduce any new functionality, just reorganizes existing definitions, it would have special considerations around maturity (e.g it wouldn't start at FMM=0).

Use

Using this would be a simple change from the existing definitions

   MedicationRequest
   - medication : ConceptReference(Medication) [1..1] // Medication (code or details) to be taken
   - reason : ConceptReference(Condition | Observation) [0..*] //  Condition or observation (instance or concept) for ordering or not ordering the medication


The actual instance doesn't change all that much (using JSON here):

     "medicationReference": {
       "reference": "Medication/X"
     },
     "reasonCode": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "11840006",
             "display": "Traveller's Diarrhea (disorder)"
           }
         ]
       }
     ]

changes to

     "medication": {
       "reference": "Medication/X"
     },
     "reason": [
       {
         "concept" : {
           "coding": [
             {
               "system": "http://snomed.info/sct",
               "code": "11840006",
               "display": "Traveller's Diarrhea (disorder)"
              }
           ]
         }
       } 
     ]

and this

   {
     "medicationCodeableConcept": {
       "coding": [
         {
           "system": "http://snomed.info/sct",
           "code": "317935006",
           "display": "Chlorthalidone 50mg tablet (product)"
         }
       ]
     },
     "reasonReference": [
       {
         "reference": "Condition/f201",
         "display": "condition for prescribing this medication"
       }
     ]
   }

changes to

   {
     "medication": {
       "concept" : {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "317935006",
             "display": "Chlorthalidone 50mg tablet (product)"
           }
         ]
       }
     },
     "reason": [
       {
         "reference": "Condition/f201",
         "display": "condition for prescribing this medication"
       }
     ]
   }

Alternative

ConceptReference as defined here ends up with ConceptReference.concept.text and ConceptReference.display which are pretty much the same thing. And it has type, as well, which seems irrelevant in this context. So a different proposal is to define the type the other way around:

   ConceptReference  : CodeableConcept {
     reference : uri [0..1] // Literal reference, Relative, internal or absolute URL to detailed information about this thing
   }

The type would behave the same as the one defined the other way for definitional purposes, but play out slightly differently on the wire:


     "medicationReference": {
       "reference": "Medication/X"
     },
     "reasonCode": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "11840006",
             "display": "Traveller's Diarrhea (disorder)"
           }
         ]
       }
     ]

changes to

     "medication": {
       "reference": "Medication/X"
     },
     "reason": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "11840006",
             "display": "Traveller's Diarrhea (disorder)"
            }
         ]
       }
     ]

and this

   {
     "medicationCodeableConcept": {
       "coding": [
         {
           "system": "http://snomed.info/sct",
           "code": "317935006",
           "display": "Chlorthalidone 50mg tablet (product)"
         }
       ]
     },
     "reasonReference": [
       {
         "reference": "Condition/f201",
         "display": "condition for prescribing this medication"
       }
     ]
   }

changes to

   {
     "medication": {
       "coding": [
         {
           "system": "http://snomed.info/sct",
           "code": "317935006",
           "display": "Chlorthalidone 50mg tablet (product)"
         }
       ]
     },
     "reason": [
       {
         "reference": "Condition/f201",
         "text": "condition for prescribing this medication"
       }
     ]
   }

Other alternatives

There's another way to do this - to inherit from neither Reference or CodeableConcept:

   ConceptReference  : Element {
     coding : Coding [0..*] // Code defined by a terminology system
     text : string [0..1] // Plain text representation of the concept      
     reference : uri [0..1] // Literal reference, Relative, internal or absolute URL to detailed information about this thing
   }

This doesn't inherit from either CodeableConcept or Reference, though OO implementations could choose to do something about that if it suited them...