Section: 5

dosage.html

Dosage

Maturity Level: 3Standards Status:Trial Use

The Dosage structure defines general dosage instruction information typically represented in medication requests, medication dispenses and medication statements.

Note: the Dosage structure allows modifier extensions.

Content

Constraints

Dosage is used in the following places:

Interpretation of Dosage in different contexts


downloads.html

Downloads

Maturity Level: N/AStandards Status:Informative
Specification Downloads
FHIR Definitions All the value sets, profiles, etc. defined as part of the FHIR specification, and the included implementation guides: These is the master set of definitions that should be the first choice whenever generating any implementation artifacts. All the other forms below include only subsets of the information available in these definition files, and do not contain all of the rules about what makes resources valid. Implementers will still need to be familiar with the content of the specification and with any profiles that apply to the resources in order to make a conformant implementation.

XML
  • Examples - all the example resources in XML format
  • Validation Schemas (includes support schemas, resource schemas, modular & combined schemas, and Schematrons)
  • Code Generation Schemas (See notes about code-generation schemas) Also note that names relevant for code generation, including resource names, element & slice names, codes etc may collide with reserved words in the relevant target language, and code generators will need to handle this

JSON

RDF
  • Turtle Examples - all the example resources in Turtle format
  • ShEx Schemas - ShEx definitions for validating RDF resources
  • Definitions - the formal definitions that define the predicates and classes used in the RDF format (not up to date)

FHIR Specification The whole specification so that you can host your own local copy (does not include the downloads) (not downloadable from build.fhir.org)
Implementation Tools
Validator The official FHIR validator - a Java jar file that can be used to validate resources. See Validation Tools for further information, or Using the FHIR Validator for parameter documentation
IG Publisher The Implementation Guide Publishing Tool (see IG Publishing documentation)
NPM Package The NPM Package used by many of the FHIR tools (particularly the IG publisher and the validator). This contains all the conformance & example resources, and various publishing support files. Note that the tools usually find this package directly, and there's no need to download it
Translation File Translations of common FHIR names and messages into multiple languages (see chat.fhir.org translations stream for guidance on how to add to more)
Icon Pack The FHIR Icon at various resolutions. Any FHIR Implementation created by an organization that has attended a connectathon is allowed to use the FHIR icon in association with the application (this policy will be reviewed in the future).
Test Cases A Collection of Test Cases. These are XML or JSON files that provide test cases for the various FHIR reference implementations to ensure correct functioning
Code Generation Support Value Set expansions for the value sets used in schema generation (XML or JSON) + a list of all choice elements & backbone elements. Note that names relevant for code generation, including resource names, element & slice names, codes etc may collide with reserved words in the relevant target language, and code generators will need to handle this
Reference Implementations
There are many open source reference implementations available to help implementers. Here are a list of the more common implementations used by implementers:
Java HAPI-FHIR: Object Models, Parsers, Client + Server Framework, FHIR Validator, & Utilities. The specification is built with this Java code
C# HL7.FHIR: Object models, Parsers/Serializers, Utilities, and a Client. Source code on GitHub at http://github.com/ewoutkramer/fhir-net-api
Pascal FhirServer: Object models, Parsers/Serializers, Validator, Utilities, Client, and the FHIR Reference server. Requires Delphi (Unicode versions)
XML XML Tools: Document Rendering Stylesheet, supplementary implementation schemas and transforms
Javascript FHIR.js: Javascript Client and Utilities
Swift Swift-FHIR: Object Model, Client and Utilities
These reference implementations are provided for implementer interest and assistance. While they may be used (and are) in production systems, HL7 and their various contributors accept no liability for their use. Note that these reference implementations are provided to assist to implementers to adopt the specification, and some are maintained by the FHIR project team, but are not part of the specification, and implementations are not required to conform to these, nor are they subject to the formal standards process.

Full blown open source implementations for FHIR, some of which use these reference implementations, are listed on HL7 Confluence.

It is not necessary to use these particular implementations in order to be conformant. Any other approach may be used, including code generated from the schemas.


ehr-fm.html

Appendix: HL7 EHR System Functional Model and FHIR

Maturity Level: N/AStandards Status:Informative

