This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "Requirements-Annotations"

From HL7Wiki
Jump to navigation Jump to search
Line 42: Line 42:
 
| ''MIF''  
 
| ''MIF''  
 
| mif-core-base.xsd\BasicAnnotation\@id
 
| mif-core-base.xsd\BasicAnnotation\@id
 +
| mif-core-base.xsd\Appendix\@name (when the id isn't a "standard" id)
 +
| mif-core-base.xsd\OtherAnnotation\@name (when the id isn't a "standard" id)
 
|}
 
|}
  
Line 154: Line 156:
 
|-
 
|-
 
| ''MIF Issues''
 
| ''MIF Issues''
| [[MIFNotUsed]]
+
| {{MIF Not Used}}
 
No tools do this yet.  (Idea stolen from Eclipse)
 
No tools do this yet.  (Idea stolen from Eclipse)
 
|-
 
|-
Line 203: Line 205:
 
{| border="2" cellspacing="0" cellpadding="3" width="600"
 
{| border="2" cellspacing="0" cellpadding="3" width="600"
 
| '''Requirement'''  
 
| '''Requirement'''  
|  
+
| Appendices need titles
 +
|-
 +
| ''Rationale''
 +
| As a distinct "document within an artifact", a label for the appendix for use in table of contents and other publishing mechanisms is required.
 +
|-
 +
| ''MIF''
 +
| mif-core-base.xsd\Annotations\documentation\appendix\@title
 +
|}
 +
 
 +
 
 +
{| border="2" cellspacing="0" cellpadding="3" width="600"
 +
| '''Requirement'''
 +
| There's a need for local implementations to embed "additional" information inside HL7 artifacts in a way that can safely be retained and managed by existing HL7 tools without a need to adjust the tools to specifically support each local requirement
 
|-
 
|-
 
| ''Rationale''  
 
| ''Rationale''  
|  
+
| HL7 development is a highly dynamic environment.  New requirements arise.  Jurisdictions or local implementers sometimes have "extra" information they need to capture within an artifact or artifact component.  While eventually the MIF may be modified to explicitly support these requirements, the change process for tools and the methodology isn't always fast enough to accommodate the needs in a timely manner.  And sometimes it makes sense to "try out" an idea before officially adding it to the methodology.
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
Line 215: Line 229:
 
{| border="2" cellspacing="0" cellpadding="3" width="600"
 
{| border="2" cellspacing="0" cellpadding="3" width="600"
 
| '''Requirement'''  
 
| '''Requirement'''  
|  
+
| Other annotations need to be "typed"
 +
|-
 +
| ''Rationale''
 +
| For local extensions to the MIF to be useful, they need to be "typed" by named categories to allow extensions of one type to be differentiated from other types.  This is essential for both user differentiation and to allow locally customized tooling to process specific extension types
 +
|-
 +
| ''MIF''
 +
| mif-core-base.xsd\Annotations\documentation\otherAnnotation\@type
 +
|}
 +
 
 +
 
 +
{| border="2" cellspacing="0" cellpadding="3" width="600"
 +
| '''Requirement'''
 +
| There's a need to know whether MIF extensions are intended to be published using standard publication rendering for free-text markup, or whether MIF extensions are some other form of marked up content
 +
|-
 +
| ''Rationale''
 +
| HL7 content, including extensions need to be published and validated.  That means distinguishing between publication markup and plain text or "ad hoc" XML
 +
|-
 +
| ''MIF''
 +
| mif-core-base.xsd\Annotations\documentation\otherAnnotation\text
 +
| mif-core-base.xsd\Annotations\documentation\otherAnnotation\data
 +
|}
 +
 
 +
 
 +
{| border="2" cellspacing="0" cellpadding="3" width="600"
 +
| '''Requirement'''
 +
| There is a need to identify linkages between existing HL7 v3 artifacts and artifact components and artifacts from other specifications or legacy implementations.
 +
|-
 +
| ''Rationale''
 +
| HL7 v3 specifications don't exist in a vacuum.  There may be other standards in the same space or local implementations.  Mapping an HL7 specification to corresponding elements of another specification is a significant aid to both understanding and applying a specification.
 +
|-
 +
| ''MIF''
 +
| mif-core-base.xsd\Annotations\appInfo\mapping
 +
|}
 +
 
 +
 
 +
{| border="2" cellspacing="0" cellpadding="3" width="600"
 +
| '''Requirement'''
 +
| Within mappings it's essential to identify the specification and possibly version being mapped to.
 
|-
 
|-
 
| ''Rationale''  
 
| ''Rationale''  
|  
+
| There can be mappings to more than one specification for a given artifact.  To create reports of mappings, or even understand mappings, you need to know what's being mapped to.  (For "local" HL7 artifacts, implementers may validate that all elements have particular mappings or that all elements from a particular specification are mapped.
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\mapping
+
| mif-core-base.xsd\Annotations\appInfo\mapping\@sourceName
 +
| mif-core-base.xsd\Annotations\appInfo\mapping\@sourceVersion
 
|}
 
|}
  
Line 233: Line 285:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\formalConstraint
+
| mif-core-base.xsd\Annotations\appInfo\formalConstraint
 
|}
 
|}
  
