Requirements-Annotations

From HL7Wiki
Jump to navigation Jump to search

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
OMG Mapping Translations to other languages will require specific tool support


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.
Methodology Each annotation translation keeps track of when it was last edited. In addition, one translation is marked as "source". If the other translations do not have a last-edited date that is the same as or newer than the source, then that translation is likely not up-to-date.
MIF
  • mif-core-base.xsd\BasicAnnotation\text\@lastEdited
  • mif-core-base.xsd\BasicAnnotation\text\@isSource
OMG Mapping Add Stereotype Elements to capture information and maintain relationships


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)
OMG Mapping Add Stereotype relationship to support linking


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
OMG Mapping This is a tool specific feature, profile can be used to capture desire


Requirement Need to be able to differentiate for some annotations what realms they're associated with.
Rationale Sometimes requirements, rationale, etc. can be realm-specific.
MIF mif-core-base.xsd\ContextAnnotation\context
OMG Mapping Add Stereotype Elements to capture information

Annotation Types

Definition

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
OMG Mapping could use Notes Add Stereotype Element to capture additional information. This is also impacted by the methodology employed

Usage Constraint

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 OCL 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
OMG Mapping This cannot be directly supported. SVBR might be a good means to address this http://en.wikipedia.org/wiki/Semantics_of_Business_Vocabulary_and_Business_Rules

Usage Notes

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
OMG Mapping Stereotypes can be used to capture the information. SVBR might improve the quality, accuracy and processing of the information captured http://en.wikipedia.org/wiki/Semantics_of_Business_Vocabulary_and_Business_Rules

Rationale

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
OMG Mapping Can use UML Note support with standard UML. But a profile would add a richer means to capture and maintain the information

Requirements

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.

This is *not* the same as Rationale. Requirements is focused on formal reference to source requirements. Rationale deals with both the reason something exists (in addition to or in place to reference to formal requirements) as well as why it's expressed the way it is.

MIF mif-core-base.xsd\Annotations\documentation\requirements
OMG Mapping Add Stereotype Elements to capture information and maintain relationships

Design Comments

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 intended to be part of the "official" artifact and need to be partitioned so that they can be excluded from publication and usual display.

For example: "Need to verify this cardinality" or "Need to integrate this concept into 'finding' hierarchy"

MIF mif-core-base.xsd\Annotations\documentation\designComments
OMG Mapping Can use a profile to capture information about what is to be segregated, but tooling support will be required to address displaying requirements


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. For example, in Eclipse, there's a view that shows all places in code that are flagged as "fix me" vs. "to do", providing an easy way to navigate outstanding development actions.
MIF Issues

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

MIF mif-core-base.xsd\Annotations\documentation\designComments\@tag
OMG Mapping Can use tag to catagorize information

Stability Remarks

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
OMG Mapping The value can be captured via tags, but Methodology could help too with standard UML

Walkthrough

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
OMG Mapping UML supports various views of the same underlying model. As an example create a package for a specific review cycle, add views and reference core model elements in the respective view, add view specific information as necessary.

Appendix

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
OMG Mapping Can link to external resources. Support varies with tool vendor


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
OMG Mapping Can link to external resources. Might create a profile to capture richer information

Other Annotation

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
OMG Mapping Can be handled by the use of a profile. One approach would be to add a tag value that all elements would expose. The value can be use to capture the idea of the lifecycle of the element. Vendor tooling could greatly improve user experience.


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
OMG Mapping Can be handled by the use of a profile. Add a tag value


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
OMG Mapping Can be handled by the use of a profile. One approach would be to add a tag value that all elements would expose. The value can be use to capture the idea of the lifecycle of the element. Vendor tooling could greatly improve user experience.

Mapping

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
OMG Mapping Add Stereotype Relationship to capture linkage, if artifact is external to modle using linking


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
  • mif-core-base.xsd\Annotations\appInfo\mapping\sourceArtifact
OMG Mapping Add Stereotype Relationship to capture linkage, if artifact is external to modle using linking


Requirement Mappings should be able to identify the degree of equivalence with the mapped item
Rationale When evaluating mappings, one of the first questions is "how well does this map?". While this can be determined by analysis, once determined it's nice to be able to just expose it.
Methodology Mapping relationships can be either "Broader Than", "Narrower Than" or "Equivalent"
Issues

Not supported by tools. Not sure how likely this is to be used for "informal" mappings, which is what annotation mappings represent.

MIF
  • mif-core-base.xsd\Annotations\appInfo\mapping\@sourceName
  • mif-core-base.xsd\Annotations\appInfo\mapping\@sourceVersion
OMG Mapping Add Stereotype Element that can be used to capture the information. Also could use tag that all elements expose as part of core elements.

Formal Constraint

Requirement There is a need to capture "formal constraints" in a way that allows those constraints to be evaluated on instances of a model
Rationale There are numerous examples of constraints that can't be pre-defined as distinct metadata within artifacts, including:
  • co-occurrence constraints (e.g. if A is not present then B must be present)
  • mathematical expressions (e.g. The total of As and Bs must not exceed 5)
  • terminology expressions (If A is a specialization of X, then B must be Y)
  • etc.
MIF mif-core-base.xsd\Annotations\appInfo\formalConstraint
OMG Mapping This is support with OCL


Requirement Formal constraints may be documented in one of several languages
Rationale Not all constraint languages are (presently) capable of supporting all HL7 constraint needs. In addition, HL7 has not selected a single constraint language.
Methodology HL7 supports the following constraint languages:
  • OCL
  • XPath (when evaluated against a specific ITS)
  • HL7 Datatype Definition Language
  • Regular Expressions
MIF
  • mif-core-base.xsd\FormalConstraint\body
  • mif-core-base.xsd\FormalConstraint\alternateFormalExpression
OMG Mapping This appears to be a process issue, not modeling. HL7 should define the allowable approach

Open Issue

Requirement When capturing artifacts there needs to be a mechanism for flagging any open issues associated with those artifacts
Rationale Sometimes when HL7 artifacts are approved or submitted for approval, there are known outstanding issues. It is important that these issues be captured in a manner that allows the issues to be brought to the attention of anyone making use of the artifact as well as to be tracked by the responsible committee or group to ensure that eventually the issue is brought to resolution.
MIF mif-core-base.xsd\Annotations\appInfo\openIssue
OMG Mapping Can be handled by tag values or modeling the relationship between the artifact and an element that captures the definition of this issue


Requirement When an open issue is closed, it is important to capture the resolution.
Rationale When an open issue is resolved, this resolution needs to be communicated to those who may already have been using the artifact. It also aids in institutional memory so that the closed issue doesn't get re-opened if the participants forget what the original resolution was
MIF mif-core-base.xsd\Annotations\appInfo\openIssue\resolution
OMG Mapping Can be handled by tag values or modeling the relationship between the artifact and an element that captures the definition of this issue

Static Example

Requirement When documenting models, datatypes or portions there-of, there needs to be a way of showing how those models or model portions could be or are intended to be used over the wire.
Rationale One or two "real" examples can often convey the intention and application of a model structure far more clearly than many paragraphs of text.
MIF mif-core-base.xsd\Annotations\appInfo\staticExample
OMG Mapping Create a UML Package, add views to show intended use. Link models, datatypes or portions there-of to package


Requirement When exposing an example or example fragment, it's important to identify the Implementation Technology Specification (ITS) that the example is being constructed against.
Rationale HL7 may define multiple ITSs that can be used to serialize an instance of a static model or datatype specification. For an example to be useful to implementers, they need to know where they can use it.
MIF mif-core-base.xsd\Annotations\appInfo\staticExample

Ballot Comment

Requirement Feedback about an artifact or portion of an artifact received in response to a formal review of an artifact (i.e. a ballot) needs to be associated with that artifact or portion.
Rationale Having comments directly associated with an artifact simplifies review by committees. It also allows subsequent versions of the ballot to be published showing both the comments and resolution. In addition, large numbers of ballot comments about a particular section may indicate contention or lack of stability which is useful information for implementers.
MIF Issue

The HL7 ballot process does not yet allow direct association or embedding of ballot comments within the artifact they correspond to

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


Requirement There is a need to cross-link ballot comments applying to a particular artifact or portion of an artifact to the overall ballot submission they are linked to
Rationale Ballot submissions are managed as a single "vote" on an overall artifact. The individual comments need to be resolved before the overall vote can be withdrawn. A significant amount of metadata such as vote, voter name, contact information, organization, etc. is captured at the "submission" level and needs to be linked to the individual comments.
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment\@submissionId


Requirement When capturing a ballot comment there's sometimes a need to capture the location "within" an artifact or artifact portion that a comment applies to
Rationale Some artifacts or artifact sections can be extremely long spanning multiple, or (for documents) even 100s of pages. It's important when considering a ballot comment to know exactly where within the artifact it applies
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment\@location


Requirement Every ballot comment must identify the "type" of comment associated with it.
Rationale The type of comment is essential to the ballot resolution process as different comment types have different expectations on resolution processes and rules on what the overall vote can be
Methodology HL7 defines the following "types" of comments:
  • Affirmative - Comment: Vote is in favour of adoption of the balloted item, with a general comment about the comment that does not require any change or answer
  • Affirmative - Typo: Vote is in favour of adoption of the balloted item, though spelling or grammar error that doesn not affect semantic needs to be
  • Affirmative - Suggestion: The voter is recommending a change to the content, but they are in favour of adoption of the balloted item regardless of whether the change is made.
  • Affirmative - Question: The voter has a question with respect to the content, however they are in favour of adoption of the balloted item regardless of whether or how the question is answered.
  • Negative - Minor: Vote is opposed to the adoption of the balloted item, with a need for minor changes in the item needed to resolve the negative.
  • Negative - Major: Vote is opposed to the adoption of the balloted item, with a need for significant changes or complete redevelopment of the item needed to resolve the negative.
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment\@commentType


Requirement For some ballot comments there's a need to capture the source text that the comment is about
Rationale There's not necessarily always a specific "location" that's referencable. Instead you need to copy the specific line of text the comment is about. This is particularly useful when identifying a proposed replacement.
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment\existingContent


Requirement For some comments, there's a need to capture the proposed new text
Rationale Often when a ballot comment is submitted there's a suggestion of "change the text to X" or "add the following sentence". There needs to be a place to capture this information.
MIF mif-core-base.xsd\Annotations\appInfo\ballotComment\proposedContent


Requirement For each ballot comment, there's a need to capture the resolution of that comment
Rationale HL7 process requires capturing a code for the resolution, the date of the resolution, the details of the resolution and the vote of the committee making the resolution (affirmatives, negatives and abstentions). This is needed for HL7 administrative processes and so that voters can see how their comments have been dealt with.
MIF
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\@resolution
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\@resolutionDate
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\resolutionComments
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\vote


Requirement For each resolution, there's a need to capture who is responsible for implementing the agreed solution and who actually implements it as well as when the change is made
Rationale These attributes help to ensure that agreed resolutions are actually implemented and maintain accountability for the agreed change.
MIF
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\@implementedDate
  • mif-core-base.xsd\Annotations\appInfo\ballotComment\resolution\@implementingPerson

Change Request

Requirement There's a need to capture information about how proposed changes to an artifact or set of artifacts will impact the individual components of a change.
Rationale Once artifacts have been approved, there's often a need for revisions or enhancements. Tracking these proposed changes as well as the estimates associated with them is important
MIF Issue

This was proposed by the NHS but it's not clear whether this annotation is currently used by any tool or process yet or what the timeframe is for taking advantage of it.

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


Requirement Each change request may require a unique id
Rationale Change requests to individual artifacts are often linked to a larger change request. An identifier allows this linkage. It also maintains a linkage between paper processes and the electronic representation of the artifact.
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\@changeRequestId


Requirement There is a need to identify the status of a change request
Rationale Knowing whether a change is proposed, approved, rejected or applied is key in evaluating the change request, filtering the artifact to expose change requests at different levels, and even determining whether the change request should be exposed when publishing
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\@status


Requirement Change requests need to be able to identify whether they are considered 'substantive' or not
Rationale HL7 methodology requires that substantive changes be subject to stricter review than changes that are "non-substantive"
Methodology 'Substantive' is defined in its own ballot document within HL7, however the primary criteria in determining whether a change is substantive is "would this change have a material impact on an existing implementation?"
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\@isSubstantiveChange


Requirement Change requests need to be able to identify whether they are considered 'backward compatible' or not
Rationale Backward compatibility is a key consideration in making changes. Generally non-backward compatible changes require creating a new artifact and deprecating the old one.
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\@isBackwardCompatibleChange


Requirement There is a need to be able to refer to a particular location within an artifact that a given change request applies to
Rationale Some artifacts or artifact sections can be extremely long spanning multiple, or (for documents) even 100s of pages. It's important when considering a change request to know exactly where within the artifact it applies
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\@location


Requirement For some changes, there's a need to know when it's desired to have the change made by
Rationale This information can affect many things - whether the change request should be exposed in a publication, when the request needs to be considered, cost impacts of the change, etc.
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\???


Requirement For approved changes, there's a need to capture information about the implementation of the change including who did it and when
Rationale This completes the cycle and provides traceability and accountability
MIF
  • mif-core-base.xsd\Annotations\appInfo\changeRequest\@implementedDate
  • mif-core-base.xsd\Annotations\appInfo\changeRequest\@implementingPersonName


Requirement When resolving a change request, there's often a need to capture descriptive information about the resolution
Rationale This could be reason for rejection, details of the planned implementation, adjustments to the request, etc.
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\resolution


Requirement Any change request may have associated estimate information
Rationale There's often a need to attach a cost in hours, dollars or both to a given change, possibly with qualifying text about assumptions and unknowns.
MIF mif-core-base.xsd\Annotations\appInfo\changeRequest\estimate

Deprecation Information

Requirement There's a need to capture information about the deprecation of an artifact or component of an artifact
Rationale Deprecation is usually accompanied by a reason for the deprecation and recommendations for how the requirement previously met by the deprecated element should be met going forward
MIF mif-core-base.xsd\Annotations\appInfo\deprecationInfo
OMG Mapping Add Stereotype Element


Requirement When capturing deprecation information, it's often useful to know in what version the deprecation is first effective.
Rationale HL7 has rules allowing deprecated elements to be removed from a specification after they've been deprecated for two consecutive publications.
MIF mif-core-base.xsd\Annotations\appInfo\deprecationInfo\@deprecatedEffectiveVersion
OMG Mapping Add tag Element