Commitment Discount {Quantity,Unit} - Consistency review edits

[cnharris10]

Adds correction-based logic and reduces duplication of clauses

[ijurica]

Issues to be addressed in CommitemntQuantity column:

• Specify that even in the case of corrections, these two columns can only contain values if CommitmentDiscountId is not null
• Specify that corrections are expected/allowed for purchases as well.
• Specify that, if CommitmentDiscountId is not null, the following applies:
  • MUST NOT be null and MUST be positive in case of regular charges
  • MAY be null or any decimal value in case of corrections
  • MUST be null in all other cases

@cnharris10 @udam-f2 I believe OPTION B more clearly addresses the idea specified in the 3rd requirement

---

Question: Is CommitmentDiscountId restricted to only Purchase and Usage, or should we also expect it in the case of Adjustment, Credit, or Tax?

---

OPTION A: Min. updates

The CommitmentDiscountQuantity column adheres to the following requirements:

• CommitmentDiscountQuantity MUST be present in a FOCUS dataset when the provider supports commitment discounts.
• CommitmentDiscountQuantity MUST be of type Decimal and MUST conform to Numeric Format requirements.
• CommitmentDiscountQuantity MAY be null or any valid decimal value if CommitmentDiscountId is not null and ChargeClass is "Correction".

In cases where the ChargeCategory is "Purchase" and CommitmentDiscountId is not null, the following applies:

• When ChargeFrequency is "One-Time", and CommitmentDiscountId is not null, CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits, paid fully or partially upfront, that is eligible for consumption over the commitment discount's term.
• When ChargeFrequency is "Recurring", and CommitmentDiscountId is not null, CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits that is eligible for consumption for each charge period that corresponds with the purchase.

In cases where the ChargeCategory is "Usage", CommitmentDiscountId is not null, and ChargeClass is not "Correction", the following applies:

• When CommitmentDiscountStatus is "Used", CommitmentDiscountQuantity MUST be the positive, metered quantity of CommitmentDiscountUnits that is consumed over the row's charge period.
• When CommitmentDiscountStatus is "Unused", CommitmentDiscountQuantity MUST be the remaining, positive, unused quantity of CommitmentDiscountUnits for the row's charge period.

CommitmentDiscountQuantity MUST be null for all other ChargeCategory values.

OPTION B: Includes reordering of bullets for readability

The CommitmentDiscountQuantity column adheres to the following requirements:

• CommitmentDiscountQuantity MUST be present in a FOCUS dataset when the provider supports commitment discounts.
• CommitmentDiscountQuantity MUST be of type Decimal and MUST conform to Numeric Format requirements.
• If ChargeCategory is "Usage" or "Purchase", CommitmentDiscountId is not null, and ChargeClass is not "Correction", the following applies:
  • CommitmentDiscountQuantity MUST NOT be null and MUST be a valid positive decimal value.
  • When ChargeCategory is "Purchase" and ChargeFrequency is "One-Time", CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits, paid fully or partially upfront, that is eligible for consumption over the commitment discount's term.
  • When ChargeCategory is "Purchase" and ChargeFrequency is "Recurring", CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits that is eligible for consumption for each charge period that corresponds with the purchase.
  • When ChargeCategory is "Usage" and CommitmentDiscountStatus is "Used", CommitmentDiscountQuantity MUST be the positive, metered quantity of CommitmentDiscountUnits that is consumed over the row's charge period.
  • When ChargeCategory is "Usage" and CommitmentDiscountStatus is "Unused", CommitmentDiscountQuantity MUST be the remaining, positive, unused quantity of CommitmentDiscountUnits for the row's charge period.
• If ChargeCategory is "Usage" or "Purchase", CommitmentDiscountId is not null, and ChargeClass is "Correction", CommitmentDiscountQuantity MAY be null or any valid decimal value.
• CommitmentDiscountQuantity MUST be null in all other cases.

[cnharris10]

I like Option A for 2 reasons.

1. We've already spent months across a lot of discussion, suggestions, and edits from many contributors for the pr, so I think the consistency review should only focus on the most minor edits to ensure correctness/accuracy/etc that keeps the original approved content, structure, etc.

2. I, personally, prefer the original flow of Option A that starts with general requirements and then goes into specifics around the 2 key scenarios (Purchase, Usage) of the column's purpose.

[jpradocueva]

Action Items from Members' call on Sep 26:

