© 2015 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg.

© 2015 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

FHIR for Specifiers

Michel Rutten

Hilversum, 12 november 2015


Who am I?

Name: Michel Rutten Company: Furore, Amsterdam Background:

Professional software developer since 1998 Microsoft .NET; Healthcare industries Technical Specialist at Furore since May 2014 Member of the Furore FHIR development team Tool Smith - Lead developer of Forge


Contents of this tutorial

FHIR 1.0 DSTU 2 Introduction to FHIR Conformance Layer Principal components FHIR Conformance Resources Implementation Guides ValueSet StructureDefinition Registry


FHIR 1.0 DSTU2Overview of changes


5

DSTU 2 Version History

Version Name Publication date

1.0.0 DSTU 2 QA Preview Aug 31 2015

1.0.1 DSTU 2 Sept 23 2015

1.0.2 Technical Correction 1 Oct 24 2015


Maturity Framework

Level Description

0 Published on current build

1 Produces no warnings during the build processSubstantially complete and ready for implementation

2 Successfully exchanged between 3+ systems at a connectathonResults reported to the FHIR Management Group

3 Meets DSTU Quality Guidelines Subject to a round of formal balloting; 10+ implementer comments drawn from 3+ organizations resulting in 1+ substantive changes.

4 Tested across its scopePublished in a formal publication (e.g. DSTU)Implemented in multiple prototype projects.Sufficiently stable to require implementer consensus for subsequent non-backward compatible changes.

5 Published in two formal publication release cycles at FMM1+ (i.e. DSTU level)Implemented in 5+ independent production systems in >1 country


7

RESTful API

Add batch Several clarifications around versioning &

transactional integrity Changed Bundle URL resolution rules


8

Search

Changed the way <> etc. works Added _list parameter Changed rules around contained and

included resources


9

Data Types

New data types Markdown Annotation

Changed data types Coding Quantity Signature Timing Address ContactPoint


10

Data Types

Changes to ElementDefinition Add base

Specifies path & cardinality of base element Make type.profile repeat

Target resource must conform to all profiles Remove constraint.name and replace with

constraint.requirements Remove binding.name Add minValue[x] and maxValue[x]


11

Resources

New Account ImplementationGuide TestScript

Removed Supply


12

Resources

Renamed resources Contraindication -> DetectedIssue MedicationPrescription -> MedicationOrder QuestionnaireAnswers -> QuestionnaireResponse


13

Resources

Changed Almost all resources Too many to list (1317 tasks worth of changes) Add, remove elements Change types, references, definitions & value sets Re-order elements Provide much more documentation and new

examples


14

Implementation Guides

Move Argonaut content out http://argonautwiki.hl7.org/index.php?title=Main_Page


15

1.0.1

Changes of significance during the QA process: Remove the Clinical Quality Improvement

Framework (CQIF) from this published version Made fixes to generated schematrons Updated generated comformance resources

(StructureDefinitions and SearchParameters) so they were consistent with the specification

Many spelling / grammar / broken link fixes


1.0.2

Series of technical corrections to the specification following extensive review: Corrections to Extension cardinalities in

implementation guides Corrections in the conformance resources that

support the specifications Correct several erroneous invariants Various typos, broken links, and fixes in examples For a comprehensive list of corrections, see the

Task list for FHIR DSTU2 Technical Correction 116


PRINCIPAL COMPONENTSFHIR CONFORMANCE LAYER


22

Conformance Resources

Terminology

Naming System

Value Set

Concept Map

Content

Structure Definition

Data Element

Operations

Conformance

Operation Definition

Search Parameter

Misc.

Implementation Guide

Test Script


23

Conformance

Conformance Resources

23

“Profile”

StructureDefinition

SearchParamDefinition

ValueSet

ConceptMap

NamingSystem OperationDefinition

Forge

ExcelImplementation

Guide

TestScript


24

Terminology

• Define which terminologies to use in which elements

ValueSet

• Define namespaces with unique symbols

NamingSystem

• Define mappings between terms from different systems

ConceptMap


25

Content

• Define data structures• Define restrictions and/or extensions

StructureDefinition

• Define data elements (ISO 11179)

DataElement


26

Operations

• Define server capabilities• Define supported API methods

Conformance

• Define additional (custom) operations

OperationDefinition

• Define additional (custom) searches

SearchParameter


27

Miscellaneous

• Author and publish an implementation guide

ImplementationGuide

• Define compliance tests against a FHIR server

TestScript


OVERVIEWFHIR CONFORMANCE RESOURCES


29

ImplementationGuide

• Define scope of usage• Describes requirements for an implementation


30

ImplementationGuide

Usage: Allow authors to publish an implementation

guide Allow tools to validate conformance Computable!


32

StructureDefinition

