Page tree

1905002 Revised naming convention GOM

12.02 Publication Naming Convention

A naming convention has several basic objectives:

  • Provide a concise way of identifying a publication in a human-meaningful way Help potential readers determine whether a document is an ANSI-approved standard or other document type
  • Help potential readers t he target user locate a document publication in a hierarchy of documents
  • Help potential readers the target user determine the purpose of a document publication
  • Help potential readers determine the relevance of a document to their need

To meet these objectives, a well-constructed document name should include:

  • The organization(s) releasing the document
  • The family of standards relevant to the document
  • The document type designation
  • A descriptive title
  • The document release identifier

HL7 defines naming rules for two types of publications – protocol specifications and ballots.  All ballots must be associated with a single target protocol specification release, but a single protocol specification release may be vetted by multiple ballots, whether part of the same ballot cycle or separate cycles.  Ballot names will always identify the protocol specification they are associated with.  Ballots will also strive to ensure consistency of naming across artifacts related to the same product families.

12.02.01 Constructing HL7 Ballot and Protocol Specification Names

The full document name shall begin with an organizational identifier followed by family name, product type and release number with a subfamily name, product type and release number, if applicable, then the product name and release number followed by the realm designation, if applicable, and the ballot type and number.  In the case of a reaffirmation ballot the term “Reaffirmation of” shall precede the organization identifier.

There are three variations on naming convention for protocol specifications, all described below.  The first is for naming releases of a product family.  The second is for naming products derived from a product family.  The final syntax is for artifacts that are not part of a product family or that span product families.

The naming construct is described below using a the following notation: of {required}, or [optional], <choice>. with Literals are expressed in bold italics Examples may be found in §12.02.01.08.

STRUCTURE

Comments

[ Reaffirmation of ]

 

{Organization Identifier}

 

<

One or more of the following 3 line items required

[ { Family Name } ] [Product Type] [ R elease [ { Release Number } ]] :

[Sub- { Family Name } ] [ R {Release Number}] [ { Product Type } ] [ Release [Release Number]] : {Product Name}, Edition {Edition Number}

[Product Type:] [ { Product Name } ] [ R elease [ { Release Number } ]]

>

 

[Realm Designation]

See HL7 Version 3 Standard > Vocabulary > HL7 Value Sets > HL7 Realm

The following elements are specific to ballot names and shall not appear in final document names.

[Designation] [Ballot Type] Ballot

Designation shall be 1st, 2nd, etc.

PI ID {Project Insight ID number}

Ballot metadata; ID number shall have hyperlink to Project Insight

12.02.01.01 Organization Identifier

The Organization Identifier shall be:

HL7 indicating a Health Level Seven International document publication

HL7/ [ Other ]” where [Other] is the abbreviated/short name for the other organization, [ such as NCPDP ] , indicating an HL7 document published in conjunction with another organization [WRK1]

12.02.01.02 Family and Subfamily Name

The standard family names are Version 2.x ( V2x ) ; Version 3 ( V3 ) [note: V3 itself does not have a release number, although each of its products typically will] ; Clinical Document Architecture® ( CDA® ) [note: CDA shall be further designated as R1 or R2] ; Electronic Health Records System-Functional Model ( EHRS-FM ) ; Fast Healthcare Interoperability Resource ( FHIR® ) ; Conceptional Model; or DAM .  Where a [WRK2] document includes reference to specification is based on two or more family names it may be identified as a Cross Paradigm Specification the Family Name naming option cannot be used; a stand-alone title shall be used instead .

The Family Name acronym may be used for all specification names, including the base specification.  Specifications shall document the full name as part of the specification text.   In the case of a Standard or Standard for Trial Use (STU) the full family name shall be used; e.g., Fast Healthcare Interoperability Resource or Clinical Document Architecture®.  In lieu of the full family name the appropriate acronym may be used for Implementation Guides, Profiles, and other documentation.

