Release
4
5
This
page
is
part
of
the
FHIR
Specification
(v4.0.1:
R4
(v5.0.0:
R5
-
Mixed
Normative
and
STU
)
).
This
is
the
current
published
version
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
Implementable
Technology
Specifications
Work
Group
|
Maturity Level : Normative | Standards Status : Normative |
The
JSON
representation
for
a
resource
is
based
on
the
JSON
format
described
in
STD
90
(RFC
8259)
,
and
is
described
using
this
format:
Foundation
{
"resourceType" : "[Resource Type]",
// from Source: property0
"property1" : "<[primitive]>", // short description
"
"property2" : { [Datatype] }, // short description
"property3" : { // Short Description
"propertyA" : { CodeableConcept }, // Short Description (Example)
},
"property4" : [{ // Short Description
"propertyB" : { Reference(ResourceType) } // R! Short Description
}]
}
Using this format:
property1
has
a
primitive
property2
has
a
complex
property3
is
an
object
property
that
contains
additional
properties
(e.g.
propertyA;
the
allowable
properties
are
property4
is
an
array
property
that
contains
items
which
are
objects
themselves.
The
items
may
have
any
of
the
types
already
encountered
in
points
1-3
propertyA
is
an
example
of
an
object
property
that
has
a
binding
to
a
value
set
-
the
Short
description
is
a
link
to
the
value
set.
In
addition,
the
binding
strength
is
shown
propertyB
is
an
example
of
an
object
property
that
has
a
reference
to
a
particular
kind
of
resource
//
is
used
for
comments.
While
//
is
legal
in
Javascript,
it
is
not
legal
in
JSON,
and
comments
SHALL
not
be
in
JSON
instances
irrespective
of
whether
application/fhir+json
.
Given the way extensions work, applications reading JSON resources will never encounter unknown properties. However, once an application starts trading with other applications that conform to later versions of this specification, unknown properties may be encountered. Applications MAY choose to ignore unknown properties in order to foster forwards compatibility in this regard, but may also choose not to.
The
JSON
format
is
similar
to
the
This
page
contains
some
XML
format:
The
names
examples
for
the
JSON
object
members
are
the
same
as
the
names
of
the
elements
and
attributes
in
XML,
including
elements
that
may
repeat.
Property
names
are
case
sensitive
Just
as
in
XML,
JSON
objects
and
arrays
are
never
empty,
and
properties
never
have
null
values
(except
for
a
special
case
documented
below).
Omit
a
property
if
it
is
empty
JSON
whitespace
is
not
part
of
the
contents
of
a
resource.
Applications
MAY
preserve
the
whitespace
when
handling
resources,
but
are
not
required
to
do
so.
Note
that
digital
signatures
may
depend
on
the
whitespace
There
are
differences
from
XML:
There
are
no
namespaces
in
the
JSON
representation
The
type
of
the
resource
is
represented
differently
in
JSON
-
instead
of
being
the
name
purposes
of
comparison
between
the
base
object
(there
is
none
in
JSON),
it
is
carried
as
the
property
resourceType
two
formats.
The
order
of
properties
of
an
object
is
not
significant
in
the
JSON
representation,
though
order
within
an
array
SHALL
be
maintained
JSON
does
not
have
a
notion
of
attributes
versus
elements,
so
attributes
(e.g.
id
,
value
)
are
handled
differently
(see
below)
JSON
formats
page
has
the
array
notation,
which
is
used
to
represent
repeating
elements.
Note
that
arrays
are
used
when
the
item
might
repeat,
even
if
it
does
not
repeat
in
a
specific
instance
The
XHTML
<div>
element
in
the
Narrative
datatype
is
represented
as
a
single
escaped
string
of
XHTML.
This
is
to
avoid
problems
in
JSON
with
mixed
content,
etc.
The
XHTML
SHALL
still
conform
to
the
rules
described
for
comparison
between
the
Narrative
The
JSON
format
for
the
resources
follows
the
standard
XML
format
closely
to
make
interconversion
easy,
and
so
that
XPath
queries
can
easily
be
mapped
to
query
the
JSON
structures.
However,
the
differences
-
particularly
the
repeating
element
one,
which
cannot
be
avoided
-
mean
that
generic
XML
-->
JSON
converters
are
not
able
to
perform
correctly.
The
reference
platforms
provide
XML
<-->
JSON
conversion
functionality
that
accommodates
these
FHIR-specific
characteristics.
formats
.
An
element
that
has
a
maximum
cardinality
of
>1
(e.g.
x..*
in
the
definitions)
may
occur
more
than
once
in
the
instance.
In
XML,
this
is
simply
done
by
repeating
the
XML
element
multiple
times.
In
JSON,
this
is
done
by
using
an
array
type.
Note
that:
So a CodeableConcept is represented in JSON like this:
{
"coding": [
{
"system" : "http://snomed.info/sct",
"code" : "104934005"
},
{
"system" : "http://loinc.org",
"code" : "2947-0"
}
]
}
XML for comparison:
<code>
<coding>
<system value="http://snomed.info/sct"/>
<code value="104934005"/>
</coding>
<coding>
<system value="http://loinc.org"/>
<code value="2947-0"/>
</coding>
</code>
FHIR
elements
with
primitive
data
types
datatypes
are
represented
in
two
parts:
_
prepended
to
the
name
of
the
element,
which,
if
present,
contains
the
value's
id
and/or
extensions
The
FHIR
types
integer
,
unsignedInt
,
positiveInt
and
decimal
are
represented
as
a
JSON
number,
the
FHIR
type
boolean
as
a
JSON
boolean,
and
all
other
types
(including
integer64
)
are
represented
as
a
JSON
string
which
has
the
same
content
as
that
specified
for
the
relevant
data
type.
datatype.
Whitespace
is
always
significant
(i.e.
no
leading
and
trailing
spaces
for
non-strings).
"code" : "abc", "birthDate" : "1972-11-30", "deceased" : false, "count" : 23 }
For
comparison,
this
is
represented
in
JSON
XML
as
<code value="abc"/> <!-- code --> <birthDate value="1972-11-30"/> <!-- dateTime --> <deceased value="false" /> <!-- boolean --> <count value="23" /> <!-- integer -->
When
using
a
JavaScript
JSON.parse()
implementation,
note
that
JavaScript
natively
supports
only
one
numeric
datatype,
which
is
a
floating
point
number.
This
can
cause
loss
of
precision
for
FHIR
numbers.
In
particular,
trailing
0s
after
a
decimal
point
will
be
lost
e.g.
2.00
will
be
converted
to
2.
The
FHIR
decimal
data
type
datatype
is
defined
such
that
precision,
including
trailing
zeros,
is
preserved
for
presentation
purposes,
and
this
is
widely
regarded
as
critical
for
correct
presentation
of
clinical
measurements.
Implementations
should
consider
using
a
custom
parser
and
big
number
library
(e.g.
https://github.com/jtobey/javascript-bignum
)
to
meet
these
requirements.
See
also
the
precision
extension
.
If the value has an id attribute, or extensions, then this is represented as follows:
"birthDate": "1970-03-30",
"_birthDate": {
"id": "314159",
"extension" : [ {
"url" : "http://example.org/fhir/StructureDefinition/text",
"valueString" : "Easter 1970"
}]
}
Note:
If
the
primitive
has
an
id
attribute
or
extension,
but
no
value,
only
the
property
with
the
_
is
rendered.
This is represented in XML as:
<birthDate id="314159" value="1970-03-30" >
<extension url="http://example.org/fhir/StructureDefinition/text">
<valueString value="Easter 1970"/>
</extension>
</birthDate>
In the case where the primitive element may repeat, it is represented in two arrays. JSON null values are used to fill out both arrays so that the id and/or extension are aligned with the matching value in the first array, as demonstrated in this example:
<code value="au"/>
<code value="nz">
<extension url="http://hl7.org/fhir/StructureDefinition/display">
<valueString value="New Zealand a.k.a Kiwiland"/>
</extension>
</code>
is represented in JSON as:
"code": [ "au", "nz" ],
"_code": [
null,
{
"extension" : [ {
"url" : "http://hl7.org/fhir/StructureDefinition/display",
"valueString" : "New Zealand a.k.a Kiwiland"
}]
}
]
Note: when one of the repeating elements has no value, it is represented in the first array using a null. When an element has a value but no extension/id, the second array will have a null at the position of that element. If the length of a JSON "element" array is different from the length of its JSON "_element" array, implementations SHALL infer null values in the suffix of the shorter array. If an array has only null elements, implementations SHOULD omit it entirely.
Implementation Note: The representation of primitive
data typesdatatypes has been split into two parts like this in order to simplify the representation of simple primitive values without id or extensions. This does have the cost of making the representation of the id attribute and extensions more ungainly, but these are both rarely used with primitivedata types.datatypes.
Elements,
and
complex
Complex
datatypes
(types
that
contain
named
elements
of
other
types)
are
represented
using
a
JSON
object,
containing
object
that
contains
a
member
property
for
each
element
in
the
datatype.
Composites
Complex
datatypes
can
have
id
attributes,
ids,
which
are
converted
to
JSON
member
values,
properties,
in
the
same
manner
as
described
for
primitives.
For
example:
<Patient>
<text>
<status value="generated" />
<div xmlns="http://www.w3.org/1999/xhtml"><p>...</p></div>
</text>
<name id="f2">
<use value="official" />
<given value="Karen" />
<family id="a2" value="Van" />
</name>
</Patient>
is represented in JSON as:
{
"resourceType" : "Patient",
"name" : [{
"id" : "f2",
"use" : "official" ,
"given" : [ "Karen" ],
"family" : "Van",
"_family" : {"id" : "a2"}
}],
}],
"text" : {
"status" : "generated" ,
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
}
}
Things to note here are:
given
is
a
repeating
name
,
the
id
is
added
represented
in
_family
as
described
above,
while
the
id
on
the
name
itself
is
represented
as
just
another
property
div
element
which
is
in
the
Narrative
element
text
is
represented
as
an
escaped
string
in
the
value
property
in
JSON.
The
xhtml
root
element
A
resource
is
a
JSON
object
with
a
property
resourceType
which
informs
the
parser
which
resource
type
this
is:
{
"resourceType" : "Patient",
"text" : {
"status" : "generated" ,
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
}
// etc...
}
Note that parsers cannot assume that the resourceType property will come first.
Implementation Note: This is a problem for several JSON -> Object serializers that assume that the resourceType property does come first, including Json.NET
There is a sample file with many edge cases to help test JSON parsers.
Resources and/or Bundles may be digitally signed (see Bundle and Provenance ).
This
specification
defines
the
following
method
for
canonicalizing
FHIR
resources,
when
represented
as
JSON:
JSON.
The
signed
set
of
fragments
SHALL
be
transformed
such
that:
This
canonicalization
method
is
identified
by
the
URI
http://hl7.org/fhir/canonicalization/json
.
The
following
additional
canonicalization
URIs
are
also
defined:
| http://hl7.org/fhir/canonicalization/json#data |
The
narrative
(
Resource.text
)
is
omitted
prior
to
signing
(note
the
deletion
is
at
Resource.text
,
not
Resource.text.div
)
|
| http://hl7.org/fhir/canonicalization/json#static |
In
addition
to
narrative
(Resource.text),
the
Resource.meta
element
is
removed.
This
makes
the
signature
robust
as
the
content
is
moved
from
server
to
server,
or
workflow
and
access
tags
are
added
or
removed.
Note
that
workflow
and
security
tags
may
contain
information
important
to
the
handling
of
the
resource,
so
meta
elements
should
be
protected
from
tampering
by
other
means
if
unsigned.
|
| http://hl7.org/fhir/canonicalization/json#narrative |
This
method
only
retains
the
Resource.id
and
Narrative
elements
|
| http://hl7.org/fhir/canonicalization/json#document | The signs everything in a Bundle, except for the Bundle.id and Bundle.metadata on the root Bundle (allows for a document to be copied from server to server) |
These canonicalization methods allow system the flexibility to sign the various portions of the resource that matter for the workflow the signature serves. These canonicalization algorithms do not work for enveloped signatures. This will be researched and addressed in a future release. This specification may define additional canonicalizations in the future, and other specifications might also define additional canonicalization methods.
Implementation Note: One consequence of signing the document is that URLs, identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed ecosystems where re-identification frequently occurs. For this reason, it is recommended that systems consider carefully the impact of any signature processes. The impact of signatures on Document bundles and their related processes is the most well understood use of digital signatures.
FHIR
®©
HL7.org
2011+.
FHIR
Release
4
(Technical
Correction
#1)
(v4.0.1)
R5
hl7.fhir.core#5.0.0
generated
on
Fri,
Nov
1,
2019
09:37+1100.
QA
Page
Sun,
Mar
26,
2023
15:26+1100.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
Glossary
|
QA
|
Compare
to
R3
R4
|
Compare
to
R4B
|
|
Propose
a
change