Example MedicationRequest/medrx0325 (XML)

define concepts and give them meaning through formal definitions, and assign codes that represent the concepts
• Value Sets specifies a set of codes defined by code systems that can be used in a specific context The difference between a code system and a value set is an important distinction that is easily missed by implementers, since the difference is often overlooked in system design. For instance, it's not unusual to see an application table that is a mixed list of codes, containing some LOINC codes and also some additional in-house codes. Quite often, there is no explicit differentiation between them; only the fact that a code happens to look like a LOINC code betrays its origin. For data exchange, on the other hand, explicitly tracking the source of the code is both important and necessary. In order to do this, each code system that defines codes is assigned a URL that identifies it, and all the codes it defines are actually a pair ("Code Pair": a name with a namespace). So in the case of this mixed list example from the previous paragraph, there are two code systems: LOINC (http://loinc.org) and a local one (let's say it has been given the URL: http://example.com/codesystems/additional-test-codes). The application table is a single value set (a set of Code Pairs) that includes codes from each of those two namespaces. The value set itself is given its own URL as an identifier (e.g. "http://example.com/fhir/ValueSet/test-codes"). This identifies the set of Code Pairs, but is never used as the namespace in an actual code pair, or in an instance. In FHIR, Code Pairs are always represented as "code" and "system", except for the simple data type code where the namespace (e.g. the system element/property) is fixed in the schema and not represented explicitly. Note that for some code systems, there is a single correct mechanism by which to represent codes defined by the system as a single URL. These single URLs are used in the context of the RDF format to enable ontological reasoning. The URL is often a direct reference to a web source that can provide additional definitional material about the concept. Where the mechanism is known, and defined by the code system, it is described in this specification. 4.1.2 Choosing a system The URL in a system is always a reference to a code system, not to a value set. The system ensures that codes can be unambiguously traced back to their original definition, and that logical comparisons, matching and inferences can be performed consistently by different systems. For this reason, choice of the correct URI for the system attribute is critical. The correct value to use in the system for a given code system can be determined by working through the following list, in order: The specification Code System Registry Narrative - if a code system is listed here, it SHALL be used A system URI or OID defined as the correct value to use in FHIR by the publisher of the code system The FHIR community code system registry - if a code system is listed here with status = active , it SHALL be used
An OID registered in the HL7 OID registry - if a code system is registered here, the OID SHOULD be used (using the syntax urn:oid:[oid]) If a code system is not resolved by this list, and there is no publisher to consult, implementers must choose a URI to use. The priority should be to choose a unique value that won't accidentally be used by another implementer for a different purpose - or a very similar purpose with a different scope. See Registering Code Systems
• for further advice. For publishers of code systems, the following considerations should be kept in mind when defining the correct URI to use: Once defined, the URI will require agreement from all implementers to change, and some might not be able to change (stored resources). If the set of users is not closed, it will usually not be possible to change the URI Implementers strongly prefer a human readable URI. http://acme.com/patients/mrn is a great deal easier to work with than urn:oid:1.2.3.4.5.6.7 An http: address SHOULD resolve to some useful description of the code system. Ideally, if a user makes a request of the address with the media type set to a FHIR media type, the server will respond with a CodeSystem resource , but some other human or computable definition is allowed HTTP addresses should be permalinks which may re-direct to the current correct content A scope of the code system URI and the correct usage of codes and displays in its namespace SHOULD be clearly defined. See examples for SNOMED CT , RxNorm , LOINC , NDC XML
Generally, allocation of URLs is hierarchical, and most care is required in choosing the Base URL. Once sub-URL policies are clearly defined, URIs can often be automatically assigned Note: if the code system is made available packaged inside a ValueSet resource, the correct URL for the system value is ValueSet.codeSystem.system , not ValueSet.uri . 4.1.3 Complex Code Systems All code systems define a set of concepts, assign specific codes to them, and provide definitional material to guide implementers in the correct use and understanding of the codes. Many code systems define relationships between the different concepts - is-a, part-of, classifies-with, and many other relationships. These features are represented in the CodeSystem resource, and exchanged using one of the code data types described above. Some code systems define rules for how complex expressions can be built using the basic concepts defined by the code system. This is sometimes referred to as "post-coordination". Some of the more notable code systems that define grammars for expressions are:
• SNOMED CT JSON
UCUM
• Mime Types Language TTL
ICD-[X]

