Authoring profiles by Michel Rutten

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

Authoring Profiles

Michel Rutten

FHIR Developer Days

November 25, 2014


Who am I?

Name: Michel Rutten

Company: Furore

Background:

Professional software developer since 1998

Microsoft .NET; Healthcare industries

Technical Specialist at Furore since May 2014

Member of the Furore FHIR development team

Lead developer of Forge

2


TOPICS


Presentation Topics

Introduction

Resources

Profiles

Representations

Authoring Tools

Authoring Profiles

Metadata

Structures

Bindings

Constraints

Extensions

Slicing

4


PROFILESIntroducing


The need for profiles

Many different contexts in healthcare, but a

single set of Resources

Need to be able to describe restrictions

based on use and context

Allow for these usage statements to: Authored in a structured manner

Published in a repository

Used as the basis for validation, code, report and UI

generation.

17


Use of Profiles

Profile

Publish to repository

Report

Implementation guide

POCO

Conformance statement

Validate Resource

18


What is a profile?

Special resource

Statement of use of one or more FHIR

resources

Provides additional rules about how a type of

resource is utilized in a particular context of use, or

for a particular use case

Specify restrictions / constraints on resources

Specify extensions on resources

19


Profiling a resource

Profiled

Resource

Resource Definition Patient

My Patient

20



21

“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”



22

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!


Using profiles

Formulate what exchanging partners must

adhere to

Server & client may publish their

conformance to profile

When communicating a resource, a resource

can indicate the profiles it conforms to.

Receiving side may verify conformance

23


Tagging a resource

• MRN 31415

• “Michel Rutten”

• 20-01-1973

• Sittard

• “I’m a Patient conforming to the Dutch Profile”See http://hl7.nl/Profiles/patient-nl

Patient

24

http://hl7.no/Profiles/patient-no


Profile –a “normal” resource

25 …computable!


REPRESENTATIONSIntroducing profiles


Formats

27

XML

Namespace: http://hl7.org/fhir

Also includes XHTML

JSON

No namespaces…

JSON XPath Navigator

http://hl7.org/fhir


Differential Structure

28

Describes only modified elements

Different from resource definition

Does not describe default elements

Identical to resource definition

Targeted at profile authors

Concise XML

Focus on customizations


Example: Lipid

29


Snapshot

30

Contains all resource elements

Modified elements

Default elements

Targeted at profile tooling

Easier to process programmatically


Example: Lipid

31


Expansion

32

FHIR API supports the expansion of

differential profiles

Tooling

Open: Expand differential profile

Save: Generate differential profile


SPREADSHEETProfile Authoring Tools


Profile spreadsheet

HL7 Wiki http://wiki.hl7.org/index.php?title=FHIR_Spreadsheet_Profile_Authoring

Tab page ↔ resource

Row ↔ resource element

Column ↔ element property

34


Example: Lipid

35


Profile spreadsheet

Supports differential structures

Only include rows for modified elements

Supports snapshots

May include default elements by copying rows

form resource definition sheet

36


FORGEProfile Authoring Tools


Forge

FHIR Profile Editor

http://fhir.furore.com/forge

Windows Desktop Application

Supports online & offline use

Load from / save to FHIR server

Load from / save to disk

38

http://fhir.furore.com/forge


Forge

Implementation based on FHIR API

Resource definitions

Deserialize XML to POCO

Serialize POCO to XML

Profile error validation

Supports differential and snapshot structures

Open differential/snapshot profile

Generates compressed XML39


Work In Progress

Current release supports most of DSTU 1

Some advanced features are not yet

supported, e.g.

Type slicing (value[x])

Search parameters

Some bugs...

40


Example: Lipid

41


STEP BY STEPAuthoring Profiles


Running Example

“Lipid Profile” example from spec

http://www.hl7.org/implement/standards/fhir/diagno

sticreport-profile-lipids.html

DiagnosticReport containing 4 results:

1x Cholesterol

1x Triglyceride

1x HDL Cholesterol

0/1x LDL Cholesterol

Package it up in a message44

http://www.hl7.org/implement/standards/fhir/diagnosticreport-profile-lipids.html


