This wiki has undergone a migration to Confluence found Here

Difference between revisions of "Vocabulary Model Artifact Definition"

From HL7Wiki
Jump to navigation Jump to search
 
(5 intermediate revisions by the same user not shown)
Line 16: Line 16:
  
 
== Audience ==
 
== Audience ==
 +
Health Care Information Technology (IT) Audiences:
 +
*System designers and architects
 +
*Programmers/implementers
  
A vocabulary model will be needed for any SAIF project that is defining or publishing an information model.  Thus it is applicable to all audiences.  
+
A vocabulary model will be needed for any SAIF project that is defining or publishing an information model.  Thus it is applicable to all technology implementation audiences.
  
 
== Applicability ==
 
== Applicability ==
 
A Vocabulary Model is needed to support and document the terminology constraints of any information model and/or data types model. Therefore a Vocabulary Model must exist for any project at any level (Row) of the SAIF.  
 
A Vocabulary Model is needed to support and document the terminology constraints of any information model and/or data types model. Therefore a Vocabulary Model must exist for any project at any level (Row) of the SAIF.  
  
<i>Rationale</i>: The source for the terminology constraints for and information model is one or more "Vocabulary Model(s)" that the information model "includes."
+
:<i>Rationale</i>: The source for the terminology constraints for and information model is one or more "Vocabulary Model(s)" that the information model "includes."
  
 
There will be one Vocabulary Model at the "universal" level, and may be one Vocabulary Model defined for each affiliate realm.
 
There will be one Vocabulary Model at the "universal" level, and may be one Vocabulary Model defined for each affiliate realm.
  
<i>Rationale</i>: The "universal" model expresses the code systems, concept domains and value sets defined for universal use, including those value sets that must be used in all realms owing to there being a "universal" binding.  Similarly, the realm-specific Vocabulary Model expresses the further code systems, etc. defined for realm-specific use.
+
:<i>Rationale</i>: The "universal" model expresses the code systems, concept domains and value sets defined for universal use, including those value sets that must be used in all realms owing to there being a "universal" binding.  Similarly, the realm-specific Vocabulary Model expresses the further code systems, etc. defined for realm-specific use.
  
== Requirements ==
+
== Requirements, Relationships and Content ==
# An expression of the purpose that determines the contents that make up this particular Vocabulary Model.  
+
<!-- What are the needs that this particular artifact was created to satisfy and why are those needs important.  (Should not be more than 10-15.) -->
 +
#The Vocabulary Model is intended to assist in packaging and managing the myriad component artifacts needed to satisfy the constraints on encoded elements in a particular set of information models and/or data types models.
 +
##<i>Rationale</i> Encoded information model and data types model elements have a mandatory binding to one or more terminology artifacts that are contained in a vocabulary model.  In turn those information models and data types models have a required relationship to the Vocabulary Model that contains the needed artifacts.
 +
#A statement of the purpose that determines the contents that make up this particular Vocabulary Model.  
 
## <i>Rationale</i> A vocabulary model may include a single sub-artifact, such as a Concept domain, or it may include all of the sub-artifacts that HL7 manages.  The selection criteria or requirements must be expressed in text.
 
## <i>Rationale</i> A vocabulary model may include a single sub-artifact, such as a Concept domain, or it may include all of the sub-artifacts that HL7 manages.  The selection criteria or requirements must be expressed in text.
# Contain one or more sub-artifacts from the following artifact definitions:
 
#:*[[Concept Domain Artifact Definition| Concept Domains]]
 
#:*[[Code System Artifact Definition| Code Systems]]
 
#:*[[Value Set Artifact Definition| Value Sets]]
 
#:*[[Context Binding Artifact Definition| Context Bindings]]
 
#:*[[Code System Supplement Artifact Definition|Code System Supplements]] and
 
#:*[[Code Translations Artifact Definition|Code Translations]]
 
