[FR] Augment requirements for correction-handling scenarios

[Matt-Cowsert]

🧠 Problem Statement

While some correction handling rules have been incorporated into individual columns' normative requirements - primarily within metrics and related unit dimensions - the FOCUS specification lacks a comprehensive, unified framework (i.e., attribute) for managing corrections across all columns. The absence of an overarching correction handling standard may lead to inconsistencies, oversights, and ambiguities in the specification, particularly in multi-dimensional and metric-based data contexts, ultimately leading to misinterpretation and the generation of non-conforming correction records, compromising data integrity, reconciliation, and overall data quality.

To address this, an overarching correction handling attribute should be introduced. Additionally, a review of existing correction handling rules within individual columns' normative requirements is essential to ensure consistency and alignment with this unified approach.

---

🧪 Use Case

• As a FinOps Practitioner, I want a consistent approach to the display of corrections so that I can reconcile my charges within my FOCUS datasets with my provider invoices.
• As a FinOps Practitioner, I want to know how my provider handles corrections for closed billing periods so I can properly allocated charges in a timely manner.
• As a FinOps Practitioner, I want to know what the correction is applying to (vs. one line capturing all corrections), broken down at resource it's applied to, so I can ensure my showback / chargeback workflows are accurate.
• As a FinOps Practitioner, I want to verify which charges/resources/services that the corrections are being applied so I can explain the correction to my organization.

Acceptance Criteria

Data Consistency & Identification:

• Correction records are consistently identifiable across all providers
• Practitioners can distinguish between corrections to closed periods vs. adjustments within current periods
• All metric columns (costs, quantities) behave predictably in correction records to enable accurate summation and reconciliation

Reconciliation Capability:

• Practitioners can reconcile correction records with their provider invoices
• Practitioners can trace corrections to the billing period being corrected
• Correction records contain sufficient dimensional detail to identify what charges/resources/services are being corrected

Attribution & Allocation:

• Practitioners can attribute correction impacts to specific resources or services for chargeback/showback
• Correction records support the same allocation granularity as non-correction charges

Specification Clarity:

• The specification unambiguously defines how correction records must behave across all column types
• Edge cases (corrections to amortized costs, corrections affecting multiple dimensions, aggregate corrections) have clear handling requirements
• Supported Feature documentation describes correction reconciliation workflows with SQL examples

Provider Alignment:

• Correction handling requirements are testable and implementable by data generators
• Common correction scenarios (usage errors, price adjustments, refunds) are explicitly covered

---

Supported Features Alignment

Current State Assessment

[ ] Enhances existing feature: Charge Categorization

• Current Gap: Feature supports identifying corrections via ChargeClass but lacks guidance on how to reconcile corrections with original charges or attribute correction impacts at resource/service level
• Needed Capability: Practitioners need to trace corrections to specific charges and resources being corrected

[ ] Enhances existing feature: Billed Cost and Invoice Alignment

• Current Gap: Feature supports invoice reconciliation for standard charges but doesn't address how corrections to closed periods affect reconciliation workflows
• Needed Capability: Practitioners need to reconcile corrections issued in later billing periods back to the affected invoices

[ ] Introduces new feature:

• Decision pending working group: Depending on solution approach, this may warrant a distinct "Correction Reconciliation" capability or may be addressed through enhancements to existing features

Approach A: Enhance Existing Supported Features

Enhancement to "Charge Categorization" Feature

Current Feature Description:

FOCUS supports the categorization of charges including purchases, usage, tax, credits and adjustments. It includes classification on frequency. It includes classification on correction vs normal entries.

Draft Enhancement - Add to Description:

FOCUS supports the categorization of charges including purchases, usage, tax, credits and adjustments. It includes classification on frequency. It includes classification on correction vs normal entries. For correction entries, the specification enables practitioners to reconcile corrections with original charges and attribute correction impacts to specific resources and services.

Draft Enhancement - Add to Directly Dependent Columns:

• ChargeCategory
• ChargeClass
• ChargeFrequency
• ChargePeriodStart (add)
• ChargePeriodEnd (add)
• ResourceId (add)

Enhancement to "Billed Cost and Invoice Alignment" Feature

Current Feature Description:

FOCUS data should be consistent with the costs indicated on payable invoices. This is relevant to the total cost of the invoice, as well as the period of time the invoice covers.

Draft Enhancement - Add to Description:

FOCUS data should be consistent with the costs indicated on payable invoices. This is relevant to the total cost of the invoice, as well as the period of time the invoice covers. When corrections are issued in subsequent billing periods for previously invoiced charges, practitioners can reconcile the correction amount back to the affected invoice and billing period.

Draft Enhancement - Add to Directly Dependent Columns:

• BilledCost
• BillingCurrency
• BillingPeriodEnd
• BillingPeriodStart
• InvoiceId
• ChargeClass (add)
• ChargePeriodStart (add)
• ChargePeriodEnd (add)

Approach B: New Standalone Supported Feature

Feature Name

Correction Reconciliation

