Annotations are a set of free-hand descriptive elements that accompany most, though not all HL7 v3 artifacts and sub-artifacts. They are broken up into a series of categories, each having a distinct objective and target audience. Some may have additional supplemental metadata. Each artifact or component of an artifact that allows annotations identifies exactly which types of annotations are allowed for that particular element based on what makes sense for that element. For example, formal constraints may make sense for static model elements, but have little relevance for concept domains which are purely descriptive in nature and have nothing to formally constrain.
MIF: mif-core-base.xsd\Annotations
Annotation Components
| Requirement
|
Descriptive free-text metadata about an artifact must be able to be captured in a primary language along with translations to other languages
|
| Rationale
|
Many HL7 specifications are used by many countries. Even within a country, there is often a need to publish multiple languages to meet official language requirements or to satisfy the needs of local implementers.
|
| MIF
|
- mif-core-base.xsd\BasicAnnotation\text (multiple repetitions)
- mif-core-base.xsd\BasicAnnotation\text\@lang
|
| Requirement
|
In situations where multiple translations are provided for free-hand text, there is a need to know whether a given translation is up-to-date with the source.
|
| Rationale
|
The person or group responsible for providing the translation is frequently not the person or group who creates or modifies the initial "primary" version. And because HL7 is a volunteer organization, the time between the primary content being updated and the update being propagated to all translations can vary. Knowing whether a given translation is up-to-date is useful both for readers (who need to know that the content is suspect) as well as those responsible for providing translations so they know where work remains to be done.
|
| MIF
|
mif-core-base.xsd\BasicAnnotation\text\@lastTranslated
|
| Requirement
|
Some types of annotations, particularly those that can have multiple repetitions such as constraints, need to to be referenceable such that in derived artifacts the relationship between a given annotation in the derived model can be linked to the corresponding annotation in the parent model. (See Requirements-
|
| Rationale
|
The person or group responsible for providing the translation is frequently not the person or group who creates or modifies the initial "primary" version. And because HL7 is a volunteer organization, the time between the primary content being updated and the update being propagated to all translations can vary. Knowing whether a given translation is up-to-date is useful both for readers (who need to know that the content is suspect) as well as those responsible for providing translations so they know where work remains to be done.
|
| MIF
|
mif-core-base.xsd\BasicAnnotation\text\@lastTranslated
|
Annotation Types
| Requirement
|
All major HL7 artifacts and artifact components require either a description that identifies what the element is or a definition that provides the semantic meaning for that element.
|
| Rationale
|
Some HL7 artifacts and components convey explicit semantic meaning, for example classes, attributes, concept domains, coded concepts, etc. Other artifacts do not represent particular meaning but still require an explanation of that the artifact is and why it exists.
Lack of documentation on an artifact or component can lead to confusion about what the artifact or component is or what it's for.
|
| MIF
|
- mif-core-base.xsd\Annotations\documentation\definition
- mif-core-base.xsd\Annotations\documentation\description
|
| Requirement
|
It must be possible to identify constraints to the usage of a given element that can't be formally expressed
|
| Rationale
|
HL7 artifacts often have constraints that can't be formally asserted using XMI or other constraint languages, possibly because they apply to content outside the instance or because there's simply no formal way to express the rule. However, these are still rules that must be followed by implementations and therefore need to be called out distinctly from implementation notes or other general recommendations.
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\usageConstraint
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\usageNotes
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\rationale
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\requirements
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\designComments
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\stabilityRemarks
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\walkthrough
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\appendix
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\otherAnnotation
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\mapping
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\formalConstraint
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\openIssue
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\staticExample
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\ballotComment
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\changeRequest
|
| Requirement
|
|
| Rationale
|
|
| MIF
|
mif-core-base.xsd\Annotations\documentation\deprecationInfo
|
