Release
5
4
Foundation
This
page
is
part
of
the
FHIR
Specification
(v5.0.0:
R5
(v4.0.1:
R4
-
Mixed
Normative
and
STU
).
This
is
the
)
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
The
current
published
version.
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 |
|
This
page
has
been
approved
as
part
of
an
ANSI
standard.
See
the
Infrastructure
Package
for
further
details.
|
The
JSON
representation
for
a
resource
is
based
on
the
JSON
format
described
in
STD
90
(RFC
8259)
,
and
is
described
using
this
format:
{
"resourceType" : "[Resource Type]",
// from Source: property0
"property1" : "<[primitive]>", // short description
"
"property2" : { [Data Type] }, // 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.
This
page
contains
some
The
JSON
format
is
similar
to
the
XML
examples
format:
There are differences from XML:
resourceType
id
,
value
)
are
handled
differently
(see
below)
<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
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
formats
.
-->
JSON
converters
are
not
able
to
perform
correctly.
The
reference
platforms
provide
XML
<-->
JSON
conversion
functionality
that
accommodates
these
FHIR-specific
characteristics.
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:
<code>
<coding>
<system value="http://snomed.info/sct"/>
<code value="104934005"/>
</coding>
<coding>
<system value="http://loinc.org"/>
<code value="2947-0"/>
</coding>
</code>
So
a
CodeableConcept
is
represented
in
JSON
like
this:
{
"coding": [
{
"system" : "http://snomed.info/sct",
"code" : "104934005"
},
{
"system" : "http://loinc.org",
"code" : "2947-0"
}
]
}
FHIR
elements
with
primitive
datatypes
data
types
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
datatype.
data
type.
Whitespace
is
always
significant
(i.e.
no
leading
and
trailing
spaces
for
non-strings).
<code value="abc"/> <!-- code --> <date value="1972-11-30"/> <!-- dateTime --> <deceased value="false" /> <!-- boolean --> <count value="23" /> <!-- integer -->
For
comparison,
this
is
represented
in
XML
JSON
as
"code" : "abc", "date" : "1972-11-30", "deceased" : false, "count" : 23
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
datatype
data
type
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 id="314159" value="1970-03-30" >
<extension url="http://example.org/fhir/StructureDefinition/text">
<valueString value="Easter 1970"/>
</extension>
</birthDate>
is represented in JSON as:
"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:
< id="314159" value="1970-03-30" >
<extension url="http://example.org/fhir/StructureDefinition/text">
<valueString value="Easter 1970"/>
</extension>
</>
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
datatypesdata types 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 primitivedatatypes.data types.
Complex
Elements,
and
complex
datatypes
(types
that
contain
named
elements
of
other
types)
are
represented
using
a
JSON
object
that
contains
object,
containing
a
property
member
for
each
element
in
the
datatype.
Complex
datatypes
Composites
can
have
ids,
id
attributes,
which
are
converted
to
JSON
properties,
member
values,
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:
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.
The
signed
set
of
fragments
SHALL
be
transformed
such
that:
JSON:
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
R5
hl7.fhir.core#5.0.0
Release
4
(Technical
Correction
#1)
(v4.0.1)
generated
on
Sun,
Mar
26,
2023
15:26+1100.
Fri,
Nov
1,
2019
09:37+1100.
QA
Page
Links:
Search
|
Version
History
|
Table
of
Contents
|
Glossary
|
QA
|
Compare
to
R4
Credits
|
Compare
to
R4B
R3
|
|
Propose
a
change