Line 245: Line 297:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\openIssue
+
| mif-core-base.xsd\Annotations\appInfo\openIssue
 
|}
 
|}
  
Line 257: Line 309:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\staticExample
+
| mif-core-base.xsd\Annotations\appInfo\staticExample
 
|}
 
|}
  
Line 269: Line 321:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\ballotComment
+
| mif-core-base.xsd\Annotations\appInfo\ballotComment
 
|}
 
|}
  
Line 281: Line 333:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\changeRequest
+
| mif-core-base.xsd\Annotations\appInfo\changeRequest
 
|}
 
|}
  
Line 293: Line 345:
 
|-
 
|-
 
| ''MIF''  
 
| ''MIF''  
| mif-core-base.xsd\Annotations\documentation\deprecationInfo
+
| mif-core-base.xsd\Annotations\appInfo\deprecationInfo
 
|}
 
|}

Revision as of 14:44, 1 July 2009

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.
Rationale In derived artifacts the relationship between a given annotation in the derived model needs to be able to be linked to the corresponding annotation in the parent model. (See Constraint Derivation)
MIF mif-core-base.xsd\BasicAnnotation\@id mif-core-base.xsd\Appendix\@name (when the id isn't a "standard" id) mif-core-base.xsd\OtherAnnotation\@name (when the id isn't a "standard" id)


Requirement Users must be able to control whether a given annotation appears in the graphical representation of the model.
Rationale In general, there will be too many annotations on a model and they will be too long to reasonably expose them all on a diagram. However, some annotations are of sufficiently high importance that a designer will want them to be exposed in the graphic representation.
MIF mif-core-base.xsd\BasicAnnotation\@graphicLinkId


Requirement Users must be able to control whether a given annotation appears in the graphical representation of the model.
Rationale In general, there will be too many annotations on a model and they will be too long to reasonably expose them all on a diagram. However, some annotations are of sufficiently high importance that a designer will want them to be exposed in the graphic representation.
MIF mif-core-base.xsd\BasicAnnotation\@graphicLinkId

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 Designers need to provide documentation for implementers or other users on how a given artifact or artifact component is intended to be used
Rationale Artifacts are usually created with a specific use in mind. Often this use is self-evident, but often there are aspects that may not be immediately obvious to the reader of the specification. There's a need to document these aspects and to call them out so they can easily be read by implementers who may be less interested in other documentation about the artifact.
MIF mif-core-base.xsd\Annotations\documentation\usageNotes


Requirement Artifacts and artifact components need to capture documentation about the rationale for why they exist and why they exist the way they do.
Rationale HL7 artifacts are often produced and maintained over a period of many years by teams of ever-changing volunteers. The reason why any given element exists or why it is modeled, constrained or otherwise represented in a particular manner will quickly be forgotten and lost if it is not captured. Capturing the rationale helps in the review process (by aiding the understanding of why the element is as it is) and also helps in ongoing maintenance by allowing proposed changes to be evaluated against the original justification.
MIF mif-core-base.xsd\Annotations\documentation\rationale


Requirement There is a need to capture or link to the requirements that drove the creation of a particular artifact or sub-artifact.
Rationale Most HL7 artifacts and artifact components originate due to some need expressed by one or more member participants. Sometimes these needs are formally represented as requirements artifacts. However, in other circumstances the requirements are captured as part of the artifact creation. Requirements help to provide context for an artifact and can also be used to evaluate the artifacts appropriateness.
MIF mif-core-base.xsd\Annotations\documentation\requirements


Requirement Artifacts and their components need a 'private' place to capture development notes
Rationale During the development process, standards developers often need to capture temporary notes to themselves about things to fix, questions about the design, future plans, etc. These comments are not intrended to be part of the "official" artifact and need to be partitioned so that they can be excluded from publication and usual display.
MIF mif-core-base.xsd\Annotations\documentation\designComments


Requirement Design comments should be categorized
Rationale Most design comments fit into one of three categories "fix me", "to do" and general notes. It is useful to be able to search for design comments indicating things that need to be fixed or "planned" changes.
MIF Issues

No tools do this yet. (Idea stolen from Eclipse)