## <i>Rationale</i> A Vocabulary Model supports the individual terminology constraints of the attributes of a particular information model, and of the data types model that is included in that model.  Therefore, it must have one or more of the above sub-artifacts to support ir define those constraints.
 
  
== Relationships and traceability ==
+
=== Relationships and traceability ===
 +
<!-- What are the other artifacts to which this artifact must or may be required to relate?  (Express those relationships that are "many-to-one" - that is where many of this artifact type will usually relate to one of the other artifact type.) How do they relate?  Why is the relationship important?
  
* One or more Vocabulary Models are '''imported''' as part of the definition of each information model and each data types model in the SAIF.
+
Follow with a bullet list of artifacts that may or must relate to this artifact, where many of the listed artifact type will relate to one of this artifact type.
** <i>Rationale</i>: A Vocabulary Model supports the individual terminology constraints of the attributes of a particular information model, and supports the terminology constraints of the data type components in a data types model.
+
-->
 
* A vocabulary model may '''replace''' or be '''replacedBy''' one or more other vocabulary models
 
* A vocabulary model may '''replace''' or be '''replacedBy''' one or more other vocabulary models
 
** <i>Rationale</i>: In serial publication of vocabulary models this provides the traceability between sets of vocabulary models wherein one may supercede another.
 
** <i>Rationale</i>: In serial publication of vocabulary models this provides the traceability between sets of vocabulary models wherein one may supercede another.
Line 49: Line 48:
 
** <i>Rationale</i>: Provides a means for combining (including) content from multiple vocabulary models into a single grouping.  
 
** <i>Rationale</i>: Provides a means for combining (including) content from multiple vocabulary models into a single grouping.  
 
* A vocabulary model may '''contain''' one or more of each of the following artifacts:
 
* A vocabulary model may '''contain''' one or more of each of the following artifacts:
#:*[[Concept Domain Artifact Definition| Concept Domains]]
+
*:*[[Concept Domain Artifact Definition| Concept Domains]]
#:*[[Code System Artifact Definition| Code Systems]]
+
*:*[[Code System Artifact Definition| Code Systems]]
#:*[[Value Set Artifact Definition| Value Sets]]
+
*:*[[Value Set Artifact Definition| Value Sets]]
#:*[[Context Binding Artifact Definition| Context Bindings]]
+
*:*[[Context Binding Artifact Definition| Context Bindings]]
#:*[[Code System Supplement Artifact Definition|Code System Supplements]] and  
+
*:*[[Code System Supplement Artifact Definition|Code System Supplements]] and  
#:*[[Code Translations Artifact Definition|Code Translations]]
+
*:*[[Code Translations Artifact Definition|Code Translations]]
** <i>Rationale</i>: Satisfy requirements
+
*: <i>Rationale</i>: Satisfy requirements
 +
 
 +
<b>Artifact types that may or must relate to this artifact types</b> - Vocabulary Models are '''imported''' as part of the definition of each information model and each data types model in the SAIF therefore the following artifacts MUST relate to a Vocabulary model:
 +
* [[Conceptual Information Model Artifact Definition|Conceptual Information Model ]]
 +
* [[Conceptual Data Types Model Artifact Definition|Conceptual Data Types Model]]
 +
* [[Abstract Data Types Artifact Definition|Abstract Data Types]]
 +
* [[Reference Information Model Artifact Definition|Reference Information Model]]
 +
* [[Domain Information Model Artifact Definition|Domain Information Model]]
 +
* [[Serializable Information Model Artifact Definition|Serializable Information Model]]
 +
* [[Loose Information Model Artifact Definition|Loose Information Model]]
 +
* [[Simplified Information Model Artifact Definition|Simplified Information Model]]
 +
* [[Data Types Implementation Technology Specification Artifact Definition|Data Types Implementation Technology Specification]]
 +
* Semantic Profile
 +
*:
 +
*:<i>Rationale</i>: A Vocabulary Model supports the individual terminology constraints of the attributes of a particular information model, and supports the terminology constraints of the data type components in a data types model.
 +
 
 +
=== Content ===
 +