METADATAAuthoring Profiles


Identification

REST Id on server

http://spark.furore.com/fhir/profile/lipid.v1

Server assigned

Name

“Lipid Profile”

Human readable

Author assigned

46

http://spark.furore.com/fhir/profile/lipid


Identification

Identifier

Globally unique

Author assigned

UUID: 15046b9c-2da0-4b80-82ef-c6af6fcfd2bf

OID: 2.16.840.1.113883.10.20.2.1

URN

urn:openEHR.org:EHR-ACTION.medication.v1

http://hl7.org/fhir/Profiles/iso-21090-2011

47

http://hl7.org/fhir/Profiles/iso-21090-2011


Versioning

We used semantic versioning

Uses “<major>.<minor>.<patch>”

See semver.org

Major version number is increased on

breaking changes

Major version number is part of author-

assigned identifier AND REST url

Both versions may co-exist on server, they

have different URLs and names48


Versioning example

URL Id v

http://fhir.nl/Profile/patient.v1 urn:fhir.nl:profile:patient:v1 1.0.0 Original

version

http://fhir.nl/Profile/patient.v1 urn:fhir.nl:profile:patient:v1 1.0.1 Typo

Clarification

Correction

Bugfix

http://fhir.nl/Profile/patient.v1 urn:fhir.nl:profile:patient:v1 1.1.0 Non-breaking

change

Addition

http://fhir.nl/Profile/patient.v2 urn:fhir.nl:profile:patient:v2 2.0.0 Breaking

change

49

http://fhir.nl/Profile/patient.v1





Profile Metadata

Publisher

• Organization or individual responsible for publishing

• Should be populated

• e.g. “FHIR Project Team“

Telecom

• One or more contact points of the publisher

• Telephone, email, website etc.

Description

• Longer description of the contents of the profile

Code

• One or more coded descriptions to help with finding the profile

• e.g. LOINC 58239-5 (lipid)

Status

• Draft, Active, Retired

• Experimental Y/N

Requirements

• Scope & Usage

• The “need” or “why” of the profile

Date

• Of publication

• YYY-MM-DD

• e.g. “2013-07-07"

50


Example

51


STRUCTURESAuthoring Profiles


What’s in a profile?

53

Profile

Extensions

Constrained Resources

& Datatypes

Metadata


Structures

54

Profiles contain “Structures”

Set of constraints on (nested) elements of a

Resource or Datatype

“Subclass” of a Resource, with specific limits

on its elements

Cardinality

Value domains

Invariants


Example

55

“Cholesterol observation” is an Observation : That has a fixed LOINC code 35200-5 (Cholesterol) as its

name

Has a quantity as value that’s expressed in mmol/L (a

UCUM unit) (without a ‘comparator’) OR ELSE there’s a

comment

An interpretation limited to LL,L,N,H,HH

A “recommended” high reference range of 4.5 (no low)

mmol/L, independent of age (no age)

Is an independent observation (no related)


Cardinality

Number of elements in a set

0 - None

1 – Single element

N – N elements

* – Many elements

Multiplicity

Minimum cardinality

Maximum cardinality56


Cardinality

Minimum Maximum Description

0 0 Prohibited / removed element

0 1 Optional single element

0 * Zero or more elements

1 1 Required element

1 * One or more elements

2 3 Specific bounds

57


Constrain Cardinality

58

You can only further restrict the cardinality of

resource elements

Increase minimum cardinality

Decrease maximum cardinality

An element that is mandatory in the resource

definition cannot be constrained as optional


Limit value domains

59

Only allow “active” Patients

=“true”

If deceased is given, it must be

a dateTime, not a boolean

AddressNL

Use a profiled datatype (from

this or other profile)

Only allow reference to a

profiled resource

OrganizationNL


Contextualize Narrative

60

Override the base spec’s descriptions by

adding context specific narrative:

short : string 1..1

formal : string 1..1

comments : string 0..1

requirements : string 0..1

synonym : string 0..*

example[x] : 0..1 (example value!)

mappings : 0..* (more specific mappings)


Example: spreadsheet

61


Example: Forge

62


