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
(Created page with "{{subst::Template:SAIF Artifact Definition}}")
 
Line 1: Line 1:
 
 
[[Category:SAIF Artifact Definition]]
 
[[Category:SAIF Artifact Definition]]
 
[[:Category:SAIF Artifact Definition|Return to Artifact List]]
 
[[:Category:SAIF Artifact Definition|Return to Artifact List]]
  
=Some Artifact Name=
+
=Vocabulary Model=
 
 
<!-- Artifact names should be descriptive and short.  They may change as we further refine the methodology -->
 
  
 
== Definition and Purpose ==
 
== Definition and Purpose ==
  
<!-- At a high level, what is this artifact and why is it needed?  Should ideally be only a few sentences -->
+
A package or release of a set of vocabulary artifacts - [[Concept Domain Artifact Definition| Concept Domains]], [[Code System Artifact Definition| Code Systems]], [[Value Set Artifact Definition| Value Sets]] and [[Context Binding Artifact Definition| Context Bindings]] assembled to meet a particular set of needs. A Vocabulary Model may be published at a Universal or realm level.
 
 
Put text here
 
  
 
== SAIF Matrix Location ==
 
== SAIF Matrix Location ==
 
<!-- Where does this artifact fit into the SAIF matrix?  Delete those rows and columns that do not apply and provide qualification if appropriate -->
 
 
'''Row(s)'''
 
'''Row(s)'''
 
* Conceptual (CIM)
 
* Conceptual (CIM)
Line 22: Line 15:
  
 
'''Column(s)'''
 
'''Column(s)'''
* Enterprise/Business
 
 
* Information
 
* Information
* Computational
 
* Engineering
 
  
 
== Audience ==
 
== Audience ==
  
<!-- Who will be the consumers of this artifact type and what will they do with it? -->
+
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.
Text
 
  
 
== Applicability ==
 
== Applicability ==
  
<!-- Under what circumstances does this artifact type need to be created?  Are there circumstances where this artifact should not exist?  Why? -->
+
A Vocabulary Model is needed to support and document the terminology constraints of any information model, which, in MIF terms, "includes" that vocabulary model.  This vocabulary model may be specifically assembled to meet the needs of that information model or be an independently-published artifact.
Text
+
<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>: More text
 
  
 
== Requirements ==
 
== Requirements ==
 
+
# 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.) -->
+
## <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.
# Some requirement
+
# Contain one or more sub-artifacts from the following artifact definitions:
## <i>Rationale</i>Some reason
+
#:*[[Concept Domain Artifact Definition| Concept Domains]]
# Some other requirement
+
#:*[[Code System Artifact Definition| Code Systems]]
## <i>Rationale</i>Some other reason
+
#:*[[Value Set Artifact Definition| Value Sets]] and
 +
#:*[[Context Binding Artifact Definition| Context Bindings]]
 +
## <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 that are related to this artifact?  How?  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.
* Some relationship
+
** <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.
** <i>Rationale</i>: Reason for relationship
+
* 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.
* Some other relationship
+
* A vocabulary model may '''dependOn''' one or more other vocabulary models
** <i>Rationale</i>: Reason for other relationship
+
** <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:
 +
#:*[[Concept Domain Artifact Definition| Concept Domains]]
 +
#:*[[Code System Artifact Definition| Code Systems]]
 +
#:*[[Value Set Artifact Definition| Value Sets]] and
 +
#:*[[Context Binding Artifact Definition| Context Bindings]]
 +
** <i>Rationale</i>: Satisfy requirements
  
 
== Artifact Technology ==
 
== Artifact Technology ==
  
<!-- What technological/standard solution has been selected for use in creating this artifact and why? -->
+
Technology as of January, 2011
Text here
+
*'''Individual contents of a Vocabulary Model''' (code systems, value sets, etc.) are:
 
+
**Maintained in tables of an Access Data Base in a "repository"
 +
**:
 +
**Updated by Java-based software driven from XML source files in the HL7-defined [[Vocabulary_Maintenance_Language | 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 [[Installing_and_Configuring_HL7_Tools#RoseTree|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 [http://gforge.hl7.org Gforge]
 +
**:
 +
**'''Primary distribution:''' is via MIF files. (XML files in MIF format.)
 +
**:
 +
**Secondary distribution: is via the Access "repository"
 
=== Rationale ===
 
=== Rationale ===
  
<!-- What's the justification for selecting the chosen technology? -->
+
* 'Cause that's what we've got and absent funding for a replacement/upgrade, that's what we use
* Some reason
+
* It's good enough to limp along with
* Some other reason
 
  
 
=== Alternatives ===
 
=== Alternatives ===
  
<!-- What other technical solutions might have been possible that were discarded, what did they offer and why were they not chosen? -->
+
Preferred strategies have been mapped out, but have not advanced for lack of resources.
 
 
<b>Some technology</b>
 
* Some pro or con
 
* Some other pro or con
 
  
 
== 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]].
<!-- What are the formal rules about how the artifact can be constructed, including any extensions and constraints for the selected technology as well as the rationale for those rules. These are rules that can reasonably be enforced or validated by tools. -->
+
## <i>Rationale</i>: Established governance
# Some rule
+
#There are no further content constraints included here.  The "core" definitions are documented as part of the artifact definitions for:
## <i>Rationale</i>: Some reason
+
#*[[Concept Domain Artifact Definition| Concept Domains]]
# Some other rule
+
#:
## <i>Rationale</i>: Some other reason
+
#*[[Code System Artifact Definition| Code Systems]]
 +
#:
 +
#*[[Value Set Artifact Definition| Value Sets]] and
 +
#:
 +
#*[[Context Binding Artifact Definition| Context Bindings]]
  
 
== Content Guidelines ==
 
== Content Guidelines ==
  
<!-- What are the informal guidelines about how the artifact content. I.e. What constitutes good practice?  These guidelines should be used in the evaluation of artifact instances but generally can't be enforced or validated by tools. -->
+
# Primary rules for submission are documented in:
# Some rule
+
#*Instructions in the [http://www.hl7.org/documentcenter/public/harmonization/HL7HarmonizationProposal.zip Harmonization Proposal Submission Template]
## <i>Rationale</i>: Some reason
+
#*:
# Some other rule
+
#*Rules and principles of the HL7 [[Vocabulary and RIM Harmonization Process]]
## <i>Rationale</i>: Some other reason
+
# Guidelines for some Vocabulary artifacts are in the [[:Category:StyleGuides| Wiki Style Guides Category]]
  
 
== Publishing Representation(s) ==
 
== Publishing Representation(s) ==
  
<!-- How will this artifact be shared and published as part of specifications? -->
+
# As noted above, the primary distribution is via MIF files. That are read by '''all''' commonly used HL7 tools
# Some text
+
## <i>Rationale</i>: Hl7's preferred distribution of processable files is MIF
## <i>Rationale</i>: Some rationale
+
# 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.
# Some other text
+
## <i>Rationale</i>: HL7's preferred publication is HTML from MIF files, so we did it that way.
## <i>Rationale</i>: Some other rationale
 
  
 
== Publishing Constraints ==
 
== Publishing Constraints ==
  
<!-- What are the constraints imposed by the publishing process on how artifacts are constructed and submitted to HL7and what are the reasons behind such constraints? -->
+
None of which I am aware.
# Some rule
 
## <i>Rationale</i>: Some reason
 
# Some other rule
 
## <i>Rationale</i>: Some other reason
 
  
 
== Tooling Considerations ==
 
== Tooling Considerations ==
  
<!-- What tooling features are required or "nice to have" to allow successful development, publication or other use of the artifact? -->
+
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:
# Nice-to-have|Required: Some feature
+
:'''''Relationships! We all got 'em, we all want 'em. What do we do with 'em?'''''
## <i>Rationale</i>: Some rationale
 
# Nice-to-have|Required: Some other feature
 
## <i>Rationale</i>: Some other rationale
 
 
 
== 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. -->
 
 
 
# Some text
 
## <i>Rationale</i>: Some rationale
 
# Some other text
 
## <i>Rationale</i>: Some other rationale
 
 
 
 
 
== Issues ==
 
 
 
 
 
<!-- This section is optional. It identifies any outstanding issues (methodology or otherwise) that need to be resolved/answered as part of the guidelines -->
 
  
* Some issue
+
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.
* Some other issue
 

Revision as of 21:01, 7 April 2011

Return to Artifact List

Vocabulary Model

Definition and Purpose

A package or release of a set of vocabulary artifacts - Concept Domains, Code Systems, Value Sets and Context Bindings 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)

  • Conceptual (CIM)
  • Logical (PIM)
  • Implementable (PSM)

Column(s)

  • Information

Audience

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.

Applicability

A Vocabulary Model is needed to support and document the terminology constraints of any information model, which, in MIF terms, "includes" that vocabulary model. This vocabulary model may be specifically assembled to meet the needs of that information model or be an independently-published artifact. Rationale: The source for the terminology constraints for and information model is one or more "Vocabulary Model(s)" that the information model "includes."

Requirements

  1. An expression of the purpose that determines the contents that make up this particular Vocabulary Model.
    1. RationaleA 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.
  2. Contain one or more sub-artifacts from the following artifact definitions:
    1. RationaleA 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

  • One or more Vocabulary Models are imported as part of the definition of each information model and each data types model in the SAIF.
    • Rationale: 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
    • 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 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 "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 "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

  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. There are no further content constraints included here. The "core" definitions are documented as part of the artifact definitions for:

Content Guidelines

  1. Primary rules for submission are documented in:
  2. Guidelines for some Vocabulary artifacts are 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:

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.