ISO/HL7 10781 EHR System Functional Model Release 2 provides a reference list of functions that may be present in an Electronic Health Record System. While FHIR is an implementation focused on exchange of information in healthcare, this often happens in the context of an EHR system and EHR record. This table briefly describes one way that FHIR can be used to meet the requirements described in the EHR-S FM and is provided to help readers of the FHIR specification understand how FHIR can be used. There are many other equally valid ways to implement the EHR-S FM and to make use of FHIR.

EHR FunctionFHIR Implementation Notes
TI.1SecurityFHIR defines parts of the security infrastructure, and delegates others to standard web based security frameworks
TI.1.1Entity AuthenticationFHIR assumes that the users are authenticated. OAuth is the preferred mechanism
TI.1.2Entity AuthorizationFHIR does not currently provide any resources to describe or manage access-control permissions. By default, underlying web frameworks such as SAML would be used. See the security section for a discussion of binding between FHIR and SAML
TI.1.3Entity Access ControlSee above about SAML / OAuth
TI.1.4Patient Access ManagementSee Security Labels
TI.1.5Non-RepudiationThe provenance resource tracks the timestamps, actors, and digital signatures associated with resources
TI.1.6Secure Data ExchangeTLS (https:) should be used for all production exchange of data. All conformant FHIR RESTful implementations SHALL be able to use TLS
TI.1.7Secure Data RoutingFHIR allows for brokers and various forms of messaging that support assured destinations and delivery (also see IN.2.2 below)
RI.1.1.4Information AttestationSee the provenance resource
TI.1.8Patient Privacy and ConfidentialityFHIR does not include functionality related to this requirement, though implementations would be expected to provide this
RI.1.1Health Record Information and ManagementThis is a core application of the FHIR capabilities
RI.1.22Data Retention, Availability and DestructionA FHIR RESTful server gives precise and fine-grained control of retention, availability and destruction of resources, all clearly described by the capability statement
RI.1.1.x.1Auditable RecordsFHIR provides the AuditEvent resource for auditable records.
RI.2SynchronizationFHIR supports synchronization using standard web publication/subscription methods via Bundles. Bundle-based pub/sub may be push or pull based, and can include all resources of a particular type, or selected subsets of the resources. In addition, groups of resources can be exchanged in bundles, keeping a set of related resources in synchronization
RI.1.1.13Extraction of Health Record InformationFHIR does not provide report formats, but does provide extensive search and retrieval functions to assist with building such reports
RI.1.1.1Store and Manage Health Record InformationA FHIR RESTful server can store and manage health information persistently - see below for further information.
RI.1.2.1Manage Structured and Unstructured Health Record InformationThe dual contents of FHIR resources - structured data and XHTML narrative - provide seamless support for dealing with a mix of structured and unstructured information
TI.3Registry and Directory ServicesThe FHIR Administration resources provide registry-based access to patients, providers, etc.
TI.4Standard Terminologies and Terminology ServicesFHIR encourages the use of standard terminologies wherever possible, and provides full support for their use through a variety of terminology related data types. FHIR defines a terminology service infrastructure. Also, see profiling, which discusses how terminology is used in a FHIR context
TI.5Standards-based InteroperabilityFHIR is a definition of a standard on which to base interoperability
TI.5.1Interchange StandardsThis is the core focus of FHIR. See below for discussion of interaction modes
TI.5.2Interchange Standards Versioning and Maintenance FHIR version maintenance is described here
TI.5.3Standards-based Application IntegrationFHIR enables simple integration through use of an easy to understand, use and debug web-based infrastructure. The same framework used within an EHR for persistence can also offer a simple way to implement exchange
TI.5.4Interchange AgreementsThe FHIR Conformance Statement and Resource Profile resources provide a registry based infrastructure for individual trading partner agreements, as well as for community based ones
TI.6Business Rules ManagementFHIR does not address this requirement at this point in time
TI.7Workflow ManagementFHIR does not address this requirement at this point in time, though the resources and services exist to support this functionality

The EHR system functional model describes several modes for interaction between systems. Each of these can be implemented in several different ways using FHIR

Interaction ModesFHIR Options
Unsolicited Notifications
e.g. a patient has arrived for a clinic appointment
  • Create/update new resource via HTTP
  • Push resources using Bundle
  • Send FHIR Message (if appropriate event is defined)
Query/Response
e.g. Is Adam Everyman known to the system? Yes, MRN is 12345678.
  • Search with parameters
  • A query message (though not defined yet)