• [TF1- #550] Chris, @cnharris10 to incorporate feedback on nullability and reordering of requirements.

[ijurica]

CommitmentDiscountQuantity OPTION C:

---

This version retains the original flow, with a few updates compared to the original:

• All the requirements are now presented as bullet points and sub-bullets.
• The purchase-related requirement includes an additional condition: ChargeClass is not Correction.
• The newly added bullet regarding correction charges (MAY be null) has been moved to the end of the list, just before the "MUST be null" requirement. I believe this resolves Udam's comment and clarifies the intention.

---

The CommitmentDiscountQuantity column adheres to the following requirements:

• CommitmentDiscountQuantity MUST be present in a FOCUS dataset when the provider supports commitment discounts.
• CommitmentDiscountQuantity MUST be of type Decimal and MUST conform to Numeric Format requirements.
• In cases where the ChargeCategory is "Purchase", CommitmentDiscountId is not null, and ChargeClass is not "Correction", the following applies:
  • When ChargeFrequency is "One-Time", and CommitmentDiscountId is not null, CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits, paid fully or partially upfront, that is eligible for consumption over the commitment discount's term.
  • When ChargeFrequency is "Recurring", and CommitmentDiscountId is not null, CommitmentDiscountQuantity MUST be the positive quantity of CommitmentDiscountUnits that is eligible for consumption for each charge period that corresponds with the purchase.
• In cases where the ChargeCategory is "Usage", CommitmentDiscountId is not null, and ChargeClass is not "Correction", the following applies:
  • When CommitmentDiscountStatus is "Used", CommitmentDiscountQuantity MUST be the positive, metered quantity of CommitmentDiscountUnits that is consumed over the row's charge period.
  • When CommitmentDiscountStatus is "Unused", CommitmentDiscountQuantity MUST be the remaining, positive, unused quantity of CommitmentDiscountUnits for the row's charge period.
• In cases where the ChargeCategory is "Purchase" or "Usage", CommitmentDiscountId is not null, and ChargeClass is "Correction", CommitmentDiscountQuantity MAY be null or any valid decimal value.
• CommitmentDiscountQuantity MUST be null in all other cases.

[ijurica]

CommitmentDiscountUnit

---

Compared to the original, in this version:

• All the requirements presented as bullet points and sub-bullets
• MUST NOT / MAY / MUST be null across various ChargeCategory, commitmentDiscountId, ChargeClass values precisely specified.
• "MUST be the same across all rows" requirement moved to the "CommitmentDiscountUnit is not null" block

---

The CommitmentDiscountUnit column adheres to the following requirements:

• CommitmentDiscountUnit MUST be present in a FOCUS dataset when the provider supports commitment discounts.
• CommitmentDiscountUnit MUST be of type String.
• Units of measure used in CommitmentDiscountUnit SHOULD adhere to the values and format requirements specified in the UnitFormat attribute.
• CommitmentDiscountUnit MUST NOT be null when ChargeCategory is "Purchase" or "Usage", CommitmentDiscountId is not null, and ChargeClass is not "Correction".
• CommitmentDiscountUnit MAY be null when ChargeCategory is "Purchase" or "Usage", CommitmentDiscountId is not null, and ChargeClass is "Correction".
• CommitmentDiscountUnit MUST be null in all other cases.
• In cases where the CommitmentDiscountUnit is not null, the following applies:
  • CommitmentDiscountUnit MUST be the same across all rows having the same CommitmentDiscountId.
  • CommitmentDiscountUnit MUST represent the unit used to measure the commitment discount.
  • When accounting for commitment discount flexibility, the CommitmentDiscountUnit value SHOULD reflect this consideration.

[jpradocueva]

Action Items from TF-1 call on October 1st:

• [TF1-#550 ] Chris, @cnharris10 : Update the quantity units format and validate consistency.

[cnharris10]

Update (10/2/24)

All additional comments shown above were discussed in TF-1 (10/1/24) with the consensus that optimizing for readability will be pushed to 1.x after guidelines are established.

The one action item that came out of the meeting was added and can be seen here

[ijurica]

We’ve specified that

CommitmentDiscountQuantity MAY be null or any valid decimal value if CommitmentDiscountId is not null and ChargeClass is Correction.

However, CommitmentDiscountUnit MUST be null, as we didn’t mention Correction charges for that column.
@cnharris10, I assume that's an oversight?

[jpradocueva]

@cnharris10, @ijurica, can we resolve this issue on time for the Members' Meeting on October 3rd? Let me know if I can be of any assistance. Thanks

[jpradocueva]

@cnharris10 The sentiment of the group is that the changes Irena proposed are okay.

[cnharris10]

@cnharris10 The sentiment of the group is that the changes Irena proposed are okay.

@jpradocueva Just integrated both outstanding comments from @ijurica

Let's move forward with it if we can. Unfortunately, not able to make the call today.

[jpradocueva]

Approved during the Members' call on Oct 3rd.