Difference between revisions of "Requirements-Metadata"
Line 16: | Line 16: | ||
|- | |- | ||
| ''MIF'' | | ''MIF'' | ||
− | | | + | | mif-core-base.xsd/Package/packageLocation |
− | |||
− | |||
− | |||
|} | |} | ||
Revision as of 16:06, 18 March 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 |
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 |
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 |
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 |
|
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 |
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 |
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 |
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 |
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 |