MIF mif-core-base.xsd\Annotations\documentation\designComments\@tag


Requirement Users of HL7 artifacts need an idea of how stable an artifact is deemed to be and known expected sources of change.
Rationale Most artifacts produced by HL7 are in a state of evolution. However the degree of expected change can vary significantly. Some artifacts are known to be unstable, perhaps because of uncertain requirements, lack of implementation experience, active debate about appropriate solutions, etc. As an implementer, it's essential to have a sense of what things are believed to be stable and what things are likely to change (and if they change what sorts of changes are most probable). Knowing this information allows them to choose where to focus their development effort and where and how to build flexibility into their solutions.
MIF mif-core-base.xsd\Annotations\documentation\stabilityRemarks


Requirement Complex artifacts need overview documentation that highlights key aspects and provides a quick summary of features and capabilities.
Rationale Many HL7 artifacts such as static models, datatype models, etc. are extremely complex and are made up of a large number of components. Even with a graphical representation, it can be challenging to identify the core areas or understand what they're for.
Methodology Complex artifacts in HL7 are expected to include a piece of documentation called a "walkthrough" that highlights the core aspects of the artifact identifying how the pieces fit together, what they are for and making recommendations for how a reader should approach reading the details of the artifact.
MIF mif-core-base.xsd\Annotations\documentation\walkthrough


Requirement Some HL7 v3 artifacts have "addendum" documents that provide support or background for the artifact. They are published and balloted together with the primary document.
Rationale Several HL7 artifacts, including the RIM, Datatypes & Vocabulary have background or support documents addressing such things as "constraint language for datatype constraints", "methodology behind the RIM", "vocabulary data model", etc. that while not strictly part of the content of the RIM static model, datatype specification or listing of HL7 vocabulary, are key to the understanding and interpretation of those artifacts and are considered "part" of the artifact. They are maintained as part of the same source and are published together.
MIF mif-core-base.xsd\Annotations\documentation\appendix


Requirement Appendices need titles
Rationale As a distinct "document within an artifact", a label for the appendix for use in table of contents and other publishing mechanisms is required.
MIF mif-core-base.xsd\Annotations\documentation\appendix\@title


Requirement There's a need for local implementations to embed "additional" information inside HL7 artifacts in a way that can safely be retained and managed by existing HL7 tools without a need to adjust the tools to specifically support each local requirement
Rationale HL7 development is a highly dynamic environment. New requirements arise. Jurisdictions or local implementers sometimes have "extra" information they need to capture within an artifact or artifact component. While eventually the MIF may be modified to explicitly support these requirements, the change process for tools and the methodology isn't always fast enough to accommodate the needs in a timely manner. And sometimes it makes sense to "try out" an idea before officially adding it to the methodology.
MIF mif-core-base.xsd\Annotations\documentation\otherAnnotation


Requirement Other annotations need to be "typed"
Rationale For local extensions to the MIF to be useful, they need to be "typed" by named categories to allow extensions of one type to be differentiated from other types. This is essential for both user differentiation and to allow locally customized tooling to process specific extension types
MIF mif-core-base.xsd\Annotations\documentation\otherAnnotation\@type


Requirement There's a need to know whether MIF extensions are intended to be published using standard publication rendering for free-text markup, or whether MIF extensions are some other form of marked up content
Rationale HL7 content, including extensions need to be published and validated. That means distinguishing between publication markup and plain text or "ad hoc" XML
MIF mif-core-base.xsd\Annotations\documentation\otherAnnotation\text mif-core-base.xsd\Annotations\documentation\otherAnnotation\data


Requirement There is a need to identify linkages between existing HL7 v3 artifacts and artifact components and artifacts from other specifications or legacy implementations.
Rationale HL7 v3 specifications don't exist in a vacuum. There may be other standards in the same space or local implementations. Mapping an HL7 specification to corresponding elements of another specification is a significant aid to both understanding and applying a specification.
MIF mif-core-base.xsd\Annotations\appInfo\mapping


Requirement Within mappings it's essential to identify the specification and possibly version being mapped to.
Rationale There can be mappings to more than one specification for a given artifact. To create reports of mappings, or even understand mappings, you need to know what's being mapped to. (For "local" HL7 artifacts, implementers may validate that all elements have particular mappings or that all elements from a particular specification are mapped.
MIF mif-core-base.xsd\Annotations\appInfo\mapping\@sourceName mif-core-base.xsd\Annotations\appInfo\mapping\@sourceVersion


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\formalConstraint


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\openIssue


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\staticExample


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest


Requirement
Rationale
MIF mif-core-base.xsd\Annotations\appInfo\deprecationInfo