There are many others. Any expression defined by the code system is still regarded as a 'code' and represented as such. This example shows a SNOMED CT expression: { "system" : "http://snomed.info/sct", "code" : "128045006:{363698007=56459004}" } Note that there is no display defined for SNOMED CT expressions. Raw XML 4.1.4 Controlling the use of Coded Values ( canonical form When an element is bound to a value set, the binding has these properties: Name A descriptive name used when presenting information about the binding Strength How the binding should be understood - + also see below Reference A URL that defines the value set. Usually, this is a direct reference to a ValueSet resource, but can be a more indirect reference, where the value set is inferred Description A text description of the use of the codes. If there is no reference, this must be populated. When there is a reference, this can be used to make additional notes about the use and implementation of the value set A binding is always represented using an ElementDefinition.binding . 4.1.4.1 Value Set References There are a number of places in the specification where value sets are referenced in order to bind a coded value to a value set: ElementDefinition .binding.valueSet Used to bind a defined element to a value set ConceptMap .source[x] and .target[x] Used to indicate the scope of the mapping in the Concept Map - from one value set to another Questionnaire .item.answerValueSet Indicates that answers to a set of questions come from a value set ValueSet .compose.include.valueSet The content of a value set includes the content in the imported value set too OperationDefinition .parameter.binding.valueSet Used to bind a defined parameter to a value set ValueSet Reference Extension Indicates that a coded value was chosen from the specified value set When referencing value sets, the reference is usually made to the definition of a value set - that is, a value set that defines what codes are in the value set. A terminology server is required to convert this definition to the actual expansion that specifies what codes are in the value set XML Format Specification in the context of operation. )

There are two types of value set references in this list, direct and logical. 4.1.4.1.1 Direct Value Set references Jump past Narrative A direct value set reference has the type Reference , and refers directly to a ValueSet based on a URL, usually to a terminology server running a FHIR RESTful API . When accessing a value set based on this kind of reference, a system should access the URL directly (after converting a relative reference to an absolute reference according to the local context). If this process fails, the system is unable to resolve the value set and must handle the error appropriately.

<?xml version="1.0" encoding="UTF-8"?>

