Vocab QA Requirements

From HL7Wiki
Jump to navigation Jump to search

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
Three current areas of focus, each with a separate sub-group working on this activity

  1. Vocabulary glossary across HL7
    1. Lead - Heather, Lisa
  2. General vocabulary issues - Vocabulary facilitators
    1. Lead - Rob McClure and Susan Barber
    2. This includes Binding
  3. Governance of creating, maintaining, delivering terminology content from HL7 specs
    1. Lead - Ted K. and Lloyd M.
    2. This includes Harmonization
  4. Publication of terminology
    1. Lead - Susan M, Richard E.

Product Families

  1. Version 2 - Rob Snelick
  2. Version 3 - Ted Klein
  3. CDA - Lisa Nelson, Rob H.
  4. FHIR - Lloyd M., Rob H.
  5. CIMI - Susan M., Richard E.

Definitions and Critical Concepts

Definitions Last updated on [enter date]

Id Item Context Draft Definition Noted Issues for draft definition Usage notes


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 From the SKMT Structured, human and machine-readable representation of concepts.
I.2 Vocabulary SKMT from Merriam-Webster's Dictionary (ISO adopted) Sum or stock of words employed by a language, group, individual work or in a field of knowledge
I.3. Code System TQA WG a managed collection of concepts represented by at least one internally unique code that may include a language-dependent description. Based on, but changed substantially from V3 Core Principles If more than one unique code is used then the code system is said to have multiple concept representations.
I.4. V2 Table HL7 Version 2 Health Exchange Standard
I.5. Ontology Oxford English Dictionary A set of concepts and categories in a subject area or domain that shows their properties and the relations between them. HL7 Core Principles does not give a specific definition for Ontology.
I.6. Concept Domain TQA WG A named category intended to represent the scope of ideas that will eventually be represented by a set of specific encodings. Based on the information in HL7 V3 Core Principles.
II. Specific Definitions - What are the definitions for these key terms?
II.1. Concept TQA WG a unitary mental representation of a real or abstract thing – an atomic unit of thought. It should be unique in a given Code System. A concept may have a language-dependant description and may also have description synonyms. A concept may represent a single atom in a code system, or may be constructed of multiple concepts (i.e. post-coordinated concepts). minor change to V3 Core Principles definition
II.2. Code System TQA WG a managed collection of concepts represented by at least one internally unique code that may include a language-dependant description. Based on, but changed substantially from V3 Core Principles If more than one unique code is used then the code system is said to have multiple concept representations.
II.3. Value Set Rob McClure A subset of concepts drawn from one or more code systems, where the concepts included in the subset share a common scope of use
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. Application of Value Set concepts
IV.1 Use of Value Sets - What is the purpose of making a value set binding in a model?
IV.2. Use of Null (information transport versus metadata bout the value exchanged)
IV.3. Use of Negation (as defining types of concepts to be included)
IV.4. Use of MIN, MAX, and IGNORE
V. Mechanics of using Value Sets
V.1. How to build a value set
V.2. What is Binding (Do we say "Value Set Binding"? "Vocabulary Binding?" What is the syntax for expressing the binding?)
V.2.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 and Create/Identify Our Working Definition

Similarities and 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]
  6. Value Set Definition
  7. Value Set Expansion
  8. Relationship
  9. Hierarchy
  10. Display Name
  11. Controlled Vocabulary
  12. Binding
  13. Model Binding
  14. Context Binding
  15. Concept Domain
  16. Coded Element
  17. Metadata
  18. Version and Versioning
  19. Conformance
  20. Normative


Value Set Definition

TQA should utilize Value Set Set Def Project

  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 - Binding

TQA should utilize HL7 Binding Semantics Project

  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

Projects External to TQA that should feed the final Process document

  1. VSD
  2. Vocabulary Binding semantics
  3. Harmonization submission materials and Processes
  4. Terminfo?

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

Initial ideas on TQA Process actions

Based on 2016-01-11 discussion at Orlando Monday Q2 meeting
Focus on:

  1. Provide WG with actionable Guidance
  2. Provide Governance for the process overall
  3. Determine a Management process for this


Actionable tasks leads to the following as initial test processes to understand what exists and how to impact:

  1. Review Harmonization and new Tables Project forms with the intent to create "a form" that will be applied to CDA-based guides and also FHIR resources and Profiles
    1. Expect that this will result in a cataloging of terminology use but but not change the use as proposed.
      1. Direct terminology information gathered in this way to HTA if it uses external terminology
    2. Identify "pure" HL7 code system and value set elements
  2. For the identified "pure" HL7 content - begin constructing comprehensive guidance and directly address overall harmonization for this.

Considerations for Model Element Naming Based on Terminology Issues

Some possible Rules:

  1. Where possible use a more specific term and avoid generic categorization terms for property names; i.e., Plan.planPurpose rather than Plan.category.
  2. Where the property is really a semantic definition of the class instance itself, in order to avoid constructions like Goal.goal, use Kind, i.e., a specific kind, e.g. Goal.kind = HbA1c, or Concern.kind =Type 1 Diabetes.
  3. Where we have other groupings,
    1. A general broad grouping is Category. Concern.category might be Diagnosis, e.g., or Complaint. (If the choices were admitting, working, rule-out, etc. see rule #1.)
    2. Classification, as you say, has a specific statistical meaning, and we shouldn’t use it unless we anticipate something like an ICD code.
  4. Type is overdetermined in the modeling space; don’t use (unless we identify another requirement)
  5. Code is a design term, not a requirements term; don’t use.