Defines datastructures• Core resources & datatypes (see validation.zip)• Constraints on resources & datatypes• Extensions

http://hl7-fhir.github.io/downloads.html


33

StructureDefinition

Share/publish to repository / registry Compare Validate resource Use to drive

Code generation Report generation UI generation (e.g. ClinFhir ResourceBuilder)

Computable!


NamingSystem

Describes “logical” numbering systems in use• What’s the name?• What are equivalent uri/uuid/oids

Represents a "System" used within the Identifier and Coding data types.


35

ValueSet

Define codes


36

ValueSet

Code System Defines a set of codes with meanings (also

known as enumeration, terminology, classification, and/or ontology)

Value Set Selects a set of codes from those defined by

one or more code systems


37

ConceptMap

Define mappingFrom one set of concepts to one or more other concept(s)


OperationDefinition

• Extend/restrict the API• Defines interactions


39

OperationDefinition

Describes additional operations over and above the RESTful interactions defined in the specification What is the name? Input/output parameters What does it do? Works on which resources?


SearchParameter

Extend/restrict searchesDescribes additional searches to filter resources• What is the name?• Elements filtered• Resource the search works on


Conformance

A set of capabilities of a FHIR Server

Binds all conformance resources together


42

Conformance

Describes how a client or server uses or should use the FHIR API Which wire formats supported? Which resources? Which operations supported? Which profiles supported? Is this a test server? What’s the name of the software?


For implementer convenience, the specification itself publishes its base definitions using these same resources!

Used in the core spec


For implementer convenience, the specification itself publishes its base definitions using these same resources!

Used in the core spec


45

Define FHIR “Profiling”?

General term: The process of creating an implementation

guide The process of creating a conformance

package The process of creating a conformance

resource


IMPLEMENTATION GUIDES


47

Examples

fhir.hl7.org Implementation > Implementation Guides

Argonaut DAF QICore SDC USLab


48

Different Kinds

Strategy•National scope guide•e.g. infrastructure, security

Principles•Overarching principles•e.g. basic components

Subject•Subject with multiple usecases•e.g. medication process

Usecase•Single usecase•e.g. prescription


50

Typical Content

Title Table of contents Document information Introduction to the guide Principles & background Functional requirements and high-level use cases Design considerations Package contents (= use case?) Privacy and security guidance Testing and certification Appendix List of all artifacts used in this guide


ImplementationGuide

New resource type introduced in DSTU2 1.0

Defines: Conformance Packages Documentation Pages Global Profiles Dependencies


Conformance Package

Defines a set of conceptually related conformance resources

Provides example resources Allows conformance validation of resources


Documentation Pages

Provides detailed description of the included conformance resources

E.g. HTML, Markdown Binaries: css, js, img, …


54

Global Profiles

A set of profiles that all resources covered by this implementation guide must conform to

Note: A resource can conform to the default profile by conforming to any profile derived from it


55

Dependencies

Other ImplementationGuide resources this guide depends on

Type Reference (hyperlink) Inclusion (embed)


56

Publish!

Test & Verify

Publish

Guide

Author & Store

Implementhttp://simplifier.nethttp://registry.fhir.org

http://simplifier.net/


http://registry.fhir.org/


57

Forge - Lipid


VALUE SETS


Coded types

Codes are defined in code systems

In a Profile, we may want to limit the codes that can possibly be used in coded elements in the Resources


“Code System”

CodeSystem vs. ValueSet

“Dante’s deadly sins”

PrideEnvyWrathSloth

AvariceGluttony

Lust

“ValueSet”

Takes concepts from…

An enumeration of terms

Definition of terms

Example: SNOMED-CT Example: “Childhood diseases”


“Special” cases

“All words under B”

“All words in theMerriam-Webster dictionary”


No need to write them all down!



“Words for ‘nerd’”

BookwormGeekGrind

WeenieWonk

Dink (slang)Dork (slang)Swot (slang)

Can take concepts from multipe codingsystems!


Identification of CodeSystems

If you refer to CodeSystems, you use a URL (instead of OID in v2 and v3): http://snomed.info/sct http://loinc.org http://hl7.org/fhir/sid/icd-10

We have introduced them for v2 and v3: http://hl7.org/fhir/v2/0078 http://hl7.org/fhir/v3/ActClass


Coded types (again)

The uri of the system


ValueSets


66

ValueSets

This models what we have been discussing so far:

• A ValueSet has metadata (much like Profile: identifier, version, name, etc)

• A ValueSet is built by inclusion of terms from CodeSystems

• A ValueSet can exclude specific codes from other valuesets

• A ValueSet can import codes from other ValueSets

Metadata

Include/Exclude Concepts


67

ValueSets

But it can also enumerate (and so indirectly define) all concepts for a new codesystem

