Skip to end of metadata
Go to start of metadata

Submitter: John Roberts for the TSC

Issue: The TSC task force assigned to update the current ballot/document naming convention [GOM §12.02] has completed its task.  GOM 20180426 Final-naming changes 20181105BNTF is submitted citing appropriate revisions to the GOM.

Analysis

Notes:

  • Discussed 2019-07-10 - deferred to 1909 cycle

The document submitted is equally applicable to the HL7 ER.  Although there is some notation to that affect, care must be taken to differentiate the two.  For example, §12.02.02 Ballot Level in the proposal identifies the ER change as Normative or Reaffirmation.  However, Reaffirmation is a type of Comment ballot used to reaffirm the status of a normative standard.  Perhaps this was intended to be Recirculation?  Further, the examples presented will be distributed to the appropriate documents: Normative to the ER, all others to the GOM.

RC1909 Analysis

The TSC document found at Proposed GOM Changes Document will be applied as revisions to the GOM and HL7 ER.

While the revisions are virtually verbatim from the TSC document with some paragraphing added for clarity, there are a few minor deviations.

"Reaffirmation" is not a ballot level, rather it is a type of Comment ballot.  Thus, the optional literal in the GOM naming structure.  By the same token, we have the optional literal "Recirculation" in the Normative ballot construct.

Given the new structure we only need the ballot name construct section in the ER as the Specification Name was established during the initial review balloting under the GOM.

Which raises the point that Ballot Level is not applicable to the ER, it only deals with Normative ballots.  Therefore, "Normative" becomes a literal.  Does it need to be a required literal or are we good as shown? 

One other point, the TSC revision consistently refers to a “Comment” ballot.  However, GOM §13.03 cites a “Comment-only” ballot.  Should we change the TSC reference or initiate a new issue to revise GOM §13.03 to read Comment Ballot?

Proposed Revision

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 the 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 – specifications and ballots.  All ballots must be associated with a single target specification release, but a single specification release may be vetted by multiple ballots, whether part of the same ballot cycle or separate cycles.  Ballot names will always identify the 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 notation of {required} or [optional] with literals expressed in bold italics.

STRUCTURE

Comments

[Reaffirmation of]


{Organization Identifier}


One or more of the following 3 line items required

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

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

[Product Type:] [{Product Name}] [Release [{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

12.02.01.02 Family and Subfamily Name

The standard family names are Version 2.x (V2.x); 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 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 specification. 

It is generally expressed as a version number with the syntax {major}.{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.0304 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.

12.02.01.0405 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 (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.0507 Ballot Level

Ballot level information may be provided as metadata distinct from the name, but shall not be part of the specification 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.0608 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, Release 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), Release 1 (1st Informative Ballot) PI ID 915

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

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

HL7 Version 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 Version 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 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 specification publication.

12.02.02.03 Qualifier

Qualifiers are 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 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 specification.

12.02.02.04 Ballot Level

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

12.02.02.05 Examples

2018-May HL7 FHIRPath R1: Comment ballot

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

HL7 EHR-System Usability Conformance Criteria, R1 Comment ballot

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

HL7 Business Architecture Model (BAM), R1 Informative ballot

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

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

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

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

12.02.0203 Approving HL7 Ballot and Protocol Specification Names

HL7 ER

02.01.01 Constructing Normative Ballot and Protocol Specification Names

[The following naming convention was put through a pilot process involving several products and ballot cycles during 2014 and 2015 and is applicable to all product families effective with the January 2016 update to the HL7 ER. Iterations of normative specifications prior to this update may not conform to this convention.]

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.

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

STRUCTURE

Comments

[Reaffirmation of]


{Organization Identifier}


{

One or more of the following 3 line items required

[Family Name] [Product Type] [Release [Release Number]] :

[Sub-family Name] [Product Type] [Release [Release Number]] :

[Product Name] [Release [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

{Ballot Cycle}


{Specification Name}


[ - Qualifier]


: Normative


[Recirculation]


ballot


02.01.01.01 Organizational Identifier Ballot Cycle

The Organizational Identifier shall be:

ANSI/HL7 indicating an HL7 document that is an ANSI-accredited normative standard

HL7 indicating an HL7 document other than an ANSI-accredited normative standard

HL7/Other [such as NCPDP] indicating an HL7 document published in conjunction with another organization

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.

02.01.01.02 Family and Subfamily Specification Name

The standard family names are Version 2.x (V2.x); 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 Resources (FHIR® is the preferred designation); where a document includes reference to two or more family names it may be identified as a Cross Paradigm Specification. Subfamily names are specific to a given family and are not further defined in this document.

The name for the specification established during the review ballot process; including expected release numbers, edition numbers, etc.  The specification name is the same for all ballots targeting the same specification publication.

02.01.01.03 Product Type Qualifier

Product types are defined as Specification or Standard; Domain Analysis Model (DAM);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.

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 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 specification.

02.01.01.04 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 (NIB).

02.01.01.0504 Examples

[NOTE: Hyperlinks illustrated but not included]

HL7 Version 2.8.2 Messaging Standard, Release 1 (2nd Normative Ballot) PI ID 1133

HL7 Version 3 Standard: Regulated Studies; CDISC Content to Message – Study Participation, Release 1 (2nd Normative Ballot) PI ID 205

HL7 Version 3 Standard: Patient Administration; Patient Encounter, Release 1 (1st Normative Ballot) PI ID 1029

HL7 CDA R2 Implementation Guide: Emergency Medical Services; Patient Care Report, Release 2 (1st Normative Ballot) PI ID 677

HL7 Service Functional Model: Care Coordination Services (CCS), Release 1 (1st Normative Ballot) PI ID 924

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

2018-May HL7 FHIR® R4 - Patient: Normative ballot

2018-May HL7 CDA® R2.1: Normative Recirculation ballot

02.01.01.0605 Approving Normative Ballot and Protocol Specification Names

Normative ballot and protocol specification names shall be approved by the TSC.  In the case of ballots, during the Notice of Intent to Ballot (NIB) process.  In the case of Likewise, protocol specification names shall be approved during the review and approval process for the Publication Request Template.


  • No labels