Binding Syntax

Binding Syntax

This project is a joint effort between CGIT and Vocabulary.

Scope

Define the human readable expression of the vocabulary constraints in implementation guides (Model Bindings) and by Realms as published sets of Context Bindings. Define the expression of the Value Set Assertion, a Model Binding, a Context Binding, and a Context Domain constraint. Information expressed in the syntax should be isomorphic to the normative definition of the data items comprising vocabulary constraints in Core Principles and the MIF ballots.

Requirements

• model binding to a single code or one or more Value Set Assertions
• context binding to one or more Value Set Assertions
• dynamic/static stability
• identification of MIN/MAX/IGNORE value sets in each Value Set Assertion
• identification of Coding Strength for each Value Set in each Value Set Assertion
• constraint of a Concept Domain to a sub-Domain
• publication of value set expansions (appendix)

A Model Binding is the direct association of a coded attribute or data type property to one or more specific Value Set Assertions or specific single fixed code from a coding system. It thus has the components:

• Value Set Assertion or Single Code (required)
• Intensity (optional)
• sequence (optional)

These requirements have been updated to match the latest version of the Core Principles and Properties of HL7 Version 3 Models document.

A Context Binding is the association between a Concept Domain, a Binding Realm, and one or more Value Set Assertions, along with effective timestamps and a sequence (if more than one Value Set Assertion is defined). The specific items that are included in a Context Binding are:

• Context Domain or sub-Domain (required)
• Binding Realm (required)
• Value Set Assertion (required)
• effective date (required)
• end date (optional)
• Intensity (optional)
• sequence (optional)

The last five items may be repeated as a group.

A Value Set Assertion is the mechanism to express the coded vocabulary constraint in a binding. A Value Set Assertion has at least one required value set declared - the MAX; this is mandatory. A Value Set Assertion has two optional Value Sets that may be declared, the MIN and IGNORED. For more information about the MAX, MIN, and IGNORED value sets in a Value Set Assertion, and how mathematical set operations may be used to understand how these provide a localizable, extensible, yet controllable constraint, see the discussion in Core Principles of V3 Models, chapter 5. The value set must be declared using a unique identifier, preferably the OID of the value set. Each value set identified in a Value Set Assertion must have an associated Coding Strength declared. The entire Value Set Assertion has an optional Stability level declared; if not declared, the stability is Dynamic. If declared, the stability is Static, and the effective timestamp is that which is declared in the Value Set Assertion stability.

A Value Set Assertion is expressed using the following ten (10) elements:

• MAX Value Set OID and/or name (mandatory)
• MAX Value Set version date/time (optional)
• MAX Value Set Coding Strength (CNE or CWE – mandatory)
• MIN Value Set OID and/or name (optional)
• MIN Value Set version date/time (optional)
• MIN Value Set Coding Strength (CNE or CWE – conditional)
• IGNORED Value Set OID and/or name (optional)
• IGNORED Value Set version date/time (optional)
• IGNORED Value Set Coding Strength (CNE or CWE – conditional)
• STABILITY StaticDate (optional)

Note that Model Binding is generally specified in Implementation Guides, whereas Context Binding is generally published separately by a Realm (since a Context Binding is valid across all models in the Realm that make use of the bound Context Domain). However, context binding to the Example Realm is common in Implementation Guides. Note also that Model Binding cannot be used for advisory bindings; Context Binding to Example Realm should be used for those, or information should be placed into the 'Terminology Guidance' section of the Vocabulary Declaration of a coded model element for such advisory information.

Keywords

The keywords SHALL, SHOULD, MAY, NEED NOT, SHOULD NOT, and SHALL NOT in this document are to be interpreted as described in the HL7 Version 3 Publishing Facilitator's Guide. The keyword "SHALL" implies a lower cardinality of 1 but does not disallow NULL values. If NULL values are to be excluded, it will be via an additional explicit conformance statement.

EBNF grammar

ModelBindingSyntax =

ValueSetAssertaion: "When not null, the content of this element " BindingIntensity ( ValueSetAssertion) ( ("effective" @effectiveDate ) | ( "effective" @effectiveDate " through " @endDate) ) sequenced @bindingPriority "." EOL

FixedCodeAssertion:

"When not null, the content of this element " BindingIntensity (FixedCodeAssertion ) ( ("effective" @effectiveDate ) | ( "effective" @effectiveDate " through " @endDate) ) "." EOL

