FR #962: Adding Correction Handling and Delivery Handling attributes

specification/attributes/attributes.mdpp

@@ -1,8 +1,10 @@
 !INCLUDE "attributes_overview.md",0
 !INCLUDE "column_handling.md",1
+!INCLUDE "correction_handling.md",1
 !INCLUDE "currency_format.md",1
 !INCLUDE "data_generator_calculated_split_cost_allocation_handling.md",1
 !INCLUDE "datetime_format.md",1
+!INCLUDE "delivery_handling.md",1
 !INCLUDE "discount_handling.md",1
 !INCLUDE "json_object_format.md",1
 !INCLUDE "invoice_handling.md",1

specification/attributes/correction_handling.md

@@ -0,0 +1,99 @@
+# Correction Handling
+
+## Overview
+
+The Correction Handling attribute defines how [*corrections*](#glossary:correction) to a previously delivered FOCUS [*dataset artifact*](#glossary:dataset-artifact) are represented in a subsequently delivered *dataset artifact*.
+
+Corrections may include some combination of added, updated, or removed *rows*. Corrections may address a variety of operational or technical causes, such as refunds, late-arriving data, rounding errors, delivery errors, and other post-processing adjustments.
+
+Accurate correction handling is essential for a range of business-critical processes, including but not limited to:
+
+* Temporal accuracy - capturing both when the [*charge*](#glossary:charge) was incurred (reflected in [*charge period*](glossary:chargeperiod) columns, i.e., [Charge Period Start](#chargeperiodstart) and [Charge Period End](#chargeperiodend)) and when the correction was invoiced (reflected in [*billing period*](#glossary:billing-period) columns, i.e., [Billing Period Start](#billingperiodstart) and [Billing Period End](#billingperiodend)).
+* Financial and legal integrity - ensuring that data presented on [*issued invoices*](#glossary:issued-invoice) remains unchanged and aligned with associated underlying charges provided in the FOCUS dataset artifacts, while any related corrections do not compromise [*invoice reconciliation*](#glossary:invoice-reconciliation).
+* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., [*Billing Account ID*](#billingaccountid), [*Sub Account ID*](#subaccountid), [*SKU ID*](#skuid), [*SKU Price ID*](#skupriceid), [*Resource ID*](#resourceid)) to ensure accurate downstream processing.
+* Auditability - tracing the full lifecycle of a *charge* from the original record through all subsequent corrections.
+
+### Correction Styles
+
+FOCUS supports three styles for correcting original records:
+
+| Correction Style | Delivery Mechanism | Correction Style Description                                                                         |
+| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
+| Replacement      | Overwrite          | Original records are ignored and replaced by correction records.                                                        |
+| Delta            | Append             | Original records are preserved and modified by correction records.                                             |
+| Ledger           | Append             | Original records are preserved and decremented/incremented by correction records. |
+
+For more information on delivery mechanisms for *dataset artifacts*, see the [Delivery Handling attribute](#deliveryhandling).
+
+#### Replacement Corrections
+
+In the Replacement correction style, a given *dataset artifact* uses the Overwrite delivery mechanism to provide a complete snapshot of data for a *billing period*, based on the data available at the time of delivery.
+
+Any given *dataset artifact* completely replaces all previous *dataset artifacts* to reflect updates, additions, or omissions relative to the previous snapshot. Therefore, the practitioner only needs to reference the most recent *dataset artifact* for a given *billing period* in order to tell a complete story of *charges*; all previous dataset artifacts for that *billing period* are considered obsolete and can be safely ignored.
+
+Given that changes are not presented as separate entries, this style lacks inherent auditability.
+
+#### Delta Corrections
+
+In the Delta correction style, a given *dataset artifact* uses the Append delivery mechanism to add records that revise or supplement previous *dataset artifacts* within a *billing period*.
+
+In some cases, the correction consists of a new record representing a previously omitted cost. Explicit reversal is not commonly performed, but may be used if the correction itself represents a reversal.
+
+Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. Therefore, the practitioner must combine all *dataset artifacts* for a given *billing period* in order to tell a complete story of *charges*.
+
+Given that only net changes are presented, this style offers limited inherent auditability.
+
+#### Ledger Corrections
+
+In the Ledger correction style, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping method of decrements and increments to represent changes within a *billing period*.  Depending on the nature of the correction, either or both of the following steps may be required: (1) reversal of the original record using a charge in which cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original; and (2) a new record with corrected values.
+
+Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. Therefore, the practitioner must combine all *dataset artifacts* for a given *billing period* in order to tell a complete story of *charges*.
+
+Given that the entire change history is presented, this style offers full inherent auditability.
+
+### Corrections to Issued Charges
+
+A charge is considered issued when it is associated with an [*issued invoice*](#glossary:issued-invoice).
+
+While corrections to the [*issued charges*](#glossary:issued-charge) (including updates, additions, or omissions) may be permitted, they must not compromise the integrity of the associated *issued invoice*. Only corrections that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior *invoice reconciliation* and undermine the invoice's financial validity.
+
+Corrections to the underlying *issued charges* that do not impact data presented on the associated *issued invoice* are allowed. However, although these corrections do not affect *invoice reconciliation*, they can still result in loss of auditability and traceability, which in turn complicates modifications and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such corrections are not preferred and should only be applied when explicitly requested by the end-user.
+
+### Corrections to Closed Billing Periods
+
+A billing period is considered closed when all expected invoices for that timeframe have been issued.
+
+Any necessary corrections to a previously *closed billing period* that require issuing additional invoices are associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred. This approach establishes a clear temporal boundary between billing cycles, preserving the historical financial accuracy and integrity of closed billing periods while enabling transparent and auditable tracking of corrections in future periods.
+
+## Attribute ID
+
+CorrectionHandling
+
+## Attribute Name
+
+Correction Handling
+
+## Description
+
+Defines how *corrections* to a previously delivered FOCUS *dataset artifact* are represented in a subsequently delivered *dataset artifact*.
+
+## Requirements
+
+All corrections adhere to the following requirements:
+
+* The correction style(s) used to correct FOCUS *dataset artifacts* MUST be documented by the data generator.
+* Correction MUST NOT introduce a discrepancy between an *issued invoice* and its associated FOCUS *dataset artifacts*.
+* Correction to a previously *closed billing period* that requires issuing additional invoices MUST result in additional charge(s) associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred.
+* Correction delivered using the Append delivery mechanism adheres to the following additional requirements:
+  * Correction MUST include exclusively additional charges.
+  * Correction MUST NOT include updates or omissions of previously delivered charges.
+
+## Exceptions
+
+* Exceptions to the restrictions on *issued charges*, *issued invoices*, and *closed billing periods* and MAY apply in the following cases:
+  * Upon explicit request from the end-user (subject to validation and approval processes).
+  * Due to technical issues encountered during or after invoice issuance or billing period closure.
+
+## Introduced (version)
+
+1.3

specification/attributes/delivery_handling.md

@@ -0,0 +1,64 @@
+# Delivery Handling
+
+## Overview
+
+The Delivery Handling attribute defines how a data generator delivers a *dataset artifact* to a customer.
+
+### Delivery Mechanisms
+
+FOCUS supports two delivery mechanisms:
+
+* Overwrite. Existing rows are replaced.
+* Append. Existing rows are preserved.
+
+These mechanisms are not mutually exclusive, and hybrid implementations are common, allowing data generators to meet specific technical and auditability requirements.
+
+For more information on corrections, see the [Correction Handling attribute](*correctionhandling).
+
+#### Overwrite Delivery
+
+In the Overwrite delivery mechanism, each *dataset artifact* provides a complete snapshot of data for a given [*billing period*](#glossary:billing-period), based on the data available at the time of delivery. Subsequent *dataset artifacts* typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism provides delivery simplicity, but it lacks inherent auditability.
+
+Subsequent *dataset artifacts* using the Overwrite mechanism may include the following:
+
+* Unchanged records are carried over.
+* Updated records overwrite previous values.
+* Additional records supplement previously delivered data.
+* Omitted records are removed if no longer applicable.
+
+#### Append Delivery
+
+In the Append delivery mechanism, a subsequent *dataset artifact* appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained.
+
+Subsequent *dataset artifacts* using the Append mechanism may include the following:
+
+* Unchanged recorded are not included.
+* Updated records are recorded as new entries, representing the difference.
+* Additional records supplement previously delivered data.
+* Omitted records are recorded as new entries, representing the reversal.
+
+## Attribute ID
+
+DeliveryHandling
+
+## Attribute Name
+
+Delivery Handling
+
+## Description
+
+Defines how a data generator delivers a *dataset artifact* to a customer.
+
+## Requirements
+
+The delivery of a *dataset artifact* adheres to the following requirements:
+
+* The delivery mechanism(s) used to deliver FOCUS *dataset artifacts* MUST be documented by the data generator.
+
+## Exceptions
+
+None
+
+## Introduced (version)
+
+1.3

specification/attributes/invoice_handling.md

@@ -1,8 +1,39 @@
 # Invoice Handling
 
-FinOps practitioners must be able to reconcile FOCUS datasets with the corresponding invoices and usage statements they receive from [*Invoice Issuers*](#glossary:InvoiceIssuer). In practice, this means ensuring that all monetary [*charges*](#glossary:charge) that appear on an invoice or usage statement — including those not tied to metered usage — are represented in the [*FOCUS dataset*](#glossary:FOCUS-dataset). Without this alignment, it becomes difficult to perform accurate invoice reconciliation, financial reporting, and chargeback.
+## Overview
 
-This attribute introduces requirements for how charges such as usage, taxes, credits, refunds, etc, inclusive of support, training, and marketplace transactions, and any other type of charge should be captured and categorized. It also defines expectations around the completeness and consistency of invoice-level totals within the dataset, enabling FOCUS datasets to be used in a system of record for all invoiced costs.
+The Invoice Handling attribute defines how a [*FOCUS dataset*](#glossary:FOCUS-dataset) should reflect details for the information presented on an [*invoice*](#glossary:invoice).
+
+This attribute introduces requirements for how monetary [*charges*](#glossary:charge) such as usage, taxes, credits, refunds, etc, inclusive of support, training, and marketplace transactions, and any other type of charge should be captured and categorized. It also defines expectations around the completeness and consistency of invoice-level totals within a FOCUS dataset, enabling FOCUS [*dataset artifacts*](#glossary:dataset-artifact) to be used in a system of record for all invoiced costs.
+
+FinOps practitioners must be able to reconcile *FOCUS datasets* with the corresponding invoices and usage statements they receive from [*invoice issuers*](#invoiceissuername). In practice, this means ensuring that all *charges* that appear on an invoice or usage statement, including those not tied to metered usage, are represented in a *FOCUS dataset*. Without this alignment, it becomes difficult to perform accurate [*invoice reconciliation*](#glossary:invoice-reconciliation), financial reporting, and chargeback.
+
+### Invoice Reconciliation and Issuance
+
+Prior to [*invoice issuance*](#glossary:issued-invoice), the invoice must undergo a reconciliation process. In this process, the *invoice issuer* ensures that the aggregated cost and usage information presented on the *invoice* matches the detailed cost and usage *charges* presented in a *FOCUS dataset*.
+
+At the conclusion of this process, the total monetary value presented on an invoice must match the total monetary value presented in the [Billed Cost](#billedcost) metric of a FOCUS dataset. Further, the detail presented on an invoice must match the values of Billed Cost when aggregated by the related combination of the following FOCUS dataset dimensions:
+
+* [Billing Account ID](#billingaccountid)
+* [Billing Currency](#billingcurrency)
+* [Billing Period Start](#billingperiodstart)
+* [Billing Period End](#billingperiodend)
+* [Invoice ID](#invoiceid)
+* [Invoice Issuer Name](#invoiceissuername)
+
+Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions.
+
+Once an invoice is issued, it becomes an authoritative financial document, and the information it contains is expected not to change. [*Corrections*](#glossary:correction) to *issued charges* (including updates, additions, or omissions) may be permitted under certain conditions. However, such corrections must not compromise the integrity of the associated *issued invoice*. For more information on *corrections* to *issued charges*, refer to the [Correction Handling attribute](#correctionhandling).
+
+This information then allows FinOps practitioners to perform their own *invoice reconciliation* process, in order to ensure that the costs reflected on an invoice are commensurate with the usage they have observed.
+
+### Open and Closed Billing Periods
+
+While a billing period is open, one or more FOCUS dataset artifacts may be generated to represent that timeframe. At some point, the billing period will be closed.
+
+A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all expected invoices have been successfully issued by an invoice issuer. Once a billing period is financially closed, no additional invoices are expected to be associated with that timeframe.
+
+The ability to determine whether a billing period is "open" or "closed" is typically documented by the invoice issuer and made accessible to customers. There is typically a documented date and time by which all FOCUS dataset artifacts associated with a previous billing period will be generated, and no further artifacts will be expected. At that time, the data presented in the FOCUS dataset artifacts associated with a closed billing period is considered final, though corrections can be made in subsequent billing periods. For information on *corrections* to *closed billing periods*, refer to the [Correction Handling attribute](#correctionhandling).
 
 ## Attribute ID
 
@@ -14,12 +45,18 @@ Invoice Handling
 
 ## Description
 
-Indicates how invoice-level *charges*, including those not directly tied to usage, should be represented in a FOCUS Cost and Usage dataset.
+Defines how a *FOCUS dataset* should reflect details for the information presented on an *invoice*.
 
 ## Requirements
 
-* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the *FOCUS dataset*.
-* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, data generators MUST include provider-defined columns (e.g., x_ChargeSubType) to capture the non-FOCUS-defined details needed to support invoice *charges* reconciliation using the *FOCUS dataset*.
+* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in one or more FOCUS Cost and Usage *dataset artifacts*.
+* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, data generators MUST include custom columns (e.g., x_ChargeSubType) to capture the non-FOCUS-defined details needed to support invoice *charges* reconciliation using the FOCUS Cost and Usage *dataset artifacts*.
+* *Invoice reconciliation* adheres to the following additional requirements:
+  * Invoice issuer MUST perform *Invoice reconciliation* between an *invoice* and its associated FOCUS *dataset artifacts* before issuing the invoice.
+  * *Invoice reconciliation* process MUST include (but is not limited to) the following metric and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuerName, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd.
+  * Invoice issuer MUST document which FOCUS dataset columns are included in the *invoice reconciliation* process.
+* The data generator MUST notify the customer if the contents of a *dataset artifact* associated with an *issued invoice* are altered after final delivery.
+* The *billing period* (i.e., the timeframe from BillingPeriodStart to BillingPeriodEnd) of a charge MUST match the *billing period* of its associated [*InvoiceId*](#invoiceid).
 
 ## Exceptions
 
@@ -28,8 +65,6 @@ Indicates how invoice-level *charges*, including those not directly tied to usag
   * SLA credit details when the credit is already applied to the charged amount
 * If such informational items are excluded, data generators MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total.
 
-None
-
 ## Introduced (version)
 
 1.3