Binding Syntax

Binding Syntax

This project is a joint effort between Implementation and Conformance 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)
• 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)
• sequence (optional)

The last four 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 =

"When not null, the content of this element SHALL" ( ValueSetAssertion | FixedCodeAssertion ) EOL

(* Depending on whether the Vocabulary Declaration is a value set assertion or 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+ EOL

(* Sorted by @bindingPriority *)

--Tklein 20:50, 24 September 2010 (UTC)I think it is unnecessary to explicitly state "respecting the identified date ranges": what would be the syntax and meaning of NOT respecting the effectiveDate and endDate in the VSA? What is the meaning of "SHALL comply with"? In the first binding syntax I think you are saying it the right way but are only halfway there: "the content of the element SHALL ". The old syntax was clear: "The content of the element SHALL be drawn from ". I know this is not technically correct; both the old binding directly to a single value set and the new binding to a list of Value Set Assertions, are the definition of a vocabulary constraint, not a picklist (which the other phraseology implies). I think we need to improve this.

--Lmckenzi 20:32, 27 September 2010 (UTC)The effective date and end date are actually characteristics of the bindings. What I was trying to get at is they have to comply with one of the VSAs in the list where the current date is between start and end. We can't us "shall be drawn from" because that only deals with maximum. Happy to see better wording though.

--Frankoemig 18-1-12: replaced "respecting the identified date ranges" by "valid as specified by the date range (effective date and end date interval) of the value set assertion" - hope this solves the concerns.

FixedCodeAssertion =

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

Code =

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

CodeSystem =

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

CodeSystemVersion =

"using the version of the code system as published on" @codeSystemVersion

ContextBinding =

EOL "On or following" @effectiveDate

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

"," ValueSetAssertion

ValueSetAssertion =

MaxValueSet [ MinValueSet ] [ IgnoreValueSet ] [ StaticDate ]

(* MinValueSet and IgnoreValueSet appear if the minimumValueSet or maximumValueSet, 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" | "MAY") "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 *)

--Tklein 22:45, 24 September 2010 (UTC)I think this is bad. Folks should NOT just create value sets 'on the fly'. I know this is how the tooling works, but that is a usability shorthand. Enshrining this handy user-interface gizmo used in the tool for human readable BNF grammar for Implementation Guides is, I strongly believe, a Very Bad Idea.

--Lmckenzi 20:32, 27 September 2010 (UTC)I've added the caveat restricting where it's used. I'd like the syntax to support what the MIF allows. If we allow it in models, no reason not to allow it in IGs.

ValueSetVersion =

@ValueSetVersionStatic | @ValueSetVersionDynamic

ValueSetVersionStatic =

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

ValueSetVersionDynamic =

 ????????????

--Tklein 22:45, 24 September 2010 (UTC)Another Bad Idea. What is the purpose of STABILITY in the VSA if you define the value set version (which is a timestamp) in the assertion as well? Or is this your syntax for STABILITY in the VSA? Since this is part of the ValueSet definition, used in MIN, MAX, and IGNORE value set references in the VSA, then you set up a potential conflict between the STATIC STABILITY timestamp and this timestamp.

--Lmckenzi 20:32, 27 September 2010 (UTC) When referencing a value set, you've always had the ability to refer to a specific version. STABILITY applies to everything that's not already declared. As mentioned in Core Principles, you can actually nail everything down without declaring stability, in which case the staticBindingDate doesn't accomplish anything.

--Frankoemig 1-18-12: does the split into static and dynamic parts address the comments?

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

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

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 --TedKlein 12:25, 18 July 2011 (UTC)Recommend that this be removed from the MIF, as this is precisely the type of information that we envisioned being captured in 'Terminology Guidance'. Note that we do not have a syntax for specifying Terminology Guidance, since it is not properly a component of Binding. This is probably an open issue.

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