Difference between revisions of "Requirements-Metadata"
(New page: {{V3 Methodology Requirements}} 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 compo...) |
(Update of some requirements with OMG Mappings) |
||
(4 intermediate revisions by one other user not shown) | |||
Line 16: | Line 16: | ||
|- | |- | ||
| ''MIF'' | | ''MIF'' | ||
− | + | | mif-core-base.xsd/Package/packageLocation | |
− | + | |- | |
− | + | | ''OMG Mapping'' | |
+ | | {{OMG-MIF-In MOF}} 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. | ||
|} | |} | ||
Line 30: | Line 31: | ||
|- | |- | ||
| ''MIF'' | | ''MIF'' | ||
− | | mif-core-base.xsd/ | + | | mif-core-base.xsd/Package/@title |
+ | |- | ||
+ | | ''OMG Mapping'' | ||
+ | | {{OMG-MIF-HL7 Profile}} 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. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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-MIF-In MOF}} 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. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{OMG-MIF-Not Supported}} 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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{OMG-MIF-In MOF}} XMI has elements for this purpose, though they are not used consistently by all tools. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{OMG-MIF-HL7 Profile}} 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. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{OMG-MIF-HL7 Profile}} 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. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{OMG-MIF-HL7 Profile}} 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. | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{MIF Not Used}} | ||
+ | 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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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'' | ||
+ | | {{MIF Not Used}} | ||
+ | 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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
+ | |} | ||
+ | |||
+ | |||
+ | {| border="2" cellspacing="0" cellpadding="3" width="600" | ||
+ | | '''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 | ||
|} | |} |
Latest revision as of 19:19, 7 July 2010
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 |
|
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 |
|
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 |
|
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 |