(* Since the Vocabulary Declaration is a a fixed code, Concept domain vocabulary declarations are not covered here. *)

ContextBindingSyntax =

"When not null, content for all coded model elements and datatype properties with a Vocabulary Declaration of Concept Domain " @conceptDomain

"with a binding realm context of" @bindingRealmName

"SHALL comply with one of the following Value Set Assertions, valid as specified by the date range (effective date and end date interval) of the value set assertion and listed in order of preference:"

@ContextBinding+ sequenced @bindingPriority"." EOL

(* Sorted by @bindingPriority *)

bindingPriority

@bindingPriority [1-9][0-9]*

FixedCodeAssertion =

"be fixed to the code" Code CodeSystem "."

Code =

@code [ "(" @codePrintName ")" ]

CodeSystem =

"from the code system having the OID" @codeSystem [ "(" @codeSystemName ")" ]

CodePrintName =

@codePrintName["string"]

ContextBinding =

EOL "On or following" @effectiveDate

[ "but prior to" @expiryDate ] (* If @expiryDate is present *)

"," ValueSetAssertion

BindingIntensity =

" MAY " | " SHOULD " | " SHALL "

(* Use of 'SHALL' means that failure to observe the constraints expressed in the Value Set Assertion(s) will be judged non-conformant *)

(* Use of 'SHOULD' means that applications are expected to obey the constraints expressed in the Value Set Assertion(s), but failure to do so will not be judged non-conformant *)

(* Use of 'MAY' means that the constraints expressed in the Value Set Assertion(s) should be considered a helpful suggestion but no conformance expectations are being asserted. *)

ValueSetAssertion =

MaxValueSet [ MinValueSet ] [ IgnoreValueSet ] [ StaticDate ]

(* MinValueSet and IgnoreValueSet appear if the minimumValueSet or ignoreValueSet, respectively, are defined in the value set assertion *)

MaxValueSet =

"be drawn from " ValueSet

( "if an appropriate code exists within that expansion, otherwise a local code or original text SHALL be used." | "." )

(* ValueSet is taken from element maximumValueSet. First option is used if @codingStrength is CNE, second iS CWE *)

MinValueSet =

"In addition, all applications SHALL at a minimum support" ValueSet "."

[ " As well, SHALL must support all local codes and originalText." ]

(* ValueSet is taken from element minimumValueSet. Last clause used if @codingStrength is CWE *)

IgnoreValueSet =

"When receiving, all applications SHALL ignore - not process or raise an error when receiving - " ValueSet

( "as well as all local codes and original text." | "." )

(* ValueSet is taken from element ignoredValueSet. First option is used if @codingStrength is CWE, second if CNE *)

StaticDate =

"All of the above expansions SHALL be resolved based on the ",

( "date " @staticBindingDate "." | "date of processing." )

(* First option is used if @staticBindingDate is present, otherwise use second option *)

ValueSet =

"the set of codes in the expansion of Value Set"

[ ValueSetName ] [ ValueSetId ] [ ValueSetDef ] [ <ValueSetVersion> ]

(* At least one of ValueSetName, ValueSetId and ValueSetDef must be present *)

ValueSetName =

" " @name

ValueSetId =

"with the identifier" @id

ValueSetDef =

"containing all codes descended from root code" @rootCode

( " including" | " excluding" ) "that root code"

(* Use the first option when @includeRoot is true, second option otherwise *)

(* NOTE: This style is restricted to use only when dealing with the ActClass, EntityClass, RoleClass, ActMood, EntityDeterminer, ActRelationshipType, ParticipationType and RoleLink classCodes. For these the code system is fixed and can be inferred. There is no ability to constrain the code system version. *)

ValueSetVersion =

@ValueSetVersionStatic | @ValueSetVersionDynamic

ValueSetVersionStatic =

" using the version defined on " @staticDate [ "at " @staticTime ]

ValueSetVersionDynamic =

"the most recent version of the value set available at the time of processing"

Note: EOL Represents an end of line as appropriate to the rendering technology (so <br>, CR, CR/LF, etc.)

Note: all dates should be formatted as "yyyy-mm-dd". Note: value set ID should be formatted in Object Identifier (OID).

Issue

The MIF representation of value set binding has (and has had for a while) the idea of "revision frequency" as a characteristic of the binding assertion. It appears at the same level as the static binding date. The definition is as follows:

revisionFrequency "Indicates how often applications are expected to update their codes to reflect changes to the value-set associated with the attribute"