Service Request and Response
e.g. Laboratory Order for Fasting Blood Sugar and a response containing the results of the test.
Could be supported either through Messaging or SOA solutions. Request/Response support is not yet defined
Information Interchange between organizations (e.g. in a RHIO, or in a National Health System)
  • Pub/sub using bundles (push or pull)
  • RESTful interface
  • FHIR messaging
Structured / Unstructured clinical document, e.g. dictated surgical note See the Documents

The combination of a properly secured and managed FHIR server, along with enforced use of the AuditEvent and Provenance resources ensures that the core record management functions defined in the EHR-S FM are met (as follows). See the FHIR Record Lifecycle Event Implementation Guide for additional details.

Additional functionality, not defined at this point in time in FHIR, is required to ensure non-repudiation, access control, and consent tracking.


element-definitions.html

Element - Detailed Descriptions

Maturity Level: NormativeStandards Status:Normative

Element


element-extras.html

Element Extensions (can be used anywhere)

Maturity Level: N/AStandards Status:Informative

This extensions defined here can be used on any element. For background information, see Extensibility. Additional extensions may be found in published Implementation Guides, or in the Conformance resource registry.


element.html

Element

Maturity Level: NormativeStandards Status:Normative

The base definition for all elements contained inside a resource. All elements, whether defined as a Data Type (including primitives) or as part of a resource structure, have this base content:

There are 3 kinds of descendant types that specialize Element:

Note that resources themselves all specialize the base type Resource.

Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ElementIn/aBase for all elements
All FHIR elements must have a @value or children
... id0..1stringUnique id for inter-element referencing
... extension0..*ExtensionAdditional content defined by implementations

doco Documentation for this format

XML Template

<[name] xmlns="http://hl7.org/fhir" id="Internal id (e.g. like xml:id) (string)"> doco
 <extension><!-- 0..* Extension Additional content defined by implementations --></extension>
</[name]>

JSON Template

// complex types:

{doco
  "id" : "<string>", // Internal Id
  "extension" : [{//  Additional content defined by implementations
    // from Element: extension (recursive)
    "url" : "<uri>", // R!  identifies the meaning of the extension
    "value[x]" : <*> // identifies the meaning of the extension
  }]
}
// primitive types:

{doco
  "{name}" : "value",  // The primitive value
  "{name}_" : { // Special syntax for the id and extensions
    "id" : "<string>", // Internal Id
    "extension" : [{//  Additional content defined by implementations
      // from Element: extension (recursive)
      "url" : "<uri>", // R!  identifies the meaning of the extension
      "value[x]" : <*> // identifies the meaning of the extension
    }]
  }
}

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ElementIElementBase for all elements
All FHIR elements must have a @value or children
... id0..1stringUnique id for inter-element referencing
... extension0..*ExtensionAdditional content defined by implementations

doco Documentation for this format

XML Template

<[name] xmlns="http://hl7.org/fhir" id="Internal id (e.g. like xml:id) (string)"> doco
 <extension><!-- 0..* Extension Additional content defined by implementations --></extension>
</[name]>

JSON Template

// complex types:

{doco
  "id" : "<string>", // Internal Id
  "extension" : [{//  Additional content defined by implementations
    // from Element: extension (recursive)
    "url" : "<uri>", // R!  identifies the meaning of the extension
    "value[x]" : <*> // identifies the meaning of the extension
  }]
}
// primitive types:

{doco
  "{name}" : "value",  // The primitive value
  "{name}_" : { // Special syntax for the id and extensions
    "id" : "<string>", // Internal Id
    "extension" : [{//  Additional content defined by implementations
      // from Element: extension (recursive)
      "url" : "<uri>", // R!  identifies the meaning of the extension
      "value[x]" : <*> // identifies the meaning of the extension
    }]
  }
}

 

Constraints

This constraint exists to reduce syntactical variation in resource contents. If an element has no children, then it is always omitted from the resource, as opposed to optionally present without any content.

Representation of Element

As the base type for all elements included in a resource, Element is an important structural element of FHIR. Even the primitive types inherit the base features and representation rules that apply to the Element type.

XML Representation

Elements are represented by an XML element. The name of the element comes from the context in which it is used, not from the type. The internal id is represented as an attribute (similar to xml:id, but see below about scope). Extensions are represented as XML elements. Here is the representation for an element 'use' of type Coding:

  <use id="[internal id]">
    <extension url="..."/>
      ... if there are any extensions
    <extension>
    .. elements of Coding type...
  </use>