Demo: Forge

63

0..1

= ‘ok’

“if no value…”

1..1

1..1


Must support?

64

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


Reusable constraints

65

We have multiple components within the

“Lipid Profile” with Quantity

All with the same constraints

Units are mmol/L

in UCUM (http://unitsofmeasure.org)

no comparator

Let us first make a reusable “lipid quantity”

constraint on the Quantity datatype!


Demo: Lipid Quantity

66

Element Property Value

Quantity Short Quantity as used in lipid measurements

Quantity Formal Quantity as used in lipid measurements

Quantity Comments Lipid measurements are expressed in

mmol/L

Quantity.units Fixed value mmol/L

Quantity.system Fixed value http://unitsofmeasure.org/

Quantity.code Fixed value mmol/L

http://unitsofmeasure.org/


Demo: Lipid Quantity

67


BINDINGSAuthoring Profiles


Coded types

69

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


CodeSystem vs. ValueSet

70

“Code System”

“Dante’s deadly sins”

Pride

Envy

Wrath

Sloth

Avarice

Gluttony

Lust

“ValueSet”

Takes concepts from…

Defintion of

terms

Example: SNOMED-CT Example: “Childhood diseases”

An enumeration

of terms


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/ActClass71


ValueSet

Has metadata

much like Profile: identifier, version, name, etc

Is built by inclusion of terms from

CodeSystems

Can exclude specific codes from other

valuesets

Can import codes from other ValueSets

72


ValueSet

73

In/exclude concepts

Metadata


ValueSet

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 organized74


ValueSet

75


ValueSet: Gender

76


Bindings

When used in a Resource, the modelers

include Bindings

Bindings specify which codes can be used

77


Example: Forge

78


Conformance

79

isExtensible=N isExtensible=Y

Required SHALL Validation error

Non-conformant

Additional codes

allowed

Preferred SHOULD Validation error

Discouraged

Supplemental

codes likely

Alternatives

allowed

Example MAY Just a suggestion, no preference

If implementers of your profile provide a

different code than you have in your profile….


FORMAL CONSTRAINTSAuthoring Profiles


Formal constraints

Examples:

“If a Cholesterol value result is not available, use

the comments field”

“A patient’s birthdate must be on or before today’s

date”

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 a constraint

83

• 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: Forge

84


Example: Forge

85


Example: Forge

86


EXTENSIONSAuthoring Profiles


Extensions

Extension Definition

Global, shared

Extension Reference

Structure element

References an Extension Definition

88


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!)89


Extension Definition

90

Note: multiple

contexts!


Extending a name

91

Key = location of formal definition

Value = value according to definition


Calculated - Definition

92


Calculated - Use

93


SLICINGAuthoring Profiles


Slicing

Slicing Group

Discriminator

Cardinality

Slice

Cardinality within the group

Additional constraints


Example: Contact

Resource definition is very generic:

Telecom

Contact { phone, fax, email, url } (0-*)

Let’s constrain; require phone & email:

Telecom (2)

Phone (1)

Email (1)

Discriminator = system

96


Slice Cardinality

97

Slice Group Cardinality Slice Cardinality

Telecom 2…2 Phone 1…1

Email 1…1



Email 0…1

Must specify both Phone and Email

Must specify Phone and/or Email



Email 0…1

Optional Phone and/or Email


Example: Contact

98


Example: Lipid

99


Example: Lipid

100


FUTURE DEVELOPMENTForge


Profile Validation

User friendly validation error messages

Validation error message provided by API…

Highlight invalid controls

Red border

Click on message => focus associated control

Support for XPath validation rules…

Hard-coded subset?

102


Resource Validation

Validate a resource against the profile

Generate validation report

List discrepancies

103


Value Slicing

Slice value[x] element

Slice element for each included type

Automatically generate/synchronize slices

Cf. regular slice – all slices share a common

type

Example

Schedule OR Period

104


Modifier Extensions

Extension with isModifier = True

Slicing within ModifierExtensions collection

Instead of regular Extensions collection

Issue:

If a profile is updated by clearing the isModifier

property value, then all related profile definitions

become invalid…

105