<!-- What elements or components are required to be part of this artifact, and what is their hierarchical structure?  How?  Why is the content important? (These can be expresses as a hierarchical set of content element names, with a brief phrase to describe each.) -->
 +
Each of the following is a SAIF Artifact in its own right, but is packaged as a sub-artifact of a Vocabulary Model
 +
*[[Concept Domain Artifact Definition| Concept Domains]]
 +
*[[Code System Artifact Definition| Code Systems]]
 +
*[[Value Set Artifact Definition| Value Sets]]
 +
*[[Context Binding Artifact Definition| Context Bindings]]
 +
*[[Code System Supplement Artifact Definition|Code System Supplements]] and
 +
*[[Code Translations Artifact Definition|Code Translations]]
 +
 
 +
:<i>Rationale</i> A Vocabulary Model supports the individual terminology constraints of the attributes of a particular information model, and of the data types model that is included in that model.  Therefore, it must have one or more of the above sub-artifacts to support or define those constraints.
  
 
== Artifact Technology ==
 
== Artifact Technology ==
Line 61: Line 86:
 
Technology as of January, 2011
 
Technology as of January, 2011
 
*'''Individual contents of a Vocabulary Model''' (code systems, value sets, etc.) are:
 
*'''Individual contents of a Vocabulary Model''' (code systems, value sets, etc.) are:
**Maintained in tables of an Access Data Base in a "repository"
+
**Maintained in tables of an Access Data Base in a "[http://gforge.hl7.org/gf/project/design-repos/ design repository]"
 
**:
 
**:
 
**Updated by Java-based software driven from XML source files in the HL7-defined [[Vocabulary_Maintenance_Language | Vocabulary Maintenance Language]] (VML)
 
**Updated by Java-based software driven from XML source files in the HL7-defined [[Vocabulary_Maintenance_Language | Vocabulary Maintenance Language]] (VML)
Line 75: Line 100:
 
**'''Primary distribution:''' is via MIF files. (XML files in MIF format.)
 
**'''Primary distribution:''' is via MIF files. (XML files in MIF format.)
 
**:
 
**:
**Secondary distribution: is via the Access "repository"
+
**Secondary distribution: is via the Access "design repository"
 
=== Rationale ===
 
=== Rationale ===
  
Line 86: Line 111:
  
 
== Content Constraints ==
 
== Content Constraints ==
# All Vocabulary content that is maintained and Published for the '''universal realm''' SHALL be adopted through the HL7 [[Vocabulary and RIM Harmonization Process]].
+
There are no content constraints included here.  The "core" definitions and constraints are documented as part of the artifact definitions for:
## <i>Rationale</i>: Established governance
+
*[[Concept Domain Artifact Definition| Concept Domains]]
#There are no further content constraints included here.  The "core" definitions are documented as part of the artifact definitions for:
+
*:
#*[[Concept Domain Artifact Definition| Concept Domains]]
+
*[[Code System Artifact Definition| Code Systems]]
#:
+
*:
#*[[Code System Artifact Definition| Code Systems]]
+
*[[Value Set Artifact Definition| Value Sets]]
#:
+
*:
#:*[[Value Set Artifact Definition| Value Sets]]
+
*[[Context Binding Artifact Definition| Context Bindings]]
#:
+
*:
#*[[Context Binding Artifact Definition| Context Bindings]]
+
*[[Code System Supplement Artifact Definition|Code System Supplements]] and  
#:
+
*:
#*[[Code System Supplement Artifact Definition|Code System Supplements]] and  
+
*[[Code Translations Artifact Definition|Code Translations]]
#:
 
#*[[Code Translations Artifact Definition|Code Translations]]
 
  
 
== Content Guidelines ==
 
== Content Guidelines ==
 
+
# The primary rules for change proposal submission include many guidelines or style guides. They are documented in:
# Primary rules for submission are documented in:
 
 
#*Instructions in the [http://www.hl7.org/documentcenter/public/harmonization/HL7HarmonizationProposal.zip Harmonization Proposal Submission Template]
 