Allowed values are:

Edition: The value set associated with the domain is 'frozen' at the set of codes available at the time the Edition referenced by the interaction was published. I.e. The codes which were published by HL7 as part of the edition for 'internal' code systems and the codes which were available in external code systems at the time the edition was published

CodeSystem: The value set bound to concept domain changes with the underlying code system. Applications are expected to support codes from the current version of the code system, regardless of declared edition.

Background

This element has been available for model bindings since MIF 2.0.0 in May, 2006. It was added with the intention of being used by implementation guides and conformance profiles. It has never been used in HL7 International models because the tools don't support capturing it. To the best of my knowledge, it has not been used in implementation guides or profiles to date yet either. The objective is, for value set assertions that are not staticly bound (i.e. that do not have a static binding date), to indicate how often implementers are supposed to keep up with changes to the value set expansion. One possibility is they only compute a new expansion for each "release" of the underlying specification and they use the expansion for the release communicated in the version attribute of the instance. For example, if they receive an instance declaring that a version of "NE2007", then they use the value set expansion for that release date. They don't have to track intervening changes in the code systems. The other possibility is they need to keep current as the code systems change. Whenever anything the value set depends on gets updated, implementers are expected to compute a new expansion and validate based on that "current" expansion.

Decision Alternatives

The Vocabulary Work Group needs to do one of three things: - Request that this concept be deprecated or removed from the MIF - Add the concept into Core Principles and into this binding syntax specification - Request modifications to this concept as represented in the MIF and then incorporate the revised content into Core Principles and into this binding syntax specification

Discussion

The challenge with expectations for "keeping up to date" with a vocabulary are not just dependent on the bound vocabulary, but also on what the application is doing. For example, the vocabulary for drug codes might change bi-weekly. For a prescribing or dispensing application, a revision frequency of bi-weekly might also be an expectation. However, for a research application doing retrospective analysis, a frequency of yearly might be perfectly fine.

Recommendation

Capture guidance around revision frequency in the "Vocabulary Guidance" annotation, but not as part of the binding syntax. This attribute should be deprecated from the MIF.

Examples

NOTE: these examples have not yet been updated to reflect the newly proposed EBNF syntax

Model Binding:

Single Code Binding:

Value Set Assertion Binding:

--Tklein 02:22, 14 September 2010 (UTC)I'm thinking a model binding to a set of codes will look more like this:

A code element SHALL be present where the value of @code is asserted by MAX Value Set 2.16.840.1.113883.19.3 LoincDocumentTypeCode 20100422 CWE, MIN Value Set 2.16.840.1.113883.19.6 MinimumDocumentTypeCode CNE with stability 20101015

The following are older examples that use the former syntax which fails to support the current binding characteristics:

CONF-ex1: A code element SHALL be present where the value of @code is selected from Value Set 2.16.840.1.113883.19.3 LoincDocumentTypeCode DYNAMIC.

CONF-ex2: A code element SHALL be present where the value of @code is 34133-9 Summarization of episode note 2.16.840.1.113883.6.1 LOINC STATIC.

A restatement of these under the proposed syntax might look like:

1. When not NULL, the content of this element be drawn from the set of codes in the expansion of Value Set "LoincDocumentTypeCode" with the identifier 2.16.840.1.113883.19.3 if an appropriate code exists within that expansion, otherwise a local code or original text MAY be used.

2. {A coded element} SHALL be present where the value of @code be fixed to the code 34133-9 "Summarization of episode note" from the code system having the OID 2.16.840.1.113883.6.1 "LOINC" using the version of the code system as published on 20110415.

--TedKlein 14:53, 28 July 2011 (UTC)We need some further examples showing the full Value Set Assertion with all three components. Something like:

When not NULL, the content of this element shall be drawn from the set of codes in the expansion of Value Set "AcknowledgementDetailType" with the identifier 2.16.840.1.113883.1.11.19358 if an appropriate code exists within that expansion, otherwise a local code or original text MAY be used. All of the above expansions SHALL be resolved based on the date 20110311 effective 20110601

--Tklein 02:22, 14 September 2010 (UTC)And a context binding something like this:

Context Binding:

When not null, content for all coded model elements and datatype properties with a Vocabulary Declaration of Concept Domain "ActDetectedIssueType" with a binding realm context of "R1" SHALL comply with one of the following Value Set Assertions, respecting the identified date ranges and listed in order of preference: On or following 20100701 but prior to 20110615 be drawn from the set of codes in the expansion of Value Set "ActDetectedIssueCode" with the identifier 2.16.840.1.113883.1.11.19572 if an appropriate code exists within that expansion, otherwise a local code or original text MAY be used. On or following 20110616 be drawn from the set of codes in the expansion of Value Set "ActIssueCode" with the identifier 2.16.840.1.113883.1.11.20357 if an appropriate code exists within that expansion, otherwise a local code or original text MAY be used. All of the above expansions SHALL be resolved based on the date of processing.

Context Domain Constraining to a Context sub-Domain: to be defined

Context binding to a single code: to be defined

Context binding to a list of value set assertions with overlapping dates: to be defined

--TedKlein 14:53, 28 July 2011 (UTC)Is the sequence in the bindings implied by the sequence of prose sentences in the syntax?

Translations

The grammar listed above is using the English language for convenience. However, it can be assumed that localized implementation guides will be created not written English. Therefore, a translation is necessary. This could be done best by defining a country specific the grammar. The grammars defined so far are listed below.

German

HL7 Germany provides a detailed description in German as well, which can be found at [1].

DesignTimeDynamicBindingSyntax =

„Der Wert für“ CodedElement („MUSS“ | „SOLL“) „DYNAMISCH aus dem ValueSet“ (ValueSetOID | ValueSetName) „ausgewählt werden.“

„Der Wert für“ CodedElement („MUSS“ | „SOLL“) „DYNAMISCH aus dem ValueSet“ (ValueSetOID | ValueSetName) [„ODER“ (ValueSetOID | ValueSetName)] „ausgewählt werden.“ EOL

DesignTimeStaticBindingSyntax =

„Der Wert für“ CodedElement („MUSS“ | „SOLL“) „STATISCH aus dem ValueSet“ (valueSetOID | valueSetName) ValueSetEffectiveDate „ausgewählt werden.“

„Der Wert für“ CodedElement („MUSS“ | „SOLL“) „STATISCH aus dem ValueSet“ (ValueSetOID | ValueSetName) ValueSetEffectiveDate [„ODER“ (valueSetOID | ValueSetName)] ValueSetEffectiveDate „ausgewählt werden.“ EOL

Reduction to a single code:

DesignTimeStaticBindingSingleCodeSyntax =

„Der Wert für“ codedElement („MUSS“ | „SOLL“) „STATISCH auf“ Code [DisplayName] CodeSystemOID [CodeSystemName] (EffectiveDate] „festgelegt werden.“ EOL

RuntimeDynamicBindingSyntax =

„Die VocabularyDomain für“ CodedElement „MUSS“ DomainName „sein. Das ValueSet für“ DomainName „in“ RealmName („MUSS“ | „SOLL“) „DYNAMISCH auf“ (ValueSetOID | ValueSetName) „festgelegt werden.“

„Die VocabularyDomain für“ CodedElement „MUSS“ DomainName „sein. Das ValueSet für“ DomainName „in“ RealmName („MUSS“ | „SOLL“) „DYNAMISCH auf“ (ValueSetOID | ValueSetName) [„ODER“ (ValueSetOID | ValueSetName)] „festgelegt werden.“

RuntimeStaticBindingSyntax =

„Die VocabularyDomain für“ CodedElement „MUSS“ DomainName „sein. Das ValueSet für“ DomainName „in" RealmName („MUSS“ | „SOLL“) „STATISCH auf“ (ValueSetOID | ValueSetName) ValueSetEffectiveDate „festgelegt werden.

Die VocabularyDomain für“ CodedElement „MUSS“ DomainName „sein. Das ValueSet für“ DomainName „in“ RealmName („MUSS“ | „SOLL“) „DYNAMISCH auf“ (ValueSetOID | ValueSetName) ValueSetEffectiveDate [„ODER“ (ValueSetOID | ValueSetName)] ValueSetEffectiveDate „festgelegt werden.“

French

Not provided yet.

Spanish

Not provided yet.

Portuguese

Not provided yet.

Japanese

Not provided yet.

Open Issues

• conditions (true/false)
• combined constraints: to be concatenated via "and" (must be reflected in BNF grammar)
• current grammar is not the current state of binding in HL7 v3 models; current state uses Value Set Assertion for binding
• Value Set Assertions are defined in the Implementation Guides
• Value Sets may be identified by OID or name
• Must be a way to assert ad hoc constraints to implement OCL-like restrictions on the bindings
• finalize translations