<MedicationRequest xmlns="http://hl7.org/fhir">
    <id value="medrx0325"/> 
    <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"><p> <b> Generated Narrative: MedicationRequest</b> <a name="medrx0325"> </a> </p> <div style="display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border:

       1px solid #8da1b4; border-radius: 5px; line-height: 60%"><p style="margin-bottom: 0px">Resource MedicationRequest &quot;medrx0325&quot; </p> </div> <p> <b> identifier</b> : id: 12345689 (use: OFFICIAL)</p> <p> <b> status</b> : on-hold</p> <p> <b> intent</b> : order</p> <h3> Medications</h3> <table class="grid"><tr> <td> -</td> <td> <b> Concept</b> </td> </tr> <tr> <td> *</td> <td> Nystatin 100UNT/MG Topical Ointment <span style="background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki"> (<a href="http://terminology.hl7.org/4.0.0/CodeSystem-v3-rxNorm.html">RxNorm</a> #884308)</span> </td> </tr> </table> <p> <b> subject</b> : <a href="patient-example-a.html">Patient/pat1: Donald Duck</a>  &quot;Donald DUCK&quot;</p> <p> <b> authoredOn</b> : 2015-01-15</p> <p> <b> requester</b> : <a href="practitioner-example-f007-sh.html">Practitioner/f007: Patrick Pump</a>  &quot;Simone HEPS&quot;</p> <blockquote> <p> <b> dosageInstruction</b> </p> <p> <b> sequence</b> : 1</p> <p> <b> text</b> : Apply to affected areas four times daily</p> <p> <b> timing</b> : 4 per 1 days</p> <blockquote> <p> <b> doseAndRate</b> </p> </blockquote> </blockquote> <blockquote> <p> <b> dispenseRequest</b> </p> <p> <b> validityPeriod</b> : 2015-01-15 --&gt; 2016-01-15</p> <p> <b> numberOfRepeatsAllowed</b> : 3</p> <p> <b> quantity</b> : 30 g<span style="background: LightGoldenRodYellow"> (Details: UCUM code g = 'g')</span> </p> <h3> ExpectedSupplyDurations</h3> <table class="grid"><tr> <td> -</td> <td> <b> Value</b> </td> <td> <b> Unit</b> </td> <td> <b> System</b> </td> <td> <b> Code</b> </td> </tr> <tr> <td> *</td> <td> 10</td> <td> days</td> <td> <a href="http://terminology.hl7.org/4.0.0/CodeSystem-v3-ucum.html">Unified Code for Units of Measure (UCUM)</a> </td> <td> d</td> </tr> </table> </blockquote> <h3> Substitutions</h3> <table class="grid"><tr> <td> -</td> <td> <b> Allowed[x]</b> </td> <td> <b> Reason</b> </td> </tr> <tr> <td> *</td> <td> true</td> <td> formulary policy <span style="background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki"> (<a href="http://terminology.hl7.org/4.0.0/CodeSystem-v3-ActReason.html">ActReason</a> #FP)</span> </td> </tr> </table> </div> </text> <identifier> 
        <use value="official"/> 
        <system value="http://www.bmc.nl/portal/prescriptions"/> 
        <value value="12345689"/> 
    </identifier> 
    <status value="on-hold"/> 
    <intent value="order"/> 
    <medication> 
    <concept> 
        <coding> 
            <system value="http://www.nlm.nih.gov/research/umls/rxnorm"/> 
        <code value="884308"/> 
        <display value="Nystatin 100UNT/MG Topical Ointment"/> 
        </coding> 
    </concept> 
    </medication> 
    <subject> 
            <!--    Linked to the resource patient who needs the medication    -->
        <reference value="Patient/pat1"/> 
        <display value="Donald Duck"/>    
    </subject> 
    <authoredOn value="2015-01-15"/> 
    <requester> 
        <reference value="Practitioner/f007"/> 
        <display value="Patrick Pump"/> 
    </requester> 

   
    <dosageInstruction> 
        <sequence value="1"/> 
        <text value="Apply to affected areas four times daily"/> 
        <timing> 
            <repeat> 
                <frequency value="4"/> 
                <period value="1"/> 
                <periodUnit value="d"/> 
            </repeat> 
        </timing> 
        <doseAndRate> 
            <type> 
                <coding> 
                    <system value="http://terminology.hl7.org/CodeSystem/dose-rate-type"/> 
                <code value="ordered"/> 
                <display value="Ordered"/> 
            </coding> 
            </type> 


            <doseQuantity> 
                <value value="1"/> 
                <unit value="ea"/> 
                <system value="http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm"/> 
                <code value="OINT"/> 
            </doseQuantity> 
        </doseAndRate> 

        
    </dosageInstruction> 

    
    <dispenseRequest> 
        <validityPeriod> 
            <start value="2015-01-15"/> 
            <end value="2016-01-15"/> 
        </validityPeriod> 
        <numberOfRepeatsAllowed value="3"/> 
        <quantity> 
            <value value="30"/> 
            <unit value="g"/> 
            <system value="http://unitsofmeasure.org"/> 
            <code value="g"/>  
        </quantity> 
        <expectedSupplyDuration> 
            <value value="10"/> 
            <unit value="days"/> 
            <system value="http://unitsofmeasure.org"/> 
            <code value="d"/>  
        </expectedSupplyDuration> 
    </dispenseRequest>    
    <substitution> 
        <allowedBoolean value="true"/> 
        <reason> 
            <coding> 
                <system value="http://terminology.hl7.org/CodeSystem/v3-ActReason"/> 
                <code value="FP"/> 
                <display value="formulary policy"/>              
            </coding> 
        </reason> 
    </substitution> 