Primitive types have the same representation; the actual primitive value appears as an XML attribute named value on the XML element. For example, a code property named "status" will be represented like this:

  <status id="[internal id]" value="[value of code]"">
    <extension url="..."/>
      ... if there are any extensions
    <extension>
  </status>

JSON Representation

Elements (except for primitive types, see below) are represented by a JSON object property. The name of the property comes from the context in which it is used, not from the type. The internal id is represented as a JSON string property named "id". Extensions are represented in a JSON array of objects named "extension". Here is the representation for a property 'use' of type Coding:

  {
    "use" : {
      "id" : "[internal id]",
      "extension" : [
        ..extensions, if present...
      ],
      .. properties of Coding type...
    }
  }

Primitive types are represented differently; the actual primitive value appears as a JSON string or number property. If an internal id or extensions are present, they appear in a JSON object with the name of the primitive value property with "_" prepended. For example, a code property named "status" will be represented like this:

  {
    "status" : "[value of code]",
    "_status" : {
      "id" : "[internal id]",
      "extension" : [
        ..extensions, if present...
      ]
    }
  }

The exact use of this pattern is described here.

Internal Id Scope

The id property of the element is defined to allow implementers to build implementation functionality that makes use of internal references inside the resource. This specification does not define any general use for the internal id, though some resources (e.g. StructureDefinition) and extensions (e.g. originalText, narrativeLink) make use of it.

The internal id is unique within the scope of the resource that contains it. Specifically, this means:

These rules ensure that there is no need to change internal identifiers while exchanging resources.


elementdefinition-definitions.html

Element Definition Detailed Descriptions

Maturity Level: NormativeStandards Status:Normative

ElementDefinition


elementdefinition-examples.html

Element Definition Examples

Maturity Level: N/AStandards Status:Informative

For ElementDefinition examples, see the extensive StructureDefinition example list.


elementdefinition-extras.html

ElementDefinition Extensions

Maturity Level: N/AStandards Status:Informative

This extensions defined here can be used on any ElementDefinition. For background information, see Extensibility. Additional extensions may be found in published Implementation Guides, or in the Conformance resource registry.


elementdefinition-mappings.html

Element Definition Mappings

Maturity Level: N/AStandards Status:Informative

This page provides mappings for Element Definition (see Mappings to Other Standards for further information & status).

Many other standard frameworks define frameworks for defining "data elements". These overlap to some degree with the ElementDefinition type. This page provides general mappings between ElementDefinition and the other frameworks. One important consideration with regard to other Element definition frameworks is the scope of the definition. Many of these definition frameworks use the term "Data Element" to refer to a data item that is collected and stored with provenance, such as when it was collected, who recorded it, etc. In this specification, that's an Observation, and the definition of those kind of data element is an ObservationDefinition, or a StructureDefinition that contains several different atomic data items. An ElementDefinition in this specification is a narrower notion, solely around the characteristics of a single element, it's definition, and it's value domain. Other frameworks - especially ISO 11179 - are used in both ways, sometimes with no formal differentiation between them. For this reason, the mappings on this page are very provisional, and are provided with the intent of helping implementers understand the possible relationships.

On this page:

v2 Mappings to the V2 segment OM1 which is used to define observations (i.e. also related to ObservationDefinition)
RIM Mappings to the RIM class Observation in definition mood which is used to define observations (i.e. also related to ObservationDefinition)
IHE DEX Mappings IHE Data Element Exchange, which is closer to defining atomic data elements - still very incomplete
LOINC Mappings to the LOINC master table which defines observations (i.e. also related to ObservationDefinition)
ISO 11179 Mappings to ISO 11179 which details how the ElementDefinition class relates to the ISO 11179 framework. Note that the principle differences are that FHIR does not differentiate between a Data Element and a Data Element Value, and the FHIR specification is heavily type dependent. Also, the FHIR specification includes constraints and other concerns that are outside the scope of ISO 11179

elementdefinition.html

Element Definition

Maturity Level: Normative Standards Status: Normative

The definition of an element in a resource or an extension. The definition includes:

The ElementDefinition type is the core of the FHIR metadata layer, and is closely (conceptually) aligned to ISO 11179. All the data elements defined in this specification are published as a collection of data elements (XML or JSON).

ElementDefinition is used in