#*Instructions in the [http://www.hl7.org/documentcenter/public/harmonization/HL7HarmonizationProposal.zip Harmonization Proposal Submission Template]
#*:
+
# Guidelines for some Vocabulary artifacts can also be found in the [[:Category:StyleGuides| Wiki Style Guides Category]]
#*Rules and principles of the HL7 [[Vocabulary and RIM Harmonization Process]]
 
# Guidelines for some Vocabulary artifacts are in the [[:Category:StyleGuides| Wiki Style Guides Category]]
 
  
 
== Publishing Representation(s) ==
 
== Publishing Representation(s) ==
Line 127: Line 147:
  
 
At present we have a very rich set of relationships that can be expressed and maintained in MIF files, but the only way to take full advantage is through manual editing of MIF files. The current tools only deal with the simpler relations.
 
At present we have a very rich set of relationships that can be expressed and maintained in MIF files, but the only way to take full advantage is through manual editing of MIF files. The current tools only deal with the simpler relations.
 +
== Development Process Considerations ==
 +
<!-- This section is optional.  It identifies thoughts or guidance around how the artifact will be used.  This may include development process, guidance on how many of this type of artifact are likely to exist within a domain or topic, etc. -->
 +
 +
== Governance Process Considerations ==
 +
<!-- This section is optional.  It identifies anticipated or existing governance processes that control or impact the development and adoption of this type of artifact.  -->
 +
# All Vocabulary content that is maintained and Published for the '''universal realm''' SHALL be adopted through the HL7 [[Vocabulary and RIM Harmonization Process]].
 +
## <i>Rationale</i>: Established governance
 +
# Primary rules for submission are documented in:
 +
#*Instructions in the [http://www.hl7.org/documentcenter/public/harmonization/HL7HarmonizationProposal.zip Harmonization Proposal Submission Template]
 +
#*:
 +
#*Rules and principles of the HL7 [[Vocabulary and RIM Harmonization Process]]
 +
 +
== Issues ==
 +
<!-- This section is optional. It identifies any outstanding issues (methodology or otherwise) that need to be resolved/answered as part of the guidelines -->

Latest revision as of 16:42, 9 April 2011

Return to Artifact List

Vocabulary Model

Definition and Purpose

A package or release of a set of vocabulary artifacts drawn from - Concept Domains, Code Systems, Value Sets, Context Bindings, Code System Supplements, and Code Translations - assembled to meet a particular set of needs. A Vocabulary Model may be published at a Universal or realm level.

SAIF Matrix Location

Row(s)

  • Level-Independent

Column(s)

  • Information

Audience

Health Care Information Technology (IT) Audiences:

  • System designers and architects
  • Programmers/implementers

A vocabulary model will be needed for any SAIF project that is defining or publishing an information model. Thus it is applicable to all technology implementation audiences.

Applicability

A Vocabulary Model is needed to support and document the terminology constraints of any information model and/or data types model. Therefore a Vocabulary Model must exist for any project at any level (Row) of the SAIF.

Rationale: The source for the terminology constraints for and information model is one or more "Vocabulary Model(s)" that the information model "includes."

There will be one Vocabulary Model at the "universal" level, and may be one Vocabulary Model defined for each affiliate realm.

Rationale: The "universal" model expresses the code systems, concept domains and value sets defined for universal use, including those value sets that must be used in all realms owing to there being a "universal" binding. Similarly, the realm-specific Vocabulary Model expresses the further code systems, etc. defined for realm-specific use.

Requirements, Relationships and Content

  1. The Vocabulary Model is intended to assist in packaging and managing the myriad component artifacts needed to satisfy the constraints on encoded elements in a particular set of information models and/or data types models.
    1. Rationale Encoded information model and data types model elements have a mandatory binding to one or more terminology artifacts that are contained in a vocabulary model. In turn those information models and data types models have a required relationship to the Vocabulary Model that contains the needed artifacts.
  2. A statement of the purpose that determines the contents that make up this particular Vocabulary Model.
    1. Rationale A vocabulary model may include a single sub-artifact, such as a Concept domain, or it may include all of the sub-artifacts that HL7 manages. The selection criteria or requirements must be expressed in text.

