Requirements-Metadata

From HL7Wiki
Jump to navigation Jump to search

This section lists metadata that is common to all HL7 stand-alone artifacts. In some cases, parts of this metadata also appears on child artifacts or components of artifacts. When this occurs, those artifacts will include a reference to this section.


Requirement All versions of HL7 specifications and stand-alone artifacts must have a unique identifier that permits: human readability, human recognizability and distributed assignment
Rationale Without a unique identifier, HL7 artifacts and their versions cannot be safely referenced by other HL7 artifacts or by other documents (RFPs, conformance claims) which use them. However in order to be useful in publications such as RFPs and within HL7 specifications, those identifiers need to be ones that can be recognized and interpreted by humans. Because HL7 artifacts will be created by a variety of organizations and groups, both within HL7.org and its affiliates as well as by implementers (e.g. templates and conformance profiles), it's essential that the identification scheme make provision for delegation of issuance of identifiers within discrete namespaces.
Methodology HL7 has adopted a "package-based" naming approach for both definitional and published versions of artifacts. This approach uses a hierarchy of packages to identify the type of artifacts within the package, the affiliate or other organizational namespace responsible for the artifact, the healthcare domain associated with the artifact, a unique identifier for the artifact within the context of the above and the version of the artifact.

Not all of these components will be present for all types of artifacts. The specific components, their order, their allowed values and lengths are all defined by HL7.

MIF mif-core-base.xsd/Package/packageLocation
OMG Mapping OMG also uses package-based naming in UML and other MOF-based languages, extended to URIs in the MOF Core and MOF Facility specifications. XMI allows URI-based cross referenceing and provides for arbitrary xmi:uuids.


Requirement Most versions of HL7 specifications and stand-alone artifacts require a descriptive title
Rationale "DEFN=PO=RX=MT=123456=UV=01" is not terribly meaningful to most readers. Therefore a more semantically meaningful label for an artifact is required. This label should ideally be unique but is not subject to the same namespacing requirements as it is used for understanding, not for reference
MIF mif-core-base.xsd/Package/@title
OMG Mapping UML does not have anything built-in apart from a name and a generic Comment capability - which is what most tools use for their element descriptions (though these are more than descriptive titles). A specific Stereotype property should be used for descriptiveTitle.


Requirement Some HL7 specifications and stand-alone artifacts require a globally unique non-HL7-style identifier
Rationale These artifacts may need to be placed in a registry that is not HL7 specific and need a persistent identifier that can be used across multiple such repositories
MIF mif-core-base.xsd/Package/@secondaryId
OMG Mapping OMG also uses package-based naming in UML and other MOF-based languages, extended to URIs in the MOF Core and MOF Facility specifications. XMI allows URI-based cross referenceing and provides for arbitrary xmi:uuids.


Requirement HL7 specifications and stand-alone artifacts must be able to identify the artifacts they supersede or that have superseded them.
Rationale The standards world is dynamic. A specification that exists now may be replaced in a few years by a new version or even a completely different specification, or its requirements may be split across multiple specifications or merged together with other content into a new specification. When looking at a particular specification it's essential to know whether it's current, if it's not current, where to look for more current information and what information you already have that has been made obsolete by this new specification.
MIF
  • mif-core-base.xsd/Package/replaces
  • mif-core-base.xsd/Package/replacedBy
OMG Mapping Though MOF Versioning allows management of different model versions and configurations thereof, it does not provide specific annotative properties to reference replaced/merged elements or generally track changes. Properties could be added to a Profile for this, but most tools would have a problem referencing the specific elements in older versions of the models


Requirement When looking at a particular serialized version of an artifact, it's useful to know information about the software that created that specification, including the time it was persisted, the application responsible for persisting it and any other rendering information
Rationale Tools occasionally have problems and knowing what tool created something when can be useful. It also provides a "non-dangerous" place for a tool to advertise itself.
MIF mif-core-base.xsd/Package/header/renderingInformation
OMG Mapping XMI has elements for this purpose, though they are not used consistently by all tools.


Requirement Artifacts must be capable of expressing legal constraints including copyright information, licensing terms, disclaimers, policies around version management and any similar information
Rationale Artifacts are intellectual property, usage of artifacts may suggest legal responsibility. These and similar legal issues create the need for clear information about the rights and restrictions associated with the use of a particular artifact.
MIF mif-core-base.xsd/Package/header/legalese
OMG Mapping Though XMI has Documentation elements for this purpose, there is no standard mapping to model elements, or anything that could be edited outside the XMI document. Therefore it would be better to define specific Stereotypes for this purpose.


Requirement With many specifications and stand-alone artifacts there's a need to capture information about the group and/or organization responsible for the artifact.
Rationale Knowing responsibility for an artifact can influence the level of comfort an implementer has in using the artifact. It's also a key piece of metadata for searching and cataloging artifacts.
MIF mif-core-base.xsd/Package/header/responsibleGroup
OMG Mapping Though XMI has Documentation elements for this purpose, there is no standard mapping to model elements, or anything that could be edited outside the XMI document. Therefore it would be better to define specific Stereotypes for this purpose.


Requirement Specifications and stand-alone artifacts must be able to capture the contributors to that artifact including such information as name, role, affiliation, contact and other information.
Rationale Attribution is important for recognition, for level of trust in the artifact and to allow for follow-up if there are questions
MIF mif-core-base.xsd/Package/header/contributor
OMG Mapping Though XMI has Documentation elements for this purpose, there is no standard mapping to model elements, or anythign that could be edited outside the XMI document. Therefore it would be better to define specific Stereotypes for this purpose.


Requirement Specifications and stand-alone artifacts need to capture keywords
Rationale Keywords are a common mechanism within catalogs and repositories to allow discovery of a specification or artifact
MIF mif-core-base.xsd/Package/header/subject


Requirement There is a need to flag artifacts with the realms or organizations they're associated with.
Rationale Some artifacts are created with the intention of being used within multiple realms. Thus it's not possible to use only the realm included within the artifact id to determine "associated realm". Because this is a key piece of information for searching and cataloging artifacts, it needs to be captured.
MIF mif-core-base.xsd/Package/header/realmNamespace


Requirement Within a specification or stand-alone artifact there's a need to capture information about the approval status of that artifact
Rationale Reliance on an artifact is significantly changed if an artifact is draft vs. active vs. withdrawn. In addition, HL7 and ANSI rules require approval information when rendering artifacts for publication
MIF mif-core-base.xsd/Package/header/approvalInfo


Requirement Within the approval information for each artifact, there's a need to know the "status" of the artifact.
Rationale Artifacts may go through a variety of approval states. The level of approval indicates the reliability of the artifact and the level of review it's received and the level of review that is currently expected
Methodology
  • Draft: Content that is under development and is not intended to be used.
  • Non-standard - Available for use: Content developed independently by an organization or individual that is declared to be 'usable' but for which there is no present intention to submit through the standards submission and review process.
  • Proposal: Content submitted to a committee for consideration for future inclusion in the standard.
  • Committee Ballot - Normative: Content prepared by a committee and submitted for internal consideration as a normative standard.
  • Committee Ballot - Informative: Content prepared by a committee and submitted for internal consideration as an informative standard.
  • Membership Ballot - Normative: Content prepared by a committee and submitted for membership consideration as a normative standard.
  • Membership Ballot - Informative: Content prepared by a committee and submitted for membership consideration as an informative standard.
  • Membership Ballot - DSTU: Content prepared by a committee and submitted for membership consideration as a draft standard for trial use.
  • Approved Normative Standard: Content that has passed ballot as a normative standard
  • Approved Informative Standard: Content that has passed ballot as a normative standard
  • Approved DSTU: Content that has passed ballot as a draft standard for trial use
  • Affiliate Ballot - Normative: Content that is being presented to an international affiliate for consideration as a realm-specific normative standard
  • Affiliate Ballot - Informative: Content that is being presented to an international affiliate for consideration as a realm-specific informative standard
  • Reference: Content that is not intended to be balloted, but which exists to support other balloted content
  • Approved Affiliate Normative Standard: Content that has passed ballot as a realm-specific normative standard
  • Approved Affiliate Informative Standard: Content that has passed ballot as a realm-specific informative standard
  • Approved Affiliate DSTU: Content that has passed ballot as a realm-specific draft standard for trial use
  • Localized Adaptation: Content that represents an adaption of a implementable balloted material to represent the needs or capabilities of a particular installation.
  • Withdrawn: Content that represents an item that was at one point a normative or informative standard, but was subsequently withdrawn
MIF mif-core-base.xsd/Package/header/approvalInfo/@approvalStatus


Requirement When capturing approval information, the organization doing the approval is needed.
Rationale Artifacts may potentially be approved by multiple bodies. Knowing the organization defines the 'scope' of the approval and may also determine approval processes and the weight or value of the approval.
MIF mif-core-base.xsd/Package/header/approvalInfo/@approvingOrganization


Requirement Where approvals may be subject to multiple stages/ballots, there's a need to capture the "current"/"most recent" stage.
Rationale Knowing "this is a membership ballot" isn't the same as knowing "this is the third membership ballot". Ballot stage also helps understand the relative stability of the content
MIF mif-core-base.xsd/Package/header/approvalInfo/@ballotOccurrence


Requirement There is a need to capture when the current approval stage is expected to be completed or when the most recent approval stage was completed
Rationale Knowing something was normative since September, 2003 is important in knowing the relative "age" of the material and its stability. When an approval process is ongoing, knowing the date when that stage will complete is also important.
MIF mif-core-base.xsd/Package/header/approvalInfo/@approvalDate


Requirement In circumstances where an artifact is withdrawn or is scheduled to be withdrawn, there's a need to capture the date for withdrawal.
Rationale When an artifact is scheduled to be withdrawn, you need to know both the date when it was approved and when it's scheduled to be withdrawn. All HL7 artifacts are automatically scheduled to be withdrawn if not extended.
MIF mif-core-base.xsd/Package/header/approvalInfo/@withdrawalDate


Requirement When artifacts are subjected to vote, there is a need to capture the votes associated with that version of the artifact.
Rationale Votes are a key part of many approval processes. Knowledge of the votes and contents is helpful in understanding the evolution of an artifact and also determines requirements for moving the artifact further along the approval process.
MIF Issue

There currently isn't any support within HL7 tools for integrating ballot comments into the specifications and artifacts voted upon.

MIF mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission


Requirement Each ballot submission needs to be able to be linkable to the individual comments submitted as part of the ballot
Rationale Resolution of all the comments that are part of the ballot are necessary to resolve an overall vote.
MIF mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission/@submissionId


Requirement Information about votes needs to include the individual submitting the vote and possibly who the vote is submitted on behalf of.
Rationale All votes must be attributed to a specific person who can be contacted when performing resolution. In some cases, the "authority to vote" rests with the individuals organization so sometimes it needs to be known as well.
MIF
  • mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission/@submitterOrganization
  • mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission/@submitterName


Requirement When tracking a ballot submission, the vote itself must be captured
Rationale Because without knowing the actual vote (affirmative, negative, abstain), the ballot submission is pretty useless . . .
MIF mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission/@vote


Requirement Ballot submissions may be accompanied by generic comments about the overall submission
Rationale There are often comments about the ballot as a whole, and in some cases, references to other ballot submissions. E.g. "See comments submitted by John Doe"
MIF mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission/voterComments


Requirement There's a need to track the overall resolution of a ballot submission including agreed resolutions, status and effective date of the current status
Rationale This information is needed to identify whether votes have been withdrawn or retracted which in turn influences subsequent approval cycles. This information is also required for groups such as ANSI.
MIF mif-core-base.xsd/Package/header/approvalInfo/ballotSubmission


Requirement When reviewing artifacts and components of them, there's a need to understand how the artifact has changed over time.
Rationale Awareness of changes is important when reviewing new versions (both for approval and for implementation). Also, understanding history of changes provides more context on the current artifact and how it's intended to be used.
MIF Issue

Elements of historyItem are used by many artifacts, but are not used consistently across all. In addition, as we start to move towards using source control, it's not clear that history information (or more specifically, "how much history information") needs to be embedded within the artifact and how much can be derived from source control.

MIF mif-core-base.xsd/Package/historyItem


Requirement When capturing history, there's a need to know when the change was made
Rationale Timestamp is a pretty key piece of information of placing multiple changes in a historical timeline and understanding the evolution of an artifact.
MIF mif-core-base.xsd/Package/historyItem/@id


Requirement When capturing history of an item, there's a need to know who made what change.
Rationale This provides traceability and accountability for the changes made
MIF mif-core-base.xsd/Package/historyItem/@responsiblePersonName


Requirement There's a need to be able to link the changes that happened to multiple components of an artifact or specification so that it's clear they all happened as part of a single version or release.
Rationale It's common for multiple changes to be applied simultaneously. That grouping provides the lowest granularity at which changes can be accessed. I.e. If two changes were applied simultaneously, then it's not possible to refer to a version of an artifact that has one change and not the other.
MIF Issue It's not clear whether this is actually the requirement that drives the 'id' attribute. Is it still actually a requirement or just a historical artifact as a "mechanism" for capturing what changes occurred as part of a particular release.
MIF mif-core-base.xsd/Package/historyItem/@id


Requirement When capturing changes, there's a need to identify whether a given change is considered 'substantive' or not.
Rationale HL7's approval methodology is significantly influenced by the substantivity of a change with substantive changes requiring greater review. In addition, substantive changes tend to be of more interest for those reviewing a specification.
MIF mif-core-base.xsd/Package/historyItem/@isSubstantiveChange


Requirement When capturing that a change occurred, there's a need to know exactly what the change was in "human readable" terms.
Rationale It's often difficult to perform a direct compare of the old and new version and seeing the fine-grained changes doesn't necessarily provide a good sense of what the general characteristic of the change was. E.g. "Fixed spelling errors and grammar" or "Updated names to align with data dictionary"
MIF mif-core-base.xsd/Package/historyItem/description