Content

Constraints

 

Use of ElementDefinition.path

The path element is the most important property of the element definition. It both names the element, and locates the element within a hierarchy defined within a particular context. Within the FHIR specification, there is only one original definition for each path. This is the master definition to which all the other definitions with the same path must conform.

All elements defined within the FHIR specification itself are defined within a StructureDefinition that defines a resource, or a datatype. This defines the identity of the element and provides the context in which the meaning of the element is understood. When Elements are defined, the following rules apply:

Elements may be defined in:

StructureDefinitions with derivation = constraint (i.e. Resource and Data Type profiles) are not allowed to define or include ElementDefinitions with a path not defined within the base type definition from which they derive (e.g. in the FHIR specification).

ElementDefinition.id

In addition to the path, every ElementDefinition SHALL have a populated id, and the id SHALL have a unique value populated by following this algorithm:

Note that in a profile with no slices, this id will match the path exactly and entirely. id values constructed in this fashion are unique, and persistent, and may be used as the target of external references into the definition, where necessary.

Interpretation of ElementDefinition in different contexts

The data type ElementDefinition is used in StructureDefinition. The way its elements are to be used and interpreted depends on the context:

ElementDefinition field Type definition, first element Type definition, following elements Constraint Definition, first element Constraint Definition, following elements
sliceName prohibited prohibited prohibited required for slices, else prohibited
label optional optional recommended recommended
code optional optional optional optional
slicing prohibited prohibited prohibited optional
short/definition required required required required
requirements/
comments/alias
prohibited optional prohibited optional
base snpshot: required
differential: optional
snpshot: required
differential: optional
required required
type required required optional optional
nameReference prohibited optional prohibited optional
min/max optional (irrelevant) required optional optional
defaultValue[x] prohibited optional prohibited optional
meaningWhenMissing prohibited optional prohibited optional
fixed[x] prohibited prohibited prohibited optional
pattern[x] prohibited prohibited prohibited optional
example[x] prohibited optional prohibited optional
minValue[x] prohibited prohibited prohibited optional
maxValue[x] prohibited prohibited prohibited optional
maxLength prohibited prohibited prohibited optional
mustSupport prohibited prohibited optional optional
isModifier prohibited optional prohibited optional
isSummary prohibited optional prohibited optional
binding prohibited optional prohibited optional
constraint optional optional optional optional
condition prohibited optional prohibited optional
mapping optional optional optional optional

Notes:

The use of Path and type depends more deeply on the context where the ElementDefinition is used:

Context path (1st element) path (following elements) type (1st element)
Base definition of a data type
(example: Quantity - XML, JSON)
Name of the type Path inside the datatype Element
A constrained data type
(example: Money - XML, JSON)
Name of the base type Path inside the datatype Name of the base type
Base definition of a resource
(example: Patient - XML, JSON)
The name of the resource Path inside the resource DomainResource or sometimes Resource
Constraint on a resource
(example: DAF Patient - XML, JSON)
The name of the resource Path inside the resource
(including into the data types)
The name of the resource
Base Extension (which is a standard data type)
(example: Extension - XML, JSON)
Extension Extension.value[x] or Extension.extension Extension
A defined Extension
(example: Extension - XML, JSON)
Extension Extension.value[x] or Extension.extension (for complex extensions) Extension

There are additional notes about the use of ElementDefinition when defining Extensions on the Defining Extensions page.

Rules about Slicing

For a description of slicing, see Slicing

Constraining elements with a choice of Type

Elements that allow a choice of multiple types can be constrained. In principle, there are two different types of constraints to apply:

When constraining elements with multiple types, the following rules apply:

Rules about min and max

Rules about Aggregation

Missing Elements

Most elements have a minimum cardinality of 0, which means that they may be missing from a resource when it is exchanged between systems. Generally, when an element is missing, all that an application processing the resource can say about the element is that the value is unknown - it may have a correct value, but it has not been provided for security or workflow reasons. On the other hand, it might not have a value at all. All the application can say is that the value is unknown.

This also applies when the element is present, but has no value or child elements, and only has extensions instead.

However, for some elements, this specification makes specific rules about what it means if the element is missing. Constraints on other structures cannot change the missing meaning of an element. Here is a list of all elements with a default value or a missing meaning:

This specification does not define any default values for resources or data types because:

Note that default values can be defined in Logical Models.