Description
Enables practitioners to identify correction records, reconcile them with previously invoiced charges, and attribute correction impacts to specific resources and services. Supports invoice reconciliation, accurate chargeback/showback workflows, and timely cost allocation when providers issue corrections for closed billing periods.

Directly Dependent Columns

• ChargeClass
• BilledCost
• BillingPeriodStart
• BillingPeriodEnd
• ChargePeriodStart
• ChargePeriodEnd
• ResourceId
• ServiceName

Supporting Columns

• ChargeCategory
• ChargeDescription
• InvoiceId
• SubAccountId
• BillingAccountId
• SkuId
• ResourceName

Comparison of Approaches

Aspect	Approach A: Enhance Existing	Approach B: New Feature
Discovery	Practitioners find correction capabilities within familiar features	Dedicated feature makes correction handling highly visible
Feature Count	Lower (2 enhanced features)	Higher (1 new + 2 existing features)
Column Dependencies	Distributed across multiple features	Centralized in one feature
Spec Footprint	Smaller incremental changes	New section in Supported Features
Practitioner Mental Model	"Corrections are a dimension of categorization and invoicing"	"Correction reconciliation is a distinct workflow"

---

🎯 Desired Outcome / Practitioner Impact

The goal of this work item is to formalize a consistent approach to correction handling across all columns within the FOCUS dataset.
By providing clear guidelines for producing conforming correction records and managing corrections across complex cost records in multi-dimensional and metric-based data contexts, this work item aims to minimize misinterpretation by both producers and consumers, ultimately enhancing data quality, integrity, and reliability.

Expected Outcomes:

• Clear, unambiguous rules and expectations for correction records as a whole, along with a unified approach to specifying correction handling normative requirements for individual columns, are established.
• An overarching correction handling attribute is introduced.
• Correction-related normative requirements for individual columns (e.g., metrics and related unit dimensions) are consistent and aligned with the agreed unified approach and overarching correction-handling attribute.

Success Criteria:

Success can be measured by improvements in clarity, consistency, and accuracy regarding correction handling, as well as positive feedback from providers and practitioners on the ease of producing and validating conforming correction records.

---

📨 Type of Request

• Refinement of an existing FOCUS attribute
• Addition of a provider-supported field not yet in FOCUS
• Net-new concept (not currently supported by providers or FOCUS)

---

🏛️ Organizations Requesting or Supporting This Feature

• Neos
• Hill Associates
• Twilio
• GoldmanSachs
• Domo

---

🌐 FinOps Scope Alignment (Optional)

• Public Cloud – AWS, Azure, GCP, etc.
• SaaS – Salesforce, Snowflake
• Data Center
• Licensing (under development)
• AI (under development)
• Custom (under development)

---

📊 Impacted Parties

• FinOps Practitioner
• FOCUS Data Generator
• Vendor Supporting FOCUS
• Other (please explain in comments)

---

🌫️ Level of Ambiguity

How clearly defined is the request? Rate from 1 to 5:

• 1 = very well-defined, low complexity
• 3 = moderately scoped, some ambiguity
• 5 = vague, high complexity or conceptual

3

---

📂 Supporting Documentation

WI #556
PR #675

Data Examples:

TBD

Prerequisites:

• Issue [DISCUSSION]: Formally document the backwards compatibility process for FOCUS #578
• Issue [EDITORIAL]: Editorial guidelines should be consistently applied throughout the specification. #594

Related Issues:

• Issue [Work_Item] Refine normative requirements for all existing spec content #557
• Issue [DISCUSSION]: Handling of corrections in the event of USAGE errors #511

---

🛠️ Proposed Solution / Approach

Initial Ideas:

• Define clear, unambiguous rules for the production, validation, and application of correction records.
• Establish a unified approach to correction handling normative requirements for individual columns.
• Introduce an overarching correction handling framework (attribute) that addresses all FOCUS columns under a holistic correction-handling guideline, aligned with previously defined rules.
• Revisit existing correction handling-related normative requirements for individual columns to ensure consistency and alignment with the overarching correction handling attribute and the agreed unified approach.

Considerations:

• There is a possibility that the results of this work item could introduce backward incompatibilities. Therefore, potential impacts will be carefully assessed at each stage of the process (e.g., defining rules, specifying the correction-handling attribute, and revisiting existing correction-related normative requirements for individual columns).
• Criteria for backward compatibility assessment are out of scope for this issue but must be prepared as a prerequisite.
• Normative requirements for existing FOCUS columns and attributes will be reviewed comprehensively in a separate issue.

Feasibility:

• Since this issue involves establishing rules and guidelines, introducing an overarching attribute, and addressing multiple columns, dividing the effort into multiple PRs will help manage the overall workload more effectively.

---

💬 Community Support (Add Your Voice)

If your organization supports this request or has a similar use case:

• Add a comment below including:
  • Your organization
  • A brief explanation of why this is important to you (e.g., use case, urgency)
• FOCUS Staff & Maintainers will aggregate supporting orgs over time.

[shawnalpay]

Setting back to Needs More Info to make sure a use case is generated.