• A ValueSet has metadata (much like Profile: identifier, version, name, etc)• A ValueSet is built by defining terms from and for a new CodeSystem• These new concepts have a display label and a definition • …and may be hierarchically organized


Bindings

When used in a Resource, the modelers include Bindings

Bindings specify which codes can be used


Profiling bindings

Depending on “core” spec, you can: “required”: not specify a different binding “extensible”: specify a different binding if needed “preferred”: specify a different binding if desired “example”: very likely specify a different binding

Change the bindings as specified in core: Define a new ValueSet

Allow additional codes, Restrict to a subset Specify whether implementers of your profile can

deviate from your valueset.


This is not too hard…


71

ValueSet Editor

Grahame Apolon …


72

ValueSet Editor


73

ValueSet Editor


STRUCTUREDEFINITION


Profiling a resource

“Must use only the Dutch national patient identifier”

“Need to register an administrative race code for a Patient in the US”

“Patient Discharge documents must at least contain section “Discharge Medication” and section “Discharge Diagnosis”

“In our Patient registration system, we use these maritalStatus codes beyond those provided by HL7…”

“Our patient registration system, only supports having one single name per Patient”

+

+


Profiling a resource

Demand that the identifier uses your national patient identifier

Limit names to just 1 (instead of 0..*)

Limit maritalStatus to another set of codes that extends the one from HL7 international

Add an extension to support “RaceCode”

Note: hardly any mandatory elements in the core spec!


Uses for profiles

Server & client may publish and check their conformance to a profile

Validating instances, messages

Implement "FHIR spec-like" website from Profiles as part of an Implementation Guide


In v3 CDA…”text-based”


Write by hand…? Forge!


Publish!

http://simplifier.nethttp://registry.fhir.org

Find & maintain

Retrieve & use


http://registry.fhir.org/


Who publishes?

http://www.hl7.org/Profile/iso-21090

http://www.hl7.nl/Profile/patient-nl

http://www.health4all.nl/h4all-vitals

http://www.fit4all.nl/f4all-vitals

http://www.data4all.nl/d4all-obs


85

Fee

dbac

k

Layered profiles

HL7 Norge adapts Patient for Norway

Helse Nord/Vest/… introduces regional differences

Use-case specific constraints

Constrain

Constrain


(Distributed) validation

DIPS’s server

Norway national validation server

Validate NO

Profile HNIKT, DIPS

Profile NO

Dow

nload &

Validate

StoreProfile

NO

Profile

HNIK

T


87

Examples…

Let’s look at DAF Profiles

http://fhir.hl7.org Implementation

Implementation Guides• DAF

http://fhir.hl7.org/


METADATA AND VERSIONS


What’s in a profile?

Metadata “Lipid Profile” v1.0.0 Drafturn:acme.org:lipid-profile:v1Author: [email protected]

Structure “LipidProfile”Element Definitions …

StructureDefinition for DiagnosticReport

Extension “calculated”

StructureObservation“Triglyceride”

StructureObservation“LDLCholesterol”

DiagnosticReportinstances (via Tag)


Referring to a profile

ObservationCholesterol

6.3 mmol/LHigh(recommended 4.5)


Structure “cholesterol”

http://acme.org/

http://acme.org/StructureDefinition/LDLCholesterol

I’m conforming to

http://acme.org/StructureDefinition/LDLCholesterol


Versioning…

A “version” – author assigned So what if you change something after

publishing? Just a typo? Change of definition? Make something optional that wasn’t? Make something mandatory that was optional? Add an extension?


“Non-breaking change”?

If old data can still be:

1. Validated against the new profile

2. Correctly interpreted against the new profile This can only be determined by the profile’s

authors (and even depends on the way it is used) A breaking change means you are

producing a new profile The profile’s author-assigned identifier changes A new Profile on the server, with a new REST utl


Authoring a Profile

Excel

Let’s do this in Forge Click “New Profile” Select base resource, e.g. Observation Edit metadata on tab page “Properties”

Name URL

Save!


STRUCTURES



Conformance Package: Lipid Report

Extension“calculated”

StructureObservation“Triglyceride”

StructureObservation“LDLCholesterol”

Structure Diagnostic Report“Lipid Profile”

StructureObservation“HDLCholesterol”

StructureObservation“Cholesterol”

DiagnosticReportinstances (via Tag)




Structure “LipidProfile”Element Definitions …

StructureDefinition: DiagnosticReport

Structure DefinitionExtension“calculated”

Structure DefinitionObservation“Triglyceride”

Structure DefinitionObservation“LDLCholesterol”

Resource Reference


Structure Definitions

Profiles contain “Structure Definitions” Base definition of a core Resource or Datatype A set of constraints on (nested) elements of a

Resource or Datatype An extension definition


Observation resource


Let’s start constraining

