Artifact Domain Artifact Definition

Return to Artifact List

Domain Artifacts

Lloyd and I settled on title above, but on further rumination, I would prefer:

• Domain Artifact Grouper or
• Domain Artifact Package or
• Domain Artifact Collection

I do not like Artifact Domain (the original) as it suggests the "domain of all artifacts" rather than "all artifacts in a domain", and while Domain Artifacts (as at present) is "correct" it always sounds to my ear like an incomplete title.

Definition and Purpose

Groups all of the artifacts defined by a particular HL7 functional domain within a particular namespace realm. The purpose of this "grouper" artifact is to collect or package the content defined by Work Groups or projects for a particular domain.

Domain

From the V3 Glossary:

Core Glossary:

1. A particular area of interest. For example, the domain for HL7 is healthcare.

2. The set of possible values of a data type , attribute, or data type component. See also vocabulary domain .

3. A special interest group within HL7, such as Pharmacy, Laboratory, or Patient Administration.

As used here, a domain is definition #3, as a qualification of definition #1.

Namespace Realm

From the "description" of the HL7Realm code system:

... concepts representing ... Namespace Realms (used to help ensure unique identification of HL7 artifacts). This code system is partitioned into three sections: Affiliate realms, Binding realms and Namespace realms. All affiliate realm codes may automatically be used as both binding realms and namespace realms...

SAIF Matrix Location

This artifact is "Level-independent" because it is designed to collect all artifacts from a particular domain and realm, regardless of which project or at which level they exist.

Row(s)

• Conceptual (CIM)
• Logical (PIM)
• Implementable (PSM)

Column(s)

• Enterprise/Business
• Information
• Computational
• Engineering
• Technical

Audience

Health Care Information Technology (IT) Audiences:

• System designers and architects
• System purchasers
• Programmers/implementers
• System vendor management

Applicability

By definition, each domain in HL7 that is participating in SAIF will have one of these artifacts in the "universal" namespace realm. However, it is likely that this artifact will never be instantiated. Absent instantiation, it exists as the logical union of "All of the defined artifacts whose defined within this domain at the universal level."

Moreover, there will also be an artifact of this type for every non-universal namespace realm in which definitional artifacts for this domain are being created.

An "incomplete" variant of this artifact may be assembled (instantiated) for a particular purpose, such as balloting or publication.

Rationale: Domain Artifacts is the sole vehicle available for assembling a package of artifacts created for a particular domain. A package of this type "exists logically" whether or not an instance is every created.

Requirements, Relationships and Content

