CORE Rule Versioning

[chowsanthony]

Document Information

Version	Date	Status
1	June 13, 2023	Draft

Effective Date

To be determined.

Target Audience

1. Rule Author

Introduction

Each CORE rule must include a version identifier ($.Core.Version) and a status identifier ($.Core.Status) in the rule schema. These elements together provide the complete status of a rule. For instance, a rule with the identifier CORE-09988 and version 1, in a draft state, would be represented as:

Core:
  Id: CORE-099988
  Version: '1'
  Status: 'Draft'

Assumptions

• The Rule Editor automatically updates the status identifier to 'Published' when a Rule Author presses the Publish button.
• A CORE Rule version is represented as a whole number, and the rule schema expects it to be formatted as a text string.
• A new CORE rule always starts with a version number of '1'.
• Each new version is an increment of 1 from the previous value, starting with '1', followed by '2', '3', and so on.
• When any conformance detail in a rule changes, it does not result in a new version of the same rule. Instead, it becomes a new CORE rule.
• CORE rules may support multiple rule sources, such as different versions of Implementation Guides, regulatory authorities, and foundational standards. To consolidate these sources into a single CORE rule, we use Authorities, referenced as $.Authorities in the rule schema.
• Cosmetic metadata refer to these attributes in the rule schema: Description ($.Description), and Message ($.Outcome.Message), Output Variables ($.Outcome.Output Variables).

Purpose

This document describes how a Rule Author handle the version identifier in each of the scenario described below.

Out of Scope

These areas are outside the scope for this document:

• Change control process for CORE Rule.
• Rule schema updates and related backward compatibility concerns.
• System audit trails.

TODO

• There are a few entries in the SDTMIG Conformance Rules v2 that were drafted but never released. Let's discuss how this scenario should be handled.
• Let's confirm whether we need to add a new attribute in the rule schema to function similarly to the "Revision History" column in the SDTMIG Conformance Rules v2. This column often contains reasons for changes made to the rules.
• Determine an effective date for this set of instructions.

Scenario: Brand new CORE rule

A Rule Author initiates a new CORE rule by setting the version identifier to '1' and the status to 'Draft'. After successfully passing the unit test, the Rule Author publishes the rule using the Rule Editor. At this stage, the Rule Editor automatically updates the status to 'Published'.

stateDiagram-v2
    new: New Rule
    unitTest: Unit Test
    publish: Publish Rule
    version1a: Version#58; '1'
    version1b: Version#58; '1'
    satutusDraft: Status#58; 'Draft'
    statusPublished: Status#58; 'Published'

    [*] --> new
    new --> unitTest
    unitTest --> publish: success
    state new {
        [*] --> version1a : set
        version1a --> satutusDraft : set
        satutusDraft --> [*]
    }
    
    state publish {
        [*] --> version1b : keep
        version1b --> statusPublished : auto update
        statusPublished --> [*]
    }

Loading

Scenario: Retiring published CORE rules

A published CORE rule may become retired due to various reasons. In such cases, the Rule Author can update the status identifier of the affected CORE rule version from 'Published' to 'Retired'.

stateDiagram-v2
    existing: Rule to Be Retired
    versionN: Version#58; N
    statusPublished: Status#58; 'Published'
    satutusRetired: Status#58; 'Retired'

    [*] --> existing

    state existing {
        [*] --> versionN : keep
        versionN --> statusPublished : update from
        statusPublished --> satutusRetired : to
        satutusRetired --> [*]
    }

Loading

Scenario: Correct rule logic

A Rule Author can update a CORE rule to correct flawed rule logic through two main steps. First, the impacted CORE rule's status is changed to 'Retired'. Then, a new version of the same CORE rule ID is created, with updated rule logic that undergoes unit testing and publication. The retired and newly created versions are distinct objects in the Rule Editor.

stateDiagram-v2
    existing: Existing Rule
    updated: Updated Rule
    unitTest: Unit Test
    publish: Publish Rule
    versionN: Version#58; N
    versionN1a: Version#58; N+1
    versionN1b: Version#58; N+1
    satutusRetired: Status#58; 'Retired'
    satutusDraft: Status#58; 'Draft'
    statusPublisheda: Status#58; 'Published'
    statusPublishedb: Status#58; 'Published'

    [*] --> existing
    existing --> updated
    updated --> unitTest
    unitTest --> publish: success

    state existing {
        [*] --> versionN : keep
        versionN --> statusPublisheda : update from
        statusPublisheda --> satutusRetired : to
        satutusRetired --> [*]
    }

    state updated {
        [*] --> versionN1a : set
        versionN1a --> satutusDraft : set
        satutusDraft --> [*]
    }
    
    state publish {
        [*] --> versionN1b : keep
        versionN1b --> statusPublishedb : auto update
        statusPublishedb --> [*]
    }

Loading

Scenario: Append additional compatible rule sources to a published CORE rule

When an additional rule source is compatible with a published CORE rule, we aim to reuse the existing rule logic. The Rule Author can update the corresponding rule without creating a new version, and no unit test is required in this scenario.

stateDiagram-v2
    existing: Reusable Rule
    versionN: Version#58; N
    statusPublished: Status#58; 'Published'
    authorities: Authorities#58;

    [*] --> existing

    state existing {
        [*] --> versionN : keep
        versionN --> statusPublished : keep
        statusPublished --> authorities : append
        authorities --> [*]
    }

Loading

Scenario: Updates needed for cosmetic metadata

Changes to cosmetic metadata do not warrant a new version of the same CORE rule.

stateDiagram-v2
    existing: Existing Rule
    versionN: Version#58; N
    statusPublished: Status#58; 'Published'
    cosmeticAttributes: Description#58;\nOutcome#58;

    [*] --> existing

    state existing {
        [*] --> versionN : keep
        versionN --> statusPublished : keep
        statusPublished --> cosmeticAttributes : update
        cosmeticAttributes --> [*]
    }

Loading

[chowsanthony]

Update Scenario: Append additional compatible rule sources to a published CORE rule to also include updating cited guidance from the source.

[chowsanthony]

Does changing scope, e.g., additional classes or domains, require a new version? Per CROG, it requires a new version of the same rule, not a new rule with a different rule ID.

Outstanding question: Do we create a new CORE rule or up-version it?

[chowsanthony]

For CORE, we will write a new rule. A different Core Rule Id will be assigned by the system.

[chowsanthony]

I added an effective date section (marked TBD) following our live discussion about the need to decide when we begin practicing this set of instructions.

[chowsanthony]

When we make minor changes to a Core rule, such as those "cosmetic" attributes, do we want to explicitly indicate it in the yaml file? For example, from "Version: 1" to "Version: 1.1".

[chowsanthony]

Alternate suggestion: Add a Revision attribute. E.g.,

Version: '1'
Revision: '1'
Status: 'Draft'
Reason: 'some text'

Reason is a conditional attribute. It is not required when drafting. It should be required when publishing a Core rule.

If we can automate the tracking of revisions similar to how Confluence wiki's page history, all the better.