Relationships and traceability

  • A vocabulary model may replace or be replacedBy one or more other vocabulary models
    • Rationale: In serial publication of vocabulary models this provides the traceability between sets of vocabulary models wherein one may supercede another.
  • A vocabulary model may dependOn one or more other vocabulary models
    • Rationale: Provides a means for combining (including) content from multiple vocabulary models into a single grouping.
  • A vocabulary model may contain one or more of each of the following artifacts:
    Rationale: Satisfy requirements

Artifact types that may or must relate to this artifact types - Vocabulary Models are imported as part of the definition of each information model and each data types model in the SAIF therefore the following artifacts MUST relate to a Vocabulary model:

Content

Each of the following is a SAIF Artifact in its own right, but is packaged as a sub-artifact of a Vocabulary Model

Rationale A Vocabulary Model supports the individual terminology constraints of the attributes of a particular information model, and of the data types model that is included in that model. Therefore, it must have one or more of the above sub-artifacts to support or define those constraints.

Artifact Technology

Technology as of January, 2011

  • Individual contents of a Vocabulary Model (code systems, value sets, etc.) are:
    • Maintained in tables of an Access Data Base in a "design repository"
    • Updated by Java-based software driven from XML source files in the HL7-defined Vocabulary Maintenance Language (VML)
    • Selected content in Access that cannot be changed via VML is added through manual entries and queries into the Access tables (about 10% of all change entries).
    • Extracted from the Access "repository" and processed into an XML file in the Model Interchange Format (MIF) by RoseTree, a Visual Basic application that runs in the Windows environment.
    • Additional Value Set definitions and context bindings that cannot be represented in the "repository" because the underlying code system is not maintained by HL7, are managed in a supplemental MIF file that is then merged (using XSLT transforms) into the released version.
  • Distribution of Vocabulary Models:
    • All distributions are made on Gforge
    • Primary distribution: is via MIF files. (XML files in MIF format.)
    • Secondary distribution: is via the Access "design repository"

Rationale

  • 'Cause that's what we've got and absent funding for a replacement/upgrade, that's what we use
  • It's good enough to limp along with

Alternatives

Preferred strategies have been mapped out, but have not advanced for lack of resources.

Content Constraints

There are no content constraints included here. The "core" definitions and constraints are documented as part of the artifact definitions for:

Content Guidelines

  1. The primary rules for change proposal submission include many guidelines or style guides. They are documented in:
  2. Guidelines for some Vocabulary artifacts can also be found in the Wiki Style Guides Category

Publishing Representation(s)

  1. As noted above, the primary distribution is via MIF files. That are read by all commonly used HL7 tools
    1. Rationale: Hl7's preferred distribution of processable files is MIF
  2. Publication of Vocabulary content is presented in sets of HTML files generated by a single transform against the content in the vocabulary core MIF files.
    1. Rationale: HL7's preferred publication is HTML from MIF files, so we did it that way.

Publishing Constraints

None of which I am aware.

Tooling Considerations

We need a RICH GUI interface to a tool that understands the yin/yang of terminology and makes it easy to request AND understand complex relationships that they represent. To quote Jimmy Buffett:

Now here comes the big ones.
Relationships! We all got 'em, we all want 'em. What do we do with 'em?

At present we have a very rich set of relationships that can be expressed and maintained in MIF files, but the only way to take full advantage is through manual editing of MIF files. The current tools only deal with the simpler relations.

Development Process Considerations

Governance Process Considerations

  1. All Vocabulary content that is maintained and Published for the universal realm SHALL be adopted through the HL7 Vocabulary and RIM Harmonization Process.
    1. Rationale: Established governance
  2. Primary rules for submission are documented in:

Issues