0..1

= ‘ok’

“if no value…”

1..1

1..1 Subject 0..1? Why not 1..1 in spec?


Must support?

Authors: SHALL be capable of providing a value for the element and resource

Consumers: SHALL be capable of extracting and doing something useful with the data element.

"Something useful" is context dependent. The Profile SHALL describe what it means for applications to “support” the element


104

Lipid


FORMAL CONSTRAINTS


Formal constraints

…beyond cardinalities and bindings, there are a lot of other conditions you might want to formulate: “If a Cholesterol value result is not available, use

the comments field” “A patient’s birthdate must be on or before today’s

date” These may concern a single element, or

cover multiple elements.


Formal constraints

Uses free text (human) + xpath (executable) Constraints should be declared on lowest

element in the hierarchy that is common to all nodes referenced by the constraint.

Identified by (local) ‘Key’, involved elements refer to that id

Specify severity (“error” or “warning”)


Context of the constraint

• This constraint is on the elements “valueQuantity” and “comments”

• We would have to formulate this constraint on the Observation, this is the context of the constraint

• We assign the constraint a “key” value that’s unique within the Observations’ constraints

• We refer from both “value[x]” and “comments” to this “key”. This means: if my value changes -> revalidate the constraint

“If a Cholesterol value result is not available, use the comments field”


Example xpath

Keep in mind: the condition is satisfied when the XPath expression evaluates to “true”

“If a Cholesterol value result is not available, use the comments field”

Note: to use both is ok! Otherwise said: not both empty In Xpath: exists(f:valueQuantity) or exists(f:comment) That’s a logical or, so not exclusive!


More xpath

“Either a valueQuantity or a comment is permitted” not( exists(f:valueQuantity) and exists(f:comment) )

“Can only have normal range if there is a valueQuantity” exists(f:valueQuantity) or not(exists(f:normalRange))

Steal from the spec (e.g. from Profile)


EXTENSIONS


Extension Context

An extension has a context type Resource, Datatype, Extension, Mapping

And a context path (Resource) Observation

“The observation was calculated” (Resource) Observation.value

“The observation’s ‘value’ was calculated” (Datatype) Quantity

“This quantity was calculated” (any Quantity used in any resource!)


Extension Definition

Note: multiplecontexts!


Extending a name

Key = location of formal definition

Value = value according to definition


Extensions

Let’s find a representative extension for Practitioner

Add it to the Practitioner (and show it’s both a reference & a definition)


The “Basic” resource

Now, what if you have the need for a completely “new” resource?

…then add extensions for each element


FHIR REGISTRYSimplifier


Collaborate

Manage projects Authorize team members Collaborate on profiles Github integration


Publish

Publish your conformance resources User-friendly structure rendering Detailed descriptions for elements Download as XML, JSON Related example resources


Find

Find existing conformance resources Constraints & Extensions (StructureDefinitions) Value Sets Concept Maps Naming Systems Search Parameters Operation Definitions Conformance Packages Implementation Guides


Resolve

Resolve conformance resources by canonical Url Globally unique identifier SHOULD be the URL at which it is published Example:

http://example.org/fhir/StructureDefinition/MyPatient.xml

Alternative: Resolve from a global registry

http://example.org/fhir/StructureDefinition/MyPatient.xml


127

Simplifier.net


128

Search


129

Constraint


130

ValueSet


131

User


132

Project


133

Versioning strategy

FHIR Normative no breaking changes => OK! Published resources will always remain available

and functional

FHIR Draft (current phase) FHIR spec may introduce breaking changes How should registry handle breaking changes?


134

Versioning strategy

Registry is based on a specific version of the .NET FHIR API

Uploaded resources are tagged with current API version at time of upload

Registry displays a warning if current system API version differs from saved resource API version => Author should update the resource


135

Security

Under development…

https OAuth2 OpenID.Connect


136

Base url claims

Under development… Proposal:

User can issue a claim for a specific base url E.g. http://example.org/fhir/

Granted claim provides exclusive permission to publish conformance resources on this base url

Delegation; grant claim permissions to other users Conflicting claim requests => prove domain

ownership

http://example.org/fhir/


137

Forge Integration

Under development…

Configure your simplifier credentials & project(s) in Forge

Publish resources Publish ImplementationGuide packages Integrate simplifier resource rendering


Q&A


139139

International HL7 FHIR Developer DaysNovember 18-20, 2015 in Amsterdam

Education 34 tutorials/presentations

pick & choose

Connectathon Meet fellow developers Put FHIR to the test

Networking FHIR experts and authors on hand

http://fhir.furore.com/devdays

© 2015 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg.

Documents

hl7 health level

hl7 international

creative commons

tm office

specifiers fhir

dstu levelimplemented

dstu2overview of changes

substantive changes