,
etc.)
The
other
place
where
this
is
used
is
when
profiling
resources
,
and
there
is
agreement
within
a
context
of
use
that
a
specified
set
of
codes
are
the
only
ones
that
can
be
used.
In
these
cases,
the
data
type
SHALL
contain
one
of
the
values
in
the
value
set.
The
following
rules
apply
when
required
bindings
are
used
with
the
CodeableConcept


</

MedicationRequest


data
type:
at
least
one
Coding
element
SHALL
be
present
one
of
the
Coding
values
SHALL
be
from
the
specified
value
set
text
can
be
provided
as
well,
and
is
always
recommended,
but
is
not
an
acceptable
substitute
for
the
required
code
If
a
required
binding
is
applied
to
an
element
with
maximum
cardinality

>
1,
the
binding
applies
to
all
the
elements.
The
following
rules
apply
when
required
bindings
are
used
with
the
code
data
type:
Where
the
value
set
is
defined
by
FHIR,
the
list
of
allowed
codes
will
be
fixed
in
the
XML
schema
Comparison
between
codes
is
always
case
sensitive
unless
the
codes
are
selected
by
reference
(e.g.
ValueSet.compose),
and
the
referenced
specification
clearly
states
otherwise
The
list
of
codes
that
can
be
used
can
only
be
extended
in
subsequent
releases
of
the
FHIR
specification
When
an
element
is
bound
to
a
required
value
set,
derived
profiles
may
state
rules
on
which
codes
can
be
used,
including
removing
codes
from
allowed
use,
but
cannot
specify
new
or
additional
codes
for
these
elements.
4.1.5.2


Extensible



To
be
conformant,
codes
in
this
element
SHALL
be
from
the
specified
value
set
if
any
of
the
codes
within
the
value
set
can
apply
to
the
concept
being
communicated.
Note
that
it
is
the
value
set
binding
that
is
extensible,
not
the
value
set
itself.
If
there
is
no
applicable
concept
in
value
set
(based
on
human
review),
an
alternate
concept
(either
system
/
code
pair,
or
text
)
may
be
used
instead.
The
alternate
concept
can
have
any
level
of
specificity
in
an
is-a
hierarchy
(see
Condition
instance
#2
).
If
there
is
at
least
one
applicable
concept
in
the
extensibly-bound
value
set
with
a
meaning
which
includes
but
is
more
general
than
the
meaning
that
is
intended
to
be
represented
by
the
element
in
the
resource
instance,
then
the
code
that
is
used
in
the
instance
SHALL
be
taken
from
the
value
set
and
should
be
the
closest
available
match
for
the
intended
element
instance
meaning
(i.e.
neither
more
general
or
more
specific).
However,
a
more
specific
code
that
more
completely
represents
the
intended
meaning
may
also
be
included
in
the
instance
as
an
additional
Coding
if
the
data
type
is
CodeableConcept,
but
it
cannot
be
used
instead
of
the
code
from
the
value
set.
This
helps
ensure
that
systems
know
which
codes
they
should
expect
to
receive
and
build
logic
for
and
it
facilitates
interoperability.

