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}}")
 
 
(11 intermediate revisions by the same user not shown)
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 drawn from - [[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]] - 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)
+
* '''Level-Independent'''
* Logical (PIM)
 
* Implementable (PSM)
 
  
 
'''Column(s)'''
 
'''Column(s)'''
* Enterprise/Business
 
 
* Information
 
* Information
* Computational
 
* Engineering
 
  
 
== Audience ==
 
== Audience ==
 +
Health Care Information Technology (IT) Audiences:
 +
*System designers and architects
 +
*Programmers/implementers
  
<!-- 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 technology implementation audiences.
Text
 
  
 
== 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.
  
<!-- Under what circumstances does this artifact type need to be created?  Are there circumstances where this artifact should not exist?  Why? -->
+
:<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."
Text
 
  
<i>Rationale</i>: More text
+
There will be one Vocabulary Model at the "universal" level, and may be one Vocabulary Model defined for each affiliate realm.
  
== Requirements ==
+
:<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, Relationships and Content ==
 
<!-- 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.) -->
 
<!-- 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.) -->
# Some requirement
+
#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>Some reason
+
##<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.
# Some other requirement
+
#A statement of the purpose that determines the contents that make up this particular Vocabulary Model.
## <i>Rationale</i>Some other reason
+
## <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.
 +
 
 +
=== 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?
 +
 
 +
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. 
 +
-->
 +
* 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.
 +
* A vocabulary model may '''dependOn''' one or more other vocabulary models
 +
** <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]]
 +
*:*[[Context Binding Artifact Definition| Context Bindings]]
 +
*:*[[Code System Supplement Artifact Definition|Code System Supplements]] and
 +
*:*[[Code Translations Artifact Definition|Code Translations]]
 +
*: <i>Rationale</i>: Satisfy requirements
  
== Relationships and traceability ==
+
<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.
  
<!-- What are the other artifacts that are related to this artifact?  How?  Why is the relationship important? -->
+
=== Content ===
* Some relationship
+
<!-- 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.) -->
** <i>Rationale</i>: Reason for relationship
+
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]]
  
* Some other relationship
+
:<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.
** <i>Rationale</i>: Reason for other relationship
 
  
 
== 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 "[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)
 +
**:
 +
**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 "design 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 ==
 
+
There are no content constraints included here.  The "core" definitions and constraints are documented as part of the artifact definitions for:
<!-- 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. -->
+
*[[Concept Domain Artifact Definition| Concept Domains]]
# Some rule
+
*:
## <i>Rationale</i>: Some reason
+
*[[Code System Artifact Definition| Code Systems]]
# Some other rule
+
*:
## <i>Rationale</i>: Some other reason
+
*[[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]]
  
 
== Content Guidelines ==
 
== Content Guidelines ==
 
+
# The primary rules for change proposal submission include many guidelines or style guides. They are documented in:
<!-- 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. -->
+
#*Instructions in the [http://www.hl7.org/documentcenter/public/harmonization/HL7HarmonizationProposal.zip Harmonization Proposal Submission Template]
# Some rule
+
# Guidelines for some Vocabulary artifacts can also be found in the [[:Category:StyleGuides| Wiki Style Guides Category]]
## <i>Rationale</i>: Some reason
 
# Some other rule
 
## <i>Rationale</i>: Some other reason
 
  
 
== 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
+
:'''''Now here comes the big ones.'''''
## <i>Rationale</i>: Some rationale
+
:'''''Relationships! We all got 'em, we all want 'em. What do we do with 'em?'''''
# Nice-to-have|Required: Some other feature
 
## <i>Rationale</i>: Some other rationale
 
  
 +
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 ==
 
== 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. -->
 
<!-- 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
+
== Governance Process Considerations ==
## <i>Rationale</i>: Some rationale
+
<!-- This section is optional.  It identifies anticipated or existing governance processes that control or impact the development and adoption of this type of artifact.  -->
# Some other text
+
# 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>: Some other rationale
+
## <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 ==
 
== Issues ==
 
 
 
<!-- This section is optional. It identifies any outstanding issues (methodology or otherwise) that need to be resolved/answered as part of the guidelines -->
 
<!-- 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
 
* Some other issue
 

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