1. Provide a vehicle (grouper) that includes all of the artifact "output" for a particular HL7 [#Domain|domain] and namespace realm.
   1. RationaleA domain is a grouping of activity used by HL7 to help manage the development of standards and their component artifacts. Domain activity occurs within a particular namespace realm. Such a domain requires a vehicle by which to refer to its output.
2. Provide an artifact that that includes a defined sub-set of the artifacts defined for a particular HL7 [#Domain|domain] and namespace realm.
   1. RationaleThe acts of publishing and distributing HL7 defined artifacts requires the ability to define and assemble a sub-set of all artifacts for a particular domain, such as "those artifacts that are required for Normative Edition 2012."

Relationships and traceability

• If an instance is not complete and is defined for a particular domain/realm combination, then that instance will be a subset of the complete instance of Domain Artifacts for the same definition.
  • Rationale Each constrained instance of Domain Artifacts is a subset of one or more less constrained instances.

Any artifact that is defined in a particular domain/realm combination is contained in an instance of this artifact type. Only only the following artifact types will not hold this relationship:

• Domain Artifacts (these relate as subs-sets, not as containment)
• Reference Information Model
• Abstract Data Types
• Vocabulary Model (and its sub-artifacts)
  • Concept Domains
  • Code System
  • Code System Supplement
  • Code Translations
  • Value Set
  • Context Binding
• Interface Model
• Structures Implementation Technology Specification
• Data Types Implementation Technology Specification

Content

• Identifier set - data elements specifying the HL7 functional domain (required) and namespace realm (required) that define this instance
  • Indicator that collection is complete, and, if not, an optional designator of the intended sub-set.
• Contents - All of the element types that are defined within domains. Excluded artifact types are listed under Relationships and traceability, above.

Artifact Technology

At its highest level, the Domain Artifacts instance for a given domain and namespace realm are created as an abstraction the day the domain itself is defined for that real,. Instantiations of this artifact type will be created as a file that conforms to the HL7 Model Interchange Format (MIF).

The underlying technology is:

• Artifacts will be maintained in some form of "repository"
  • Current design content for universal specifications is maintained in SVN on the HL7 Gforge site
    • Current practice maintains directory structures intended to hold the full content for each domain.
• Contained artifacts will be retrievable by instituting a query (or equivalent) or defining a manifest for a particular sub-set
  • Current V3 Publishing Tools use a combination of:
    • ANT scripts to control the processes,

    • Publication Databases (Access) to both define subsets of Domain Artifacts and to define specific artifacts,

    • XSLT transforms to define/determine constraints, execute queries and build manifests

    • XML editors to define packages and content that are not covered by the above tools.

Rationale

• The whole of the HL7 specification management and publication process is based on the notion of producing "processable" content files in MIF that can be used to publish the ballot and as a resource for implementers. The definition of "Domain Artifacts" sub-sets is central to this process, and the underlying technology defined is the engine that runs this.
• The objective of the evolution of these tools is to move to an open platform dependent (Java). This is a work in progress. With the exception of the Publication Database and RMIM Designer, the rest of these tools have in recent years moved to this platform.

Alternatives

Proprietary tools

• Hl7 is working to extract itself from dependency on tools (Access and Visio) whose development paths do not necessarily coincide with ours, and which run on a limited, albeit ubiquitous, operating environment.

Content Constraints

1. In the MIF file representations, artifacts of this type SHALL be identified by the following elements:

   • Root-kind identifier = DEFN (definition); (required) specifies that this is an assembly of defined artifacts

   • Domain identifier - <domainCode> (domain); (required) (like "PA") - the formally adopted identifier of that domain, as defined in Code System Hl7PublishingDomain

   • Namespace Realm identifier - <realmCode> (realm); (required) (like "UV for universal realm) - the formally adopted designator of the realm responsible for these definitions, as defined under code NamespaceRealms in code system HL7Realm.

   1. Rationale: These three elements are also part of the identifiers for every defined artifact. Thus once this package has been defined, its contents are all artifacts anywhere that have the same two (if realm is omitted) or three values for these identifier elements
2. In the MIF file representations this artifact has two further attributes relevant to this artifact type:

   • Is complete indicator - <Boolean>; (required) designates whether or not the instance is a complete collection of the content defined by the identifier elements listed above.

   • Label for subset - <string>; (optional) can be valued when the "is complete indicator" is 'false' to indicate the purpose for the subset. Examples might be designations indicating which ballot or Normative Edition this subset is used for. Some other rule

   1. Rationale: The most common use for sub-sets is to indicate content used for a particular ballot or Normative Edition. These packages are distributed widely and it is beneficial to carry an indicator of their source.

Publishing Representation(s)

This instances of this artifact and its sub-set are at the heart of defining and managing the overall HL7 publication process. As such, they have a number of related representations:

1. Domain Table of Contents - each domain has a table of contents (TOC) that lays out the elements (artifact types in the Domain Artifacts) that are included. Internally, there are numerous sub-TOCs that list all of the individual artifacts for a particular domain and its topics.
   1. Rationale: Each artifact in the domain represents a point of interest - an item for a voter to review or for an implementer to implement. Therefore, these are listed and linked in the various TOCs in the domain.
2. Manifests - A manifest for each domain is published (both as text and HTML files). These manifests start with the files that represent or document each of the Artifacts in the domain. The content of the manifest is, currently, more than just the artifact definitions as it includes supporting graphics and the like.
   1. Rationale: The contents of this artifact and its related documentation define the complete set of files needed for publishing and distributing the domain.
3. MIF representation - A single MIF file of this artifact type is created for every published domain. It is a subset of the total domain artifacts as it references (supplements) but does not include the definition of the information models.
   1. Rationale: This generated artifact is, in fact, an instantiation of this artifact type.
4. Source files - The domain artifacts collection for a particular domain is used to assemble the "source files" that were used to construct and publish the domain.
   1. Rationale: This represents an instantiation of the domain artifacts in a file archive (zip)_.

Publishing Constraints

1. At present, the tooling that supports artifact definition and publishing limits the artifact definition content that is in the appropriate MIF format for inclusion in an instance of this artifact type. Among the elements that are incomplete are:

   • Information models (SIMs) Are represented in MIF format, but lack graphics content in the MIF file. Hence the graphics are carried separately.
     • Even if the information model graphic content were carried solely in the MIF file, we currently lack rendering capability to use this content to create PNG files and clickable overlays.
   • We lack a full WYSWIG editor for the XML-editing (MIF creation) environment, and therefore cannot include graphics in the other text artifact definitions, either.

   1. Rationale: That is the state of tool conversion.
2. Currently, the artifact definitions MIF files are created as a by-product of publishing, late in the stage. Therefore they do nott yet "drive the publishing process, as they should.
   1. Rationale: That is the state of tool conversion.

Tooling Considerations

1. Nice-to-have|Required: Complete integration of this artifact type into the publishing process. We are getting there incrementally, but have noit fully achieved it.
   1. Rationale: This is the primary intended functional role for this artifact type in HL7.
2. Nice-to-have|Required: Conversion of RMIM Designer and Publication data bases to MIF-based tools. Both steps are planned and somewhat "in progress", but will not be completed in 2011, and probably not in 2012.
   1. Rationale: This is the "strategic" plan for HL7 Tooling.