When a code for an applicable concept in the extensibly-bound value set is used it should always be the closest available match for the intended element instance meaning, regardless of hierarchical (i.e. "is-a") relationships in the underlying code system(s) or hierarchical "level" of the concept. However, as noted above, a code for a concept that is outside of the extensibly-bound value set with a meaning which is "covered by" (i.e. is more specific than or Usage note: every effort has an "is-a" relationship to) a concept that is included in the value set cannot be used. In that case a code for a concept that is in the extensibly-bound value set SHALL be used in the element instance and it should be the code for the concept that most closely matches the intended element instance meaning. If the data type is CodeableConcept , then, as noted above, one of the Coding values SHALL be from the specified extensibly-bound value set if a code in that value set applies, but if no applicable code exists in the value set alternate code(s) from outside the value set may be used instead. If no codes, including local codes, are available, then text alone (in CodeableConcept.text) may be used. If the data type is Coding , then the code/system SHALL be from the specified value set if a code applies, but if no suitable code exists in the value set, an alternate code may be provided in its place. If an extensible binding is applied to an element with maximum cardinality > 1, the binding applies to all the elements. Identified gaps in value sets should be submitted to the organization administering the value set in order to improve interoperability in the future. Extensible bindings are used when there is consensus at the specification or profiling level about the coded values that should be used, but it is impossible to create a bounded list of codes that are known to cover all use cases, including ones that are yet to arise. When an element is extensibly-bound been made to a value set, derived profiles may state rules on which codes can be used, but cannot select new or additional codes for these elements unless no codes with appropriate meanings are found in the base value set. Note that if the valueset-reference extension is being used and the code in the element instance is from outside the extensibly-bound value set, the extension must reference a different value set ensure that the code was chosen from (or if no other value set reference is available the extension cannot be used in that instance). 4.1.5.2.1 Examples for Extensible Bindings See examples to help explain the difficult but important subject of Extensible bindings. 4.1.5.3 Preferred Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant. If the data type is CodeableConcept , then one of the Coding values SHOULD be from the specified value set, but another code and/or text can be used in its place. Preferred bindings are used when there is consensus at the specification level about the coded values that are the best to be used, correct and useful, but there is recognition that some implementation contexts are unable to use the recommended codes for a variety of reasons. Applications should consider adopting the preferred value set wherever possible, as these preferred value sets are the most likely to serve interoperability purposes in the future. When an element is bound to a preferred value set, derived profiles may bind the element to any value set they choose. 4.1.5.3.1 Examples for Preferred Bindings See examples of how Preferred bindings work. 4.1.5.3.2 Example Bindings Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included. Example bindings are used when an element has a very broad meaning (such as List .code), or there is no consensus over the correct codes to be used. For these bindings: Coding : the system / code values MAY be one of the codes in the value set. CodeableConcept : one of the coding elements MAY contain a system / code that is in the value set. Some other coded value MAY be used, or (for a CodeableConcept), a text alternative MAY be provided. Example value sets are provided to assist implementers to understand the correct use of an element. Value sets based on code systems such as SNOMED CT that have restrictive license terms will only be used as example bindings in the base FHIR specification, though implementation guides for particular jurisdictions may adopt value sets that require licenses. In addition, well-specified realm-specific ValueSets may also be used as example bindings in the base specification. When an element is bound to an example value set, derived profiles may bind the element to any value set they choose. 4.1.6 Other notes Subsequent versions of FHIR may replace example value sets with preferred bindings if enough consensus emerges in the relevant sphere. Bindings to value sets provided as normative part of the specification are always specific to the version of the value set published with the specification. The value set may be sealed by defining a simple list of enumerated codes, or it may include codes by their properties, along with a non-version specific reference to an underlying code system, in which case the list of valid concepts may change over time. 4.1.6.1 Binding String Values In a few special cases, humans customarily use codes directly for elements that have type "string". A typical case is codes for states, and there are several places where a URI must come from a set of controlled values. An element of type string or uri can also be bound to a value set. When a string or URI is bound to a value set, the value property SHALL contain the code specified by the value set, and the system and display values are ignored. 4.1.6.2 Terminology Service FHIR has defined a Terminology Service specification which sets requirements for systems that support the use of codes, value sets and code systems.