Vocab QA Requirements

This is the working collaboration page for documenting the issues and requirements to be addressed by the Vocab QA project. This page will begin to put together the ideas from which the document will eventually be produced. Project Main Page

Scope Items

Project ID: 1196

Product Families

1. Version 2
2. Version 3
3. CDA
4. FHIR

Definitions Last updated on [enter date]

Id	Item	Context	Draft Definition	Noted Issues for draft definition	Known overlaps and conflicting definitions
I.	Overarching Terms - How are these concepts the same or different?	V3 Core Principles	(copy in the V3 definition)	(note where this def doesn't meet SKMT definition guidelines	(note known issues for this term)
I.1	Terminology	V3 Core Principles
I.2	Vocabulary	V3 Core Principles
I.3.	Code System	V3 Core Principles
I.4.	V2 Table	V3 Core Principles
I.5.	Ontology	V3 Core Principles
I.6.	Concept Domain	V3 Core Principles
II.	Specific Definitions - What are the definitions for these key terms?
II.1.	Concept	V3 Core Principles
II.2.	Code System	V3 Core Principles
II.3.	Value Set	V3 Core Principles
II.4.	Value Set Definition	V3 Core Principles
II.4.1	Extensional Value Set Definition	V3 Core Principles
II.4.2	Intensional Value Set Definition	V3 Core Principles
II.4.3	Value Set Expansion	V3 Core Principles
II.4.4	Grouping Value Set	V3 Core Principles
II.4.5	Value Set Scope (Purpose)	V3 Core Principles
II.4.6	"Locked" Value Set	V3 Core Principles
III.	Versioning - What is versioning and how does it apply in this context?
IV.	Use of Value Sets
IV.1.	Use of Null (information transport versus metadata bout the value exchanged)
IV.2.	Use of Negation (as defining types of concepts to be included)
IV.3.	Use of MIN, MAX, and IGNORE
V.	How to build a value set
V.1	What is Binding (Do we say "Value Set Binding"? "Vocabulary Binding?")
V.1.1	What is Binding Strength?
V.1.2	What is Binding Stability? (Static and Dynamic)
V.2	Selection of Code System(s)
V.3	Use of concept descriptions
V.4	What is VS Expansion information and what is in the definition ( See II.4.3)
V.5	Use of concepts not in the bound value set (open/closed, strength, extensability)

Terms to Clarify

Differences between these ideas.

1. Terminology
   1. [get definition from Core Principles]
2. Vocabulary
   1. [get definition from Core Principles]
3. Code System
   1. [get definition from Core Principles]
4. Concepts
   1. [get definition from Core Principles]
5. Value Set
   1. [get definition from VSD]

Value Set Definition

1. Intensional & Extensional
   1. Value Set Expansions
   2. Grouping value set
   3. VS Scope (Purpose) - critical elements
   4. "Locked"

V2 Table

1. Code usage (Required, Permitted, Excluded)

Terminology artifact versioning

[How is versioning applied for the main aspects]

Use of value sets

1. Use of Null (information transport versus metadata about the value exchanged)
2. Negation (as defining types of concepts to be included)
3. MIN, MAX, IGNORE

How to build a value set

1. Binding
   1. Binding Strength
   2. Binding Stability (Static and Dynamic)
2. Selection of code system
3. Use of concept descriptions
4. What is VS Expansion information and what is in the definition
5. Allowance for use of concepts not in the value set (Open/Closed, ~strength, extensability)

Vocabulary Objects

1. HL7 Defined Code Systems
2. HL7 Authored and Published Value Sets

Common Elements Across Families

1. Code system metadata
   1. Code system Identifiers
   2. HL7 code system component syntax
      1. Code case
      2. Use of special characters, etc
      3. Expectations on specification of a particular concept representation for use
2. Value Set metadata
   1. Value set identifiers
   2. Value set definition constructs
      1. QA considerations to be considered when changes are proposed
3. Binding information
   1. Common components and naming
   2. Min and Max
   3. Expectations on adherence to versions and behavior when expected version is not available
      1. Expectations to include
         1. Version update timeliness
         2. Impact on backwards compatibility and restrictions that must be considered when changes are proposed
4. Clarify how partially/unconstrained specifications are to be fully constrained
   1. If every HL7 specification provides through binding and guidance all information necessary to fully specify binding, then HL7 does not need to provide expansions because this should mean that any entity could follow the specification (knowing the allowed defaults and default behavior) to arrive at the correct deterministic expansion
   2. HL7 will define final defaults for all parameters so that if a specification does not address the approach for arriving at a deterministic specification, the HL7 default will govern.

What is needed for each of these

1. Similar sub-elements
2. Unified governance
3. Where there are differences
   1. Allow differences or require harmonization

Draft list of issues for discussion

1. Multi-code system value sets and their use in extensible bindings
2. Use of value sets to control better use of null flavor
3. Value set versioning
4. Use of static binding
5. Clarify use of immutable value set: ActClassProcedure – good example
6. Not just value set – all terminology issues
7. V2 table content issues
8. Incorrect OID identifier and name of object
9. Inconsistency in naming conventions
10. Terminology source of truth for artifacts
11. Terminology in the context of ballot review
12. If a code system is represented in an HL7 spec, the code system:
    1. Needs an identifier "known to HL7 users"
    2. Has a documented steward
13. Example of situation that should be avoided
    1. Abnormal / Interpretation flags in v2 lab / v3 lab
14. Explain the ROI for following these guidelines
    1. Enhanced ease of implementation
    2. Ease of ballot review and understanding
    3. Vocabulary Darwin award winners
15. Restructure the ballot documents so that the vocabulary content is easily reviewable and the context of use is easy to determine

List of principles

This is a working list to document general principles to be implemented with processes to achieve a higher level of quality in the HL7 Vocabulary management processes across the product families.

1. Assessment of fitness for purpose of new value sets

• Scope and Range of proposed Value Set

1. Assessment of both fitness for purpose and possible negative effects of proposed changes

Initial Ideas for Requirements

We really want to have all of these be SHALLs, but we recognize there may be issues around broad use.

1. Review process should be asynchronous
2. Review process should invite contributions from both members and non-members
3. Tooling should be used to ensure technical accuracy

• Proposed content ready for use at time of submission
• Proposed content should be free of spurious editorial error or structural mistakes (missing requirement elements, etc.)
• Proposed content should be in a formal artifact and well structured
• Proposed content should have a clear path to implementability

1. Tooling should be broadly available to enable creation and update of VSDs
2. Tooling should be broadly available to enable creation and update of HL7 code systems
3. Tooling must support the format for implementation use of the value sets and other vocabulary objects across all families

• Ideally the tooling should provide a single set of capabilities and UI, and the product family differences are 'under the covers' in the background

1. It would be nice if the tooling did the automatic items, such as and OID is created automatically when a FHIR value set is created
2. Asynchronous but consistent process - need off-line functionality
3. Should we continue to support inconsistent ballot processes timing and approach across families
   1. may need to consider what could change here

General Notions and Comments

• Some requirements are driven by the underlying code system requirements
• Some requirements are driven by the product family
• We should try to ensure that all value sets created are usable across product families
• The current notion is that a value set expansion contains a particular set of concepts from underlying terminologies, but different expansions made from the same VSD may have differences in additional baggage; but all must have the same set of concepts
• Our processes should ensure that whatever gets submitted is consistent with what our documented notions of what value sets actually are.
• Our processes should allow for the possibility that validation requirements for value sets may vary based on the product family or models they are being designed for use with.
• See if our tooling and practices can make effective use of social media so that the review process can scale by taking advantage of crowd-sourcing notions

Systematic Approach

1. Alternative approaches:
   1. Gather Input by meeting with key collaborator for each product family to find issues
      1. Decided against this. Decided to build stawman to discuss with product families first.
   2. Develop and initial strawman then review with product families
      1. Document process
         1. Incrementally add specificity over time
         2. Focus on critical areas and allow other items to not change initially
            1. Identify common elements across all families but are not approached in same way
      2. Incremental build of supporting tooling
         1. Can we have tooling that changes as requirements change
2. Consider using survey monkey to gather current processes