This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Proposal for ConceptReference"

From HL7Wiki
Jump to navigation Jump to search
(→‎Definition: added an issue)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This page documents rationale for a proposed enhancement for FHIR, the creation of a new datatype called ConceptReference
 
This page documents rationale for a proposed enhancement for FHIR, the creation of a new datatype called ConceptReference
  
−
= Rationale =
+
=Rationale=
  
 
As of R4, it's pretty common to see this pattern in FHIR:
 
As of R4, it's pretty common to see this pattern in FHIR:
Line 20: Line 20:
 
Common enough to want a better way to do the two examples above, that's for sure.  
 
Common enough to want a better way to do the two examples above, that's for sure.  
  
−
= Proposal =
+
=Proposal=
  
−
== Definition ==
+
==Definition==
  
 
The proposal is define a new type, ConceptReference.  
 
The proposal is define a new type, ConceptReference.  
Line 30: Line 30:
 
     }
 
     }
  
−
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.  
+
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)
+
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
 
btw, Alternative possible names: ReferenceOrConcept, CodeableReference
  
−
== Use ===
+
*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).
  
−
Using this would be simple
+
Issue: The definition should address the potential conflict between CodeableConcept.text and Reference.display.
 +
 
 +
==Use==
 +
 
 +
Using this would be a simple change from the existing definitions
  
 
     MedicationRequest
 
     MedicationRequest
Line 45: Line 57:
  
  
−
The actual instance doesn't change all that much (in JSON):
+
The actual instance doesn't change all that much (using JSON here):
  
 
       "medicationReference": {
 
       "medicationReference": {
Line 122: Line 134:
 
       ]
 
       ]
 
     }
 
     }
 +
 +
==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...

Latest revision as of 14:18, 17 October 2019

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).

Issue: The definition should address the potential conflict between CodeableConcept.text and Reference.display.

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...

Retrieved from "https://wiki.hl7.org/w/index.php?title=Proposal_for_ConceptReference&oldid=166773"