Subfamily names are specific to a given family and are not further defined in this document. 

12.02.01.03 Release Number

The Release Number is a unique identifier for a particular product family or stand-alone primary protocol specification. 

It is generally expressed as a version number with the syntax {major} dot {minor} – e.g. 3.2.  It reflects the number of the final publication of the artifact intended for use by implementers.  It remains the same across all ballots until the specification is published.  The major number can be used alone if there is no minor release.  The release number is not reset when a product transitions from STU to normative or at any other point.  Those STU updates not balloted must be a minor release.

The TSC may approve alternate release number syntaxes – for example the year-based identifiers used for HL7 v3 publications, and the “2.” prefix for V2 publications.  The release number must be specified when naming derived specifications unless the specification applies to multiple releases of the base product family in which case it must be omitted.

12.02.01. 03 04 Product Type

Product types are defined as Specification or Standard; Domain Analysis Model (DAM) ; Conceptual Model; Service Functional Model (SFM) ; Functional Model (FM) ; Functional Profile (FP) ; Implementation Guide (IG) ; Logical Model [note: a Logical Model is not a Cross Paradigm Specification] ; Profile, White Paper, and Guidance [for documents such as a Cookbook or Companion Guide].  The TSC may, at their discretion, declare additional product types. [WRK3]

12.02.01. 04 05 Product Name

The Product Name is specified by the Work Group when they initiate a PSS to create a new or update an existing Protocol Specification; however, the Product Name may be revised upon submission of the Notice of Intent to Ballot ( [WRK4] NIB ) .

If a product is based on higher-level derived artifacts (e.g. an implementation guide based on another implementation guide, a services functional model based on a higher-level model) the product name may include references to one or more of those higher-level artifacts, including their versions.  This should only be done if it is a necessary part of the descriptive name to ensure uniqueness or to ensure implementers understand what the artifact is.  Detailed metadata should be provided in the artifact itself.  All efforts should be made to keep the product name concise and easy to use.

12.02.01.06 Edition Number

The Edition Number is a unique number for the Product Name within the scope of the product family.  The term “Edition” is used to avoid confusion with the “Release” of the product family on which the Edition is based.  The term Edition is used for all artifacts derived from a based product family publication – even if there is a hierarchy of artifacts.  For example, Edition 1 of implementation guide B, might depend on Edition 3.1 of implementation guide A, which in turn depends on R4 of the product family specification.  Edition Numbers follow the same format as the Release Number with respect to major and minor version numbers.

The Edition Number does not reset when a derived publication advances to a newer release of the same product family.  Multiple publications with different release numbers for the base specification and the same edition number and product name are possible if multiple publications are produced with essentially the same content for different releases of the underlying product family.  

12.02.01. 05 07 Ballot Level

Ballot level information may be provided as metadata distinct from the name, but shall not be part of the name.

The Ballot Level defines the type of Review Ballot being undertaken: Informative; STU [note: STU numbering is independent of the normative release level the product may ultimately be assigned]; or Comment-only [note: a Comment-only ballot is not typically numbered given that it is issued for a specific reason, such as reaffirmation, or as a precursor to an Informative or STU ballot].

The TSC has issued specific guidance as to sub-numbering the release number for a STU update.  Please refer to TSC Policy and Guidance to Work Groups on STU Updates vs. STU Ballots .

12.02.01. 06 08 Examples

[NOTE: hyperlinks illustrated but not included]

HL7 FHIRPath R1

HL7 FHIR® R4

HL7 V3 R2019

HL7 CDA® R2.1

HL7 CDA® R2 Implementation Guide: Patient-friendly language for Consent Directives, Release Edition 1 (1st Informative Ballot) PI ID 1130

HL7 EHR-System Usability Conformance Criteria, R elease 1 (Comment-only Ballot) PI ID 995

HL7 FHIR® R2 Implementation Guide Profile : Data Access Framework (DAF), Release Edition 1 (1st STU Ballot) PI ID 1143

HL7 Business Architecture Model (BAM), R elease 1 (1st Informative Ballot) PI ID 915

HL7 Service Functional Model: Care Coordination Service (CCS), R elease 1 (1st STU Ballot) PI ID 924

HL7 V ersion 3 Standard: Biomedical Research Integrated Domain, Release Edition 2 (1st STU Ballot) PI ID 1120

HL7 V ersion 2X R 2.7.1 Implementation Guide: Message Transformations with OASIS Tracking of Emergency Patients (TEP), Release Edition 1 (2nd Informative Ballot) PI ID 970

Reaffirmation of HL7 V ersion 3 Standard: Pharmacovigilance - Individual Case Safety Report, Part 1: The Framework for Adverse Event Reporting, R Edition 2 (1st Normative Ballot) PI ID 1258

All examples shown above reflect ballot names; the ballot designation and Project Insight ID shall not appear in the document name used for publication.

12.02.02 Constructing HL7 Ballot Names

The naming construct is described below using a notation of {required} or [optional] with literals expressed in bold italics .

STRUCTURE

Comments

{Ballot Cycle}

 

{Specification Name}

[ - Qualifier]

: {Ballot Level}

[ Reaffirmation ]

 

ballot

 

12.02.02.01 Ballot Cycle

The “closing month” of the ballot cycle, expressed as YYYY-mmm, which includes this ballot.  Note that the ballot cycle date remains the same for those ballots that have alternate opening dates within the same ballot cycle.

12.02.02.02 Specification Name

The expected name for the protocol specification that will result from the balloting process, as defined in §12.02.01.  This will include expected release numbers, edition numbers, etc.  It will remain the same for all ballots targeting the same protocol specification publication.

12.02.02.03 Qualifier

A Qualifier is a few words identifying the subset of the content in the target publication being reviewed by this ballot.  Qualifiers should only appear for ballots that are limited to and do not include the full scope of the target publication.  Note that the published protocol specification will only include the Specification Name and not any qualifier.  Information about the approval status of the limited subset will be conveyed in metadata of the resulting published protocol specification.

12.02.02.04 Ballot Level

The Ballot Level defines the type of Review Ballot being undertaken: e.g., Comment-only, Informative, or STU.

12.02.02.05 Examples

2018-May HL7 FHIRPath R1: Comment-only ballot

2018-May HL7 CDA® R2 Implementation Guide: Patient-friendly language for Consent Directives, Edition 1 Informative ballot

2018-May HL7 EHR-System Usability Conformance Criteria, R1 Comment-only ballot

2018-May HL7 FHIR® R2 Implementation Guide: Data Access Framework (DAF), Edition 1 STU ballot

2018-May HL7 Business Architecture Model (BAM), R1 Informative ballot

2018-May HL7 Service Functional Model: Care Coordination Service (CCS), R1 STU ballot

2018-May HL7 V3 Standard: Biomedical Research Integrated Domain, Edition 2 STU ballot

2018-May HL7 V2X R2.7.1 Implementation Guide: Message Transformations with OASIS Tracking of Emergency Patients (TEP), Edition 1 Informative ballot

2018-May HL7 V3 Standard: Pharmacovigilance - Individual Case Safety Report, Part 1: The Framework for Adverse Event Reporting, Edition 2 Comment-only Reaffirmation ballot

12.02. 02 03 Approving HL7 Ballot and Protocol Specification Names [WRK5]

 


[WRK1] Does this apply only to Joint IP pubs for an SOU?  Or does it apply to Accelerators?

[WRK2] Are DAMs and Conceptual Models really families?  I don’t think so. EHRS-FM?

[WRK3] Where are the other names posted?  Must GOM be updated if they are?

[WRK4] Can’t it also be revised at Pub Request stage?

[WRK5] Does this mean no changes were made to this section other than number?