Requirements-Metadata

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