Glossary Artifact Definition

Return to Artifact List

Glossary

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
        • part of speech - "noun", "verb", "adjective", "adverb", with default being "noun"
        • 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

Instances of this artifact type will be created, maintained and distributed as a file that conforms to the HL7 Model Interchange Format (MIF).

The underlying technology (as of April 2011) is:

• The "Core Glossary" (identifier is just the "namespace realm" for universal) is maintained in "publishing" xml but will be converted within months to MIF.
• "Local" glossaries for domains is captured in that domain's publication database (Access). When the domain content is extracted, a glossary file is also extracted for conversion to MIF and merger.
• Glossaries for single documents are captured as:
  • Stand-alone xml files for conversion to MIF and merger

  • In-line term definitions that can be extracted to glossary MIF and will (in future) be replaced with "include" links to their glossary.
• Editing:
  • of definitions in the PubDb can be linked to XML-spy in a quasi-WYSIWYG GUI
  • XML-editor of choice with no special support for reviewing markup except by rapid transform to "final form", which is available through current V3 Publishing Tools.

Rationale

• The whole of the HL7 specification management and publication process is based on the notion of producing "processable" content files in MIF that can be used to publish the ballot. The glossaries have been managed in XML for over almost a decade.
• The objective of the evolution of these tools is to move to an open platform dependent (Java). This is a work in progress.

Content Guidelines

1. "term" names should be all lower case unless they are specifically an acronym, or pointing a definition that is capitalized in general usage. Thus the term should be "serialized information model" and the acronym term should be "SIM"
   1. Rationale: This is start of a style guide.
2. "definitions" should start with a "noun phrase" that presupposes a lead in of "<term> is " to form a sentence. Subsequent elements of the definition should be complete sentences.
   1. Rationale: See HL7 annotation style guide for definitions.
3. All acronyms that are included as terms should link to their definition under a fully spelled out term. Do not list a definition for an acronym.
   1. Rationale: This is start of a style guide.

Publishing Representation(s)

1. At present, standard publishing within HL7 produces:

   • A universal "core" glossary at the level of the ballot itself that includes solely "global" or core content
   • A domain- or document-specific glossary for each domain or document being balloted that includes both the "core" glossary and the specific terms.

Tooling Considerations

1. Nice-to-have|Required: WYSIWYG editor for reviewing, editing and creating glossary content.
   1. Rationale: Too easy to skip glossary steps if it is not easy to use them.

Development Process Considerations

1. Regardless of whether authors are writing a text document, creating an information model, etc., two critical elements should be available to them:

   1. Ready access to the existing glossary content for review, and, perhaps for inclusion, in the specification they are creating; and
   2. A straightforward means of adding new glossary terms to their own domain.

   1. Rationale: Glossaries are often overlooked simply because they are secondary to the business of writing rather than integral thereto.