This wiki has undergone a migration to Confluence found Here

Difference between revisions of "Glossary Artifact Definition"

From HL7Wiki
Jump to navigation Jump to search
Line 71: Line 71:
  
 
=== Content ===
 
=== 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.) -->
 +
<b>glossary</b> - the collection itself
 +
*<b>glossary identifier</b> including elements for
 +
**'''''namespace realm''''' - universal or an affiliate realm
 +
**'''''domain''''' - in which glossary being defined
 +
**'''''artifact type''''' - for specifications like RIM, etc.
 +
**'''''specification name''''' - unique name to identify non-artifact documented specifications/
 +
*<b>term definitions</b> (1..*) - core content for the glossary
 +
**<b>term</b> (1..1) - the term being defined, which is also the primary identifier 
 +
***<b>definition</b> (0..*) - the text plus translations thereof
 +
****<i>definition properties</i> - additional properties for managing definitions
 +
*****<b>sequence</b> for distinguishing multiple definitions in same context
 +
*****<b>is preferred</b> - will select the preferred definition where there are multiples
 +
*****<b>secondary identifier</b> - to provide another index to the content (in addition to "term") that will allow aggregation of the content into a single namespace for publishing purposes.
 +
**<b>term translation</b> (0..*) - provides for translations of the term name.
 +
**<b>alternative term</b> (0..*) - provides a reference to another glossary term that either enhances the definition, or (if no definition is recorded above) provides the definition (as for an acronym). 
 +
 +
<!-- PRELIMINARY NOTES:
 +
MIF -  (bold is element)
 +
*'''glossary'''
 +
**title (0..1)
 +
**secondaryId (0..1)
 +
**:
 +
**'''packageLocation (0..1)'''
 +
***all standard elements
 +
**:
 +
**'''replaces (0..*)''' (glossary by ref)
 +
**'''replacedBy (0..*)''' (glossary by ref)
 +
**'''importedGlossary (0..*)''' (glossary by ref) "base glossary" whose terms will be overridden if defined in current glossary
 +
**:
 +
**'''termDefinition (1..*)'''
 +
***term (1..1) note that this is the '''sole identifier''' at this level
 +
***:
 +
***'''definition (0..*)''' - despite being infinitely infinite, there is NO further identification except the "lang" in the text element
 +
****''''text (1..*)''' (with language)
 +
***:
 +
***'''termTranslation (0..*)'''
 +
****name (1..1) - translated term
 +
****lang (0..1)
 +
****'''realmNamespace (0..*)''' in which used or managed
 +
*****value  (1..1)
 +
***:
 +
***'''seeAlso (0..*)''' type is a string holding a term to reference
 +
 +
identifier elements (min) reqd choices for publishing include : artifact realm domain name
  
<!-- 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.) -->
+
gl identified by:
* <b>Content element name</b> - Brief Description
+
 
* <b>Another content element name</b> - Brief Description
+
should be artifact (not defined in a domain like the RIM, DAM, DT, VO, DC , but these are NOT presently allowed a GL)
** <b>Sub-element name</b> - Brief Description
+
 
* <b>Another content element name</b> - Brief Description
+
domain-realm
 +
artifact-domain-realm
 +
 
 +
name-realm (Like core principles) -->
  
 
== Artifact Technology ==
 
== Artifact Technology ==

Revision as of 21:39, 19 April 2011

Return to Artifact List

Glossary - incomplete

Definition and Purpose

Is a collection of defined terms used in the specifications created for a particular domain or project. It collects defined terms from a variety of sources and makes them and their definitions available for "re-use" in other standards and publications.

SAIF Matrix Location

This artifact is "Level-independent" because it is may be required at any level at which other artifacts or specifications are being defined. Glossaries are managed to serve all levels. Row(s)

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

Column(s)

  • Enterprise/Business
  • Information

Audience

The audience is all audiences because the definitional clarity provided by a glossary is intended to inform any audience.

Health Care Community Audiences:

  • General public
  • Health care practitioners
  • Health system administrators
  • Health care policy makers

Health Care Information Technology (IT) Audiences:

  • System designers and architects
  • System purchasers
  • Programmers/implementers
  • System vendor management

Applicability

This artifact should be created wherever new terminology is being introduced for use in HL7 specifications. Because of the management requirements of glossaries, they should be defined, in general, at the domain level rather than as part of artifacts of a lower scope.

Rationale:Glossary term definitions need to be overseen by the Work Groups that create them and must be managed, overall, for publishing in HL7. Thus the glossary content should be aggregated, to the degree possible, within Work Groups and domains.

Requirements, Relationships and Content

  1. Each glossary term must be unique within the context in which it is defined.
    1. Rationale Terms are referenced by their names.
  2. Each glossary term must be defined within a context that is one of:
    • A domain-realm combination of a namespace realm and an HL7 domain level;
    • A specification document and the namespace realm in which it is defined (such as "Core Principles" or an "Implementable Technology Specification" in the "universal" namespace.)
    • A "universal" artifact that is not within a domain, such as RIM, Vocabulary Model or Abstract Data Types Model Artifact Definition|Abstract Data Types Model]].
    1. Rationale Many technology areas use more-specific or variant definitions for common words. These contextual definitions need to be presented along with the common and there must be a way to link to the contextual definitions when publishing. For example, the word "transport" when used in the context of Emergency Care as opposed to the context of a Transmission Protocol.
  3. Each term must permit of alternate definitions in the same context.
    1. Rationale Many words have multiple meanings in the HL7 context. Consider the word "document" as used as a noun in CDA and as a verb in writing SAIF Artifact definitions. Also, see the definition for domain in the V3 Glossary.
  4. It must be possible to record translations to various languages for each "term" and each "definition" of the terms.
    1. Rationale The name of the organization is HL7 International
  5. The glossary must permit alternate terms for a given definition, such as "CMET" pointing to definition for "common model element type".
    1. Rationale In an environment that is rife with acronyms, this provides the ability to link an acronym to both the full term and the definition thereof.
  6. The "markup" of definitions needs to be sufficiently rich that a definition can be "included" in another document directly from the glossary source, rather than by copying.
    1. Rationale Reuse of glossary definitions across multiple documents is crucial to the maintenance of consistent standards across HL7.

Relationships and traceability

  • A glossary must be able to indicate which glossary it replaces.
    • Rationale:' In glossary management this will permit a representation and tracing of the evolution of glossaries.

Artifact types that may or must relate to this artifact types:

  • The documentation of any SAIF specification may desire to link to a particular glossary term, or to include a glossary term and its definition' in the body of the document.

Content

glossary - the collection itself

  • glossary identifier including elements for
    • namespace realm - universal or an affiliate realm
    • domain - in which glossary being defined
    • artifact type - for specifications like RIM, etc.
    • specification name - unique name to identify non-artifact documented specifications/
  • term definitions (1..*) - core content for the glossary
    • term (1..1) - the term being defined, which is also the primary identifier
      • definition (0..*) - the text plus translations thereof
        • definition properties - additional properties for managing definitions
          • sequence for distinguishing multiple definitions in same context
          • is preferred - will select the preferred definition where there are multiples
          • secondary identifier - to provide another index to the content (in addition to "term") that will allow aggregation of the content into a single namespace for publishing purposes.
    • term translation (0..*) - provides for translations of the term name.
    • alternative term (0..*) - provides a reference to another glossary term that either enhances the definition, or (if no definition is recorded above) provides the definition (as for an acronym).


Artifact Technology

Text here

Rationale

  • Some reason
  • Some other reason

Alternatives

Some technology

  • Some pro or con
  • Some other pro or con

Content Constraints

  1. Some rule
    1. Rationale: Some reason
  2. Some other rule
    1. Rationale: Some other reason

Content Guidelines

  1. Some rule
    1. Rationale: Some reason
  2. Some other rule
    1. Rationale: Some other reason

Publishing Representation(s)

  1. Some text
    1. Rationale: Some rationale
  2. Some other text
    1. Rationale: Some other rationale

Publishing Constraints

  1. Some rule
    1. Rationale: Some reason
  2. Some other rule
    1. Rationale: Some other reason

Tooling Considerations

  1. Nice-to-have|Required: Some feature
    1. Rationale: Some rationale
  2. Nice-to-have|Required: Some other feature
    1. Rationale: Some other rationale

Development Process Considerations

  1. Some text
    1. Rationale: Some rationale
  2. Some other text
    1. Rationale: Some other rationale

Governance Process Considerations

  1. Governance Process name - Some process description
    1. Rationale: Some rationale
  2. Another Governance Process name - Process description
    1. Rationale: Some other rationale

Issues

  • Some issue
  • Some other issue