Ewout Kramer San Antonio TX January 2015 Updated for FHIR DSTU2 httpwwwslidesharenetewoutkramerfhirprofilingtutorial Who am I Name Ewout Kramer Company Furore ID: 541724
Download Presentation The PPT/PDF document "Profiling FHIR" is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.
Slide1
Profiling FHIR
Ewout KramerSan Antonio, TX – January 2015
Updated for FHIR DSTU2!
http://www.slideshare.net/ewoutkramer/fhir-profiling-tutorialSlide2
Who am I?
Name: Ewout
KramerCompany: Furore, AmsterdamBackground:FHIR core team, RIMBAASoftware developer & healthcare architectContact:e.kramer@furore.comwww.thefhirplace.comSlide3
Introduce ourselves
Who has looked at Profiling FHIR in the spec for more than 5 minutes?Who has near-future needs for authoring profiles?Slide4
Contents of this tutorial
Introduction to profiling
MetadataRestricting resources
Bindings
Formal constraints
Extensions
SlicingSlide5
Introduction
to profilingSlide6
The need for
profiling FHIRMany different contexts in
healthcare, but a single set of operations and ResourcesNeed to be able to describe restrictions based on use and contextAllow for these usage statements to be:Authored in a structured mannerPublished in a repositoryUsed as the basis for validation, code, report and UI generation.Slide7
Uses for profile packages
Server & client may publish and check their conformance to a profile package
Validating instances, messagesImplement "FHIR spec-like" website from Profiles as part of an Implementation GuideSlide8
In v3 CDA…”text-based”Slide9
openEHR ADL
…computable!Slide10
Conformance package
- normal resources
CompositionExtension DefinitionProfile
ValueSet
Search
Parameter
…computable!
Operation
Definition
Naming
SystemSlide11
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”++Slide12
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 internationalAdd an extension to support “RaceCode”Note: hardly any mandatory elements in the core spec!Slide13
Extend/restrict the API
Add operations to turn a FHIR server into a Terminology serverAdd operations for merging patientsSlide14
Compliance
Publication
Guidance
Implementation
Find
& maintain
Retrieve & use
RepositorySlide15
Who publishes?
http://www.hl7.org/Profile/iso-21090
http://www.hl7.nl/Profile/patient-nlhttp://www.health4all.nl/h4all-vitals
http://www.fit4all.nl/f4all-vitals
http://www.data4all.nl/d4all-obsSlide16
Declaring conformance
Patient
MRN 22234“Ewout Kramer”30-11-1972Amsterdam
“
I’m
a
Patient
conforming
to
the
Norwegian
Profile –
see
http://hl7.no/
Profiles
/
patient
-no
”
“
I’m
a
Patient
conforming
to
the
ContosoHIS
Profile –
see
http://contoso.no/
Profiles
/
patient”
in
Patient.meta.profileSlide17
(Distributed) validation
ContosoHIS’s
serverNorway national validation serverValidate NO
Profile Contoso
Profile NO
Download & Validate
Store
Profile NO
Profile
ContosoSlide18
Write by hand? Forge!Slide19
Running example…
We are taking the “Lipid Profile” example from the spec from now on.This is a DiagnosticReport
, containing 4 results:1x Cholesterol1x Triglyceride1x HDL Cholesterol0/1x LDL CholesterolAnd package it up in a messageSlide20
Preparing the Conformance Package
Let’s do this in ForgeChoose: “File
New”Click “Edit Package Properties” on the left of the screenUnder “Meta Properties” enter values for the mandatory fields& SaveSlide21
Metadata and versionsSlide22
Conformance
Package - Bundle
What’s in a profile?Composition“Lipid Profile” by e.kramer@furore.comProfile“LipidProfile
”
ExtensionDefinition
“calculated
”
Profile
“Triglyceride”
Profile
“
LDLCholesterol
”
DiagnosticReport
instance (via
meta
)
DiagnosticReport
instance (via meta)
DiagnosticReport
instance
(via meta)
SectionSlide23
Metadata
Profile
ExtensionDefinitionSearchParameterOperationDefinitionValueSetNamingSystemurlurlurlidentifieridentifier identifieridentifierversion versionversion
name
name
name
title
name
name
publisher
publisher
publisher
publisher
publisher
telecom
telecom
telecom
telecom
telecom
description
description
description
description
description
description
copyright
status
status
status
status
status
experimental
experimental
experimental
experimental
date
date
date
datecodecodeSlide24
Referring to a profile
http://acme.org/Profile/lipids-v1
1. Where?DiagnosticReportLipid Report
Wile E. COYOTE
2009-03-03
14:26
Cholesterol 6.3
mmol
/L
Triglyceride 1.3
mmol
/L
HDL
Chol
. 1.3
mmol
/L
LDL
Chol
. 4.2
mmol
/L
Dr. Pete Pathologist,
Acme Labs
DiagnosticReport.meta.profile
http://acme.org/Profile/lipids-v1
http://
acme.org/Profile/
87408b94
( or
any
valid technical FHIR id, not
necessarily “comprehensible
”
)
orSlide25
Identifiers
So, Profile has a REST id on a server
Might not be under your control, server assignedBut also:A “url” – A canonical url that identifies the profileA “name” – human readable, e.g. “Lipid Profile”An “identifier” – author-assigned, globally uniqueOID (2.16.840.1.113883.10.20.2.1)UUID (09bd961e-c629-11e3-8841-1a514932ac01)URN (urn:openEHR.org:EHR-ACTION.medication.v1)Slide26
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? Slide27
“Non-breaking change”?
If old data can still be:Validated against the new profile
Correctly interpreted against the new profileThis 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 profileThe profile’s author-assigned identifier changesA new Profile on the server, with a new REST utlSlide28
Versioning schema
We used semantic versioningUses “<major>.<minor>.<patch>”
See semver.orgMajor version number is increased on breaking changesMajor version number is part of author-assigned identifier AND REST urlBoth versions may co-exist on server, they have different URLs and namesSlide29
Example
Url
http://acme.org/Profile/patient.v1Idurn:acme.org:profile:patient:v1Version1.0.0Urlhttp://acme.org/Profile/patient.v1Idurn:acme.org:profile:patient:v1Version1.0.1…after a small typo, clarification or correction (“bugfix”) becomes……after a bigger non-breaking change, like an addition, becomes…Url
http://acme.org/Profile/patient.v1
Id
urn:acme.org:profile:patient:v1
Version
1.1.0
Url
http://acme.org/Profile/patient.v2
Id
urn:acme.org:profile:patient:v2
Version
2.0.0
…after a breaking change (like cardinality) becomes…Slide30
Authoring a Resource Profile
Let’s do this in ForgeIn the middle under Profiles click “Add” and choose “
DiagnosticReport”Edit the Profile Properties on the left of the screen& SaveSlide31
31Slide32
Restricting resourcesSlide33
Profile –a normal resource
…computable!Slide34
Profile –a normal resource
ElementDefinition
Path: Patient.nameType: HumanNameCardinality: 0..*EtceteraSlide35
Profiles
A set of constraints on (nested) elements of a Resource or DatatypeSort of a “subclass” of a Resource, with specific limits on its elements
CardinalityValue domainsInvariantsSlide36
Observation resourceSlide37
Example
“Cholesterol observation” is an Observation :
That has a fixed LOINC code 35200-5 (Cholesterol) as its nameHas a quantity as value that’s expressed in mmol/L (a UCUM unit) (without a ‘comparator’) OR ELSE there’s a commentAn interpretation limited to LL,L,N,H,HHA “recommended” high reference range of 4.5 (no low) mmol/L, independent of age (no age)Is an independent observation (no related)Slide38
Let’s start constraining
0
..1
= ‘ok’
“if no value…”
1..1
1..1
Subject 0..1? Why not 1..1 in spec?Slide39
Constraining a Resource
Let’s do this in ForgeIn the middle, under “Profiles” press “Add”
Name the Profile “Cholesterol” using the property panel on the leftStart setting the cardinalities for each element, by clicking on them in the middle and using the property panelSlide40
40Slide41
Referring to a profile
http://acme.org/Profile/lipid-cholesterol
ObservationCholesterol6.3 mmol
/L
High
(recommended 4.5)
Observation.meta.profile
http://acme.org/Profile/lipid-cholesterolSlide42
Reusable constraints
We have multiple components within the “Lipid Profile” package with QuantityAll
with the same constraints Units are mmol/Lin UCUM (http://unitsofmeasure.org) no comparatorLet us first make a reusable “lipid quantity” constraint on the Quantity datatype!Slide43
bindingsSlide44
Coded types
Codes are defined in
code systemsWe may want to limit the codes that can possibly be used in coded elements in the ResourcesSlide45
“Code System”
CodeSystem
vs. ValueSet“Dante’s deadly sins”PrideEnvyWrathSlothAvariceGluttonyLust“ValueSet”Takes
concepts
from…
An enumeration of terms
Defintion
of terms
Example: SNOMED-CT
Example: “Childhood diseases”Slide46
“Special” cases
“All words under B”
“All words in theMerriam-Webster dictionary”Takes concepts from…
No need to write them all down!
Takes
concepts
from…
Takes
concepts
from…
“Words for ‘nerd’”
Bookworm
Geek
Grind
Weenie
Wonk
Dink (slang)
Dork (slang)
Swot
(slang)
Can take concepts from
multipe
codingsystems
!Slide47
Identification of CodeSystems
If you refer to CodeSystems, you use a URL (instead of OID in v2 and v3):
http://snomed.info/scthttp://loinc.orghttp://hl7.org/fhir/sid/icd-10We have introduced them for v2 and v3:http://hl7.org/fhir/v2/0078http://hl7.org/fhir/v3/ActClassSlide48
Coded types (again)
The
url of the systemMay aid interpretationSlide49Slide50
50
MetadataIn/exclude conceptsThis 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
ValueSetsSlide51
51
But it can also enumerate (and so indirectly
define) all concepts for a new codesystemA ValueSet is built by defining terms from and for a new CodeSystemThese new concepts have a display label and a definition …and may be hierarchically organizedSlide52
Bindings
When used in a Resource, the modelers include BindingsBindings specify which codes can be usedSlide53
Profiling bindings
Depending on “core” spec, you can:“fixed”: not specify a different binding
“incomplete”: specify a different binding if needed“example”: very likely specify a different bindingChange the bindings as specified in core:Define a new ValueSet Allow additional codes, Restrict to a subsetSpecify whether implementers of your profile can deviate from your valueset.Slide54
ValueSets
In order of precision:A “true” FHIR
ValueSet resource (may be version specific)A general reference to some web content that defines a set of codes (e.g. mime types). A textual description of the possible codes Slide55
Interpretation Binding
Let us limit http://hl7.org/fhir/vs/observation-interpretation
Let’s Define a new ValueSet using codes from the existing Code systemhttp://hl7.org/fhir/v2/0078Slide56
This is not too hard…Slide57
Conformance levels
IsExtensible
“N”IsExtensible “Y”Required “SHALL”Validation error, non-conformantAdditional codes allowedPreferred “SHOULD”“Guidance”Validation warning, discouragedSupplemental codes likelyAlternatives allowedExample “MAY”Just a suggestion, no preferenceIf implementers of your profile provide a different code than you have in your profile….Slide58
Must support?
Authors: SHALL be capable of providing a value for the element and resourceConsumers:
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 elementSlide59
Refer to ValueSet
And now…make the Profile point to the newly created ValueSet using ForgeSlide60
Formal constraintsSlide61
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.Slide62
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 idSpecify severity (“error” or “warning”)Slide63
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 constraintWe assign the constraint a “key” value that’s unique within the Observations’ constraintsWe 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” Slide64
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 emptyIn Xpath: exists(f:valueQuantity) or exists(f:comment)That’s a logical or, so not exclusive!Slide65
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)Slide66
Add constraint
Let’s do this in ForgeClick the Cholesterol Observation (that’s the context, remember!), add under the “Constraints” in the property panel
Give it key “chol-01”Click both “value[x]” and “comment” and set their condition to “chol-1”.Slide67
extensionsSlide68
Extensions
Add the fact that: “an LDL Cholesterol value is calculated”
There’s no such indication on Observation (or Observation.value) -> Extension!!Note!! - You’re not extending a resource per se, but you specify where an extension applies. This may be multiple places. So “haircolor” may be applied to “Patient” and “Practitioner”Slide69
ExtensionDefinition
–a normal resource
ElementDefinitionPath: Patient.nameType: HumanNameCardinality: 0..*EtceteraSlide70
Extension Context
An extension has a context typeResource,
Datatype, Extension, MappingAnd 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!)Slide71
Extension definition
Note: multiple
contexts!Slide72
Extending
a name
Key = location of formal definitionValue = value according to definitionSlide73
Complex extensionsSlide74
Complex extensionsSlide75
The “Basic” resource
Now, what if you have the need for a completely “new” resource?
…then add extensions for each elementSlide76
Authoring an extension
Let’s do this in ForgeOpen the “Extensions” tab in the middle of the screenPress “Add”
Give it a name, context and datatypeSlide77
slicingSlide78
Where are we?
Cholesterol
Observationname: loinc.org#35200-5TriglycerideObservationname: loinc.org#35217-9
HDL Cholesterol
Observation
name: loinc.org#2085-9
LDL Cholesterol
Observation
name: loinc.org#
13457-7
Quantity (
lipidQuantity
)
use
ValueSet
(
lipidInterpretation
)
bind
Extension
(calculated)
boolean
applies
to
TODO:
DiagnosticReport
containing
4
results:
1x Cholesterol
1x Triglyceride
1x
HDL
Cholesterol
0/1
LDL CholesterolSlide79
The Diagnostic Report
Cholesterol
TriglycerideHDL Cholesterol
LDL Cholesterol
= loinc.org#57698-3
(Lipid
panel with direct
LDL)
1
1
1
0/1Slide80
Slicing!
Reference(Observation)
Result: Reference(Observation)Reference(Observation)Reference(Observation)
ResourceReference
(Observation)
Reference(Observation)
ResourceReference
(Observation)
…
Cholesterol
Observation
name: loinc.org#35200-5
Triglyceride
Observation
name: loinc.org#35217-9
HDL Cholesterol
Observation
name: loinc.org#2085-9
LDL Cholesterol
Observation
name: loinc.org#
13457-7
0..*
3
..4
Reference(Observation)
Discriminator
1..
1
1..
1
1..
1
0
..
1
"There MUST be
exactly one
Observation
with
LOINC 35200-5
. And if you find it, it
must conform to our
"Cholesterol" StructureSlide81
Properties of slices
Each slicing group indicates a discriminator
here, that is Observation.nameEach slicing group indicates a cardinalityhere, that was 3..4Each slice indicates its own cardinality within the slicehere 1..1 for chol,trig,hdlc, 0..1 for ldlcEach slice indicates additional constraintshere "must conform to Cholesterol profile" etc. Slide82
Authoring slices
Let’s do this in ForgeClick "result" and then "Slice" above property panel
Indicate the discriminator and the cardinality for the whole sliceClick "Add slice" (4x), and name each slice, give it the cardinality, tie Reference to "cholesterol", "triglyceride" etc.Slide83
One step further!
Cholesterol
TriglycerideHDL Cholesterol
LDL Cholesterol
DiagnosticReport
data: Reference(
DiagnosticReport-lipidPanel
) 1..1
Package the
DiagnosticReport
in a "
LipidResultMessage
"Slide84
FHIR server @ hospitalA.org
Practitioner Bernard
FHIR server @ lab.hospitalA.orgMessageHeader
Diagnostic
Report A
data
In REST: Possibly distributed…
FHIR server @ pat.registry.org
Patient Joe
subject
performer
FHIR server @
lab2.hospitalA.org
HDL
Obs
34
Triglyceride
Obs
78
Cholesterol
Obs
1
resultSlide85
Aggregation
Aggregation: for each ResourceReference choose one to all of these options:
CodeDefinitioncontainedReference to a contained resource.referencedReference to a resource that has to be resolved externally..bundledReference points to will be found in the same
bundle
read:
Message,
DocumentSlide86
Authoring aggregation
Let’s do this in ForgePick any of the
ResourceReferences in the model.Notice none of the checkboxes next to a ResourceReference is checked: all aggregation types are allowedNow select those checkboxes to changeSlide87
Finally…
“Conformance Package” tab on each Resource, e.g.:http
://hl7.org/implement/standards/FHIR-Develop/patient-packages.htmlForge downloadhttp://fhir.furore.com/forge/http://fhir.furore.com/Tooling/ProfileEditorFind this presentation on SlideShareSlide88
Questions?