From 835847e2918ca4bf429df19623f75a36ec2cfda4 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 19 Aug 2025 16:07:14 +0200 Subject: [PATCH 01/71] FOCUS #962: Correction Handling attribute spec --- specification/attributes/attributes.mdpp | 1 + .../attributes/correction_handling.md | 88 +++++++++++++++++++ .../attributes/correction_handling.md | 72 +++++++++++++++ 3 files changed, 161 insertions(+) create mode 100644 specification/attributes/correction_handling.md create mode 100644 supporting_content/attributes/correction_handling.md diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index 269ec3182..91f28a4ed 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -6,6 +6,7 @@ for data granularity, recency, frequency, etc. Requirements defined in attribute [FinOps capabilities][FODOFC] accurately using a standard set of instructions regardless of the origin of the data. !INCLUDE "column_handling.md",1 +!INCLUDE "correction_handling.md",1 !INCLUDE "currency_format.md",1 !INCLUDE "datetime_format.md",1 !INCLUDE "discount_handling.md",1 diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md new file mode 100644 index 000000000..d92c5a269 --- /dev/null +++ b/specification/attributes/correction_handling.md @@ -0,0 +1,88 @@ +# Correction Handling + +Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. + +**Terminology Note:** Correction (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections to previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to all previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. + +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors or post-processing adjustments, etc. + +Accurate correction handling is essential for a range of business-critical processes, including but not limited to: + +* Temporal accuracy - capturing both when the charge was incurred (reflected in the charge periods, i.e., Charge Period Start and Charge Period End columns) and when the correction was invoiced (reflected in the billing period, i.e., Billing Period Start and Billing Period End columns). +* Financial and legal integrity - preserving original charge records associated with finalized invoices and recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. +* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). +* Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. + +## Provisioning Styles + +To ensure consistent interpretation and correct implementation, it is important to clarify how Correction Handling relates to other foundational concepts such as data delivery styles and invoice finalization. + +Data generators typically deliver cost and usage records using one of two models: + +* Replacement: + * Previously delivered records are overwritten with updated versions, omitted if obsolete, or supplemented with additional records. This model assumes consumers will discard prior versions and always use the latest available data. + * Previously delivered records may be overwritten with updated versions, omitted when obsolete, or supplemented with additional records to represent related corrections (e.g., refunds). Multiple records for the same dimensions may coexist, so consumers should handle such cases appropriately. This model does not provide a built-in audit trail; consumers must maintain historical snapshots independently to enable auditability. +* Append-only: + * To correct the original, one or more new records are added without modifying existing ones. Corrections are represented by adding new rows, and previously delivered rows remain unchanged. + * Corrections are implemented by adding one or more new records without modifying or deleting any previously delivered records. Duplicate records are explicitly disallowed. All original and correction records are preserved as distinct entries, inherently supporting a built-in audit trail. + +FOCUS supports both Replacement and Append-only delivery styles for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only append-only modeling is permitted. This ensures financial integrity and enables accurate audit trails. + +There are two standard approaches to modeling corrections in append-only delivery model: + +* In ledger-style correction, adjustments are modeled by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. + +## Invoice Finalization + +A billing period is considered closed once all invoices for that period are finalized. After that point, the original invoice and its records must remain immutable. Corrections to such periods must not overwrite existing records and must follow special provisioning rules (see below). + +If a correction is applied to a charge from a closed billing period, the corrected record must: + +* The correction MUST NOT replace or omit the original record. +* Be assigned to a different invoice (i.e., not the one originally associated with the charge). +* Have BillingPeriodStart and BillingPeriodEnd values that correspond to the open billing period in which the correction is issued. +* Preserve the original ChargePeriodStart and ChargePeriodEnd values to indicate when the corrected cost was actually incurred. + +This dual treatment—distinguishing the charge period from the billing period—allows cost data consumers to understand both the historical intent and the current accounting context for each correction. + +## Attribute ID + +CorrectionHandling + +## Attribute Name + +Correction Handling + +## Description + +Defines how updates to previously provided charge records are represented in FOCUS datasets. + +## Requirements + +> WORK IN PROGRESS !!! + +All corrections/changes to previously provided charge records in FOCUS dataset MUST follow the correction handling requirements listed below. + +* Corrections to charges in previously closed billing periods MUST satisfy the following: + * The correction MUST NOT replace or omit the original record. + * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. + * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued. + * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time interval in which the charge occurred. + * ChargeClass MUST be set to "Correction". +* Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). +* Etc. + +## Exceptions + +> WORK IN PROGRESS !!! + +Potential exceptions, to be discussed: + +* Restatement of Dimensions Not on Original Invoice: Determine whether exceptions will be allowed for corrections that modify only non-invoiced dimensions. +* Technical issues mentioned by Riley. +* Replacment over Append-only explicitly specified by the end-user. + +## Introduced (version) + +1.3 diff --git a/supporting_content/attributes/correction_handling.md b/supporting_content/attributes/correction_handling.md new file mode 100644 index 000000000..6d30c965a --- /dev/null +++ b/supporting_content/attributes/correction_handling.md @@ -0,0 +1,72 @@ +# Correction handling + +## Prevent Replacement After Invoice Finalization (and Billing Period Closure) + +> **TODO:** Mention/address in upcoming Correction Handling attribute + +***Note:*** *See S-1: Itemized Correction Scenarios with Cost Calculation Integrity Respected - S-1.1 and S-1.2 in particular* + +We should prevent the use of the Replacement provisioning style once an invoice has been finalized and the corresponding billing period closed. + +Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections — and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: + +- A finalized invoice is considered legally issued and immutable. +- The associated billing period is closed, prohibiting any modifications or overwriting of previously delivered records. + +Therefore, only append-only provisioning styles (such as ledger-style increments/decrements or accounting-style reversals followed by corrected entries) should be permitted for handling Post-Invoice Finalization Corrections. + +**Exceptions:** + +- Contributors are encouraged to document any exception to the general rule. + +- Should we allow restating in cases where corrections apply to dimensions that were not included in the original invoice? +Personally, I would prefer not to allow this — but this is currently the only scenario where I can see a possible justification. +- Technical issues mentioned by Riley. +- Explicitly specified by the end-user. + +### Normative Requirements for Post-Invoice Finalization Corrections + +> **TODO:** Mention/address in upcoming Correction Handling attribute +> (Shawn has added numbers to the statements that would become normative requirements in the attribute) + +The following applies to all corrections to a previously closed billing period, i.e., correction charge records provisioned after invoice finalization and billing period closure, but which pertain to activity that occurred during that already invoiced and closed period: + +- **Legal and Procedural Perspective:** + - <<1>> The invoice is considered legally issued and immutable. + - The billing period is considered closed, thereby prohibiting any modifications to or overwriting of the originally invoiced records. + +- **Provisioning perspective**: `x_ExportDateTime = T2` (i.e., the date it became available to the consumer) + +- **Operational Perspective**: All Correction records (Increments and Decrements in case of the Ledger style, Negations and Corrected records in case of Accounting style) pertain to activity that occurred in **May**, so in case of Usage records <<2>> `ChargePeriodStart`/`ChargePeriodEnd` **must reflect the actual usage period** (e.g., `ChargePeriodStart = 2025-05-01`) + +- **Financial Perspective**: The original invoice (e.g., `INV-20250501-20250601`) has already been finalized (issued and sent e.g., as PDF). The May billing period is **considered closed** therefore + - <<3>> `BillingPeriodStart`/`BillingPeriodEnd` **must be equal to or later than** the first **open** billing period (i.e., June 2025 or later) + - <<4>> `InvoiceId` must not match the original invoice (e.g., `INV-20250501-20250601`). + +- **Charge Class:** <<5>> ChargeClass must be set to "Correction". + +## Cost and Usage data Provisioning Styles + +> **TODO:** Mention/address in upcoming Correction Handling attribute + +Data Generators typically use two main provisioning styles/mechanisms when delivering cost and usage data: + +- **Replacement:** Overwrites previously delivered records with updated ones. This approach ensures data accuracy by reflecting corrections directly in place. + +- **Append-only:** Delivers only new records without modifying previously sent data. This approach can be further divided into two subtypes: + - **Ledger-style:** Adds incremental (or decremental) records over time. Corrections are reflected as additional entries where the cost or quantity metrics are adjusted (+/-), while all other dimensions remain identical to the original record. This supports an append-only model but offers limited auditability, as there is typically no explicit reversal. + - **Accounting-style:** Tracks changes explicitly via negative (reversal) entries followed by corrected records. This ensures full auditability and provides a clear historical trail of adjustments. + +## Finalized Invoice and Closed Billing Period + +> **TODO:** Mention/address in upcoming Correction Handling attribute +> See [FR #Add invoice-level correction handling rules](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/issues/1013) + +While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **“closed”** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. + +To address these **gaps** in this scenario, we assume the following: + +- Data Generator (Providers) finalize invoices at some point, marking them as ready for invoice reconciliation. +- A billing period is considered closed once all invoices for that period are finalized. + +***Note:** These information are assumed to be provided not within the cost and usage dataset itself, but in separate, adjacent datasets (e.g., invoice-related datasets). From bd5f3345ed844dd1d11d3a103be78bed96823427 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 19 Aug 2025 17:01:56 +0200 Subject: [PATCH 02/71] FOCUS #962: Correction Handling attribute spec --- specification/attributes/correction_handling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index d92c5a269..4c1236dae 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,14 +2,14 @@ Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** Correction (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections to previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to all previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. +**Terminology Note:** The term "Correction" (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections for previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. -Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors or post-processing adjustments, etc. +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors, post-processing adjustments, etc. Accurate correction handling is essential for a range of business-critical processes, including but not limited to: -* Temporal accuracy - capturing both when the charge was incurred (reflected in the charge periods, i.e., Charge Period Start and Charge Period End columns) and when the correction was invoiced (reflected in the billing period, i.e., Billing Period Start and Billing Period End columns). -* Financial and legal integrity - preserving original charge records associated with finalized invoices and recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. +* Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). +* Financial and legal integrity - preserving original charge records associated with finalized invoices while recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. From c454121877b12b3f1924760ed8b767ddd085a137 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 20 Aug 2025 16:35:17 +0200 Subject: [PATCH 03/71] FOCUS #962: Correction Handling attribute spec update - work in progress --- .../attributes/correction_handling.md | 47 ++++++++----------- 1 file changed, 20 insertions(+), 27 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 4c1236dae..2d47ab003 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -13,38 +13,34 @@ Accurate correction handling is essential for a range of business-critical proce * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. -## Provisioning Styles +Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -To ensure consistent interpretation and correct implementation, it is important to clarify how Correction Handling relates to other foundational concepts such as data delivery styles and invoice finalization. +A billing period is considered closed once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is closed, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in a closed billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -Data generators typically deliver cost and usage records using one of two models: +FOCUS datasets can be delivered using one of two mechanisms - Replacement or sppend-only. -* Replacement: - * Previously delivered records are overwritten with updated versions, omitted if obsolete, or supplemented with additional records. This model assumes consumers will discard prior versions and always use the latest available data. - * Previously delivered records may be overwritten with updated versions, omitted when obsolete, or supplemented with additional records to represent related corrections (e.g., refunds). Multiple records for the same dimensions may coexist, so consumers should handle such cases appropriately. This model does not provide a built-in audit trail; consumers must maintain historical snapshots independently to enable auditability. -* Append-only: - * To correct the original, one or more new records are added without modifying existing ones. Corrections are represented by adding new rows, and previously delivered rows remain unchanged. - * Corrections are implemented by adding one or more new records without modifying or deleting any previously delivered records. Duplicate records are explicitly disallowed. All original and correction records are preserved as distinct entries, inherently supporting a built-in audit trail. +For the Replacement mechanism, the initial and each subsequent dataset for a billing period provide a complete snapshot of cost and usage data collected for that period up to the time of delivery, with each subsequent dataset reflecting any updates, omissions, or additions since the previous one. This mechanism does not provide a built-in audit trail, so historical snapshots must be maintained separately to support traceability. -FOCUS supports both Replacement and Append-only delivery styles for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only append-only modeling is permitted. This ensures financial integrity and enables accurate audit trails. +In the Replacement mechanism, charge records in subsequent datasets are handled as follows: -There are two standard approaches to modeling corrections in append-only delivery model: +* Unchanged charge records – carried over unchanged from the previously delivered dataset. +* Updated charge records – overwritten with the latest values. +* Additional charge records – new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). +* Omitted charge records – removed from the dataset because they are no longer applicable. -* In ledger-style correction, adjustments are modeled by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. +In the Append-only mechanism, corrections are represented exclusively by appending one or more new records, while previously delivered records remain unchanged. Duplicate records are explicitly disallowed. This mechanism inherently supports a built-in audit trail, since all original and correction records are retained as distinct entries. + +When the Append-only delivery mechanism is used, there are two common styles for modeling corrections: -## Invoice Finalization +* In ledger-style correction, corrections are represented by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. -A billing period is considered closed once all invoices for that period are finalized. After that point, the original invoice and its records must remain immutable. Corrections to such periods must not overwrite existing records and must follow special provisioning rules (see below). +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a charge record that matches all fields of the original except for the numeric values, which are inverted, followed by a new record with the corrected values. This model preserves a full correction history and is preferred when transparency and traceability are required. -If a correction is applied to a charge from a closed billing period, the corrected record must: +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. -* The correction MUST NOT replace or omit the original record. -* Be assigned to a different invoice (i.e., not the one originally associated with the charge). -* Have BillingPeriodStart and BillingPeriodEnd values that correspond to the open billing period in which the correction is issued. -* Preserve the original ChargePeriodStart and ChargePeriodEnd values to indicate when the corrected cost was actually incurred. +FOCUS supports both Replacement and Append-only cost and usage data delivery mechanisms for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only Append-only delivery mechanism is permitted. This ensures financial integrity and enables accurate audit trails. -This dual treatment—distinguishing the charge period from the billing period—allows cost data consumers to understand both the historical intent and the current accounting context for each correction. +All correction charge records adhere to the correction handling requirements listed below. ## Attribute ID @@ -62,16 +58,13 @@ Defines how updates to previously provided charge records are represented in FOC > WORK IN PROGRESS !!! -All corrections/changes to previously provided charge records in FOCUS dataset MUST follow the correction handling requirements listed below. - -* Corrections to charges in previously closed billing periods MUST satisfy the following: +* Corrections to charges in previously closed billing periods adhere to the following additional requirements: * The correction MUST NOT replace or omit the original record. * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. - * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued. - * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time interval in which the charge occurred. + * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued (correspond to the open billing period in which the correction is issued). + * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time window in which the charge occurred (cost was actually incurred). * ChargeClass MUST be set to "Correction". * Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). -* Etc. ## Exceptions From 08c2346edf34689911e59d5bfadb3fd65db9cfb9 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Thu, 21 Aug 2025 12:09:13 -0700 Subject: [PATCH 04/71] linter fix --- specification/attributes/correction_handling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 2d47ab003..0fb90b78d 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -23,10 +23,10 @@ For the Replacement mechanism, the initial and each subsequent dataset for a bil In the Replacement mechanism, charge records in subsequent datasets are handled as follows: -* Unchanged charge records – carried over unchanged from the previously delivered dataset. -* Updated charge records – overwritten with the latest values. -* Additional charge records – new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). -* Omitted charge records – removed from the dataset because they are no longer applicable. +* Unchanged charge records - carried over unchanged from the previously delivered dataset. +* Updated charge records - overwritten with the latest values. +* Additional charge records - new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). +* Omitted charge records - removed from the dataset because they are no longer applicable. In the Append-only mechanism, corrections are represented exclusively by appending one or more new records, while previously delivered records remain unchanged. Duplicate records are explicitly disallowed. This mechanism inherently supports a built-in audit trail, since all original and correction records are retained as distinct entries. From d972df5df831c9aeeb998c4988ff9e65f3f95fa0 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 00:38:40 +0200 Subject: [PATCH 05/71] FOCUS #962: Correction Handling attribute spec update - work in progress --- .../attributes/correction_handling.md | 65 ++++++++++++------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 2d47ab003..75f1212d4 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,9 +2,9 @@ Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** The term "Correction" (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections for previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. -Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors, post-processing adjustments, etc. +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. Accurate correction handling is essential for a range of business-critical processes, including but not limited to: @@ -15,30 +15,31 @@ Accurate correction handling is essential for a range of business-critical proce Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -A billing period is considered closed once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is closed, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in a closed billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -FOCUS datasets can be delivered using one of two mechanisms - Replacement or sppend-only. +FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. -For the Replacement mechanism, the initial and each subsequent dataset for a billing period provide a complete snapshot of cost and usage data collected for that period up to the time of delivery, with each subsequent dataset reflecting any updates, omissions, or additions since the previous one. This mechanism does not provide a built-in audit trail, so historical snapshots must be maintained separately to support traceability. +In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, and therefore historical snapshots must be retained externally to support traceability. -In the Replacement mechanism, charge records in subsequent datasets are handled as follows: +Subsequent datasets in the Replacement mechanism may include the following: -* Unchanged charge records – carried over unchanged from the previously delivered dataset. -* Updated charge records – overwritten with the latest values. -* Additional charge records – new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). -* Omitted charge records – removed from the dataset because they are no longer applicable. +* Unchanged records are carried over. +* Updated records overwrite previous values. +* Additional records supplement previously delivered data. +* Omitted records are removed if no longer applicable. -In the Append-only mechanism, corrections are represented exclusively by appending one or more new records, while previously delivered records remain unchanged. Duplicate records are explicitly disallowed. This mechanism inherently supports a built-in audit trail, since all original and correction records are retained as distinct entries. +Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Modifications or deletions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. -When the Append-only delivery mechanism is used, there are two common styles for modeling corrections: +In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. -* In ledger-style correction, corrections are represented by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. +Corrections in the Append-only mechanism are represented exclusively by adding new records, and duplicate entries are explicitly disallowed. -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a charge record that matches all fields of the original except for the numeric values, which are inverted, followed by a new record with the corrected values. This model preserves a full correction history and is preferred when transparency and traceability are required. +Within the Append-only mechanism, two correction styles are commonly used: -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. +* Ledger-style correction: Adds records that adjust selected cost- and quantity-related columns by incrementing or decrementing their values. All other columns remain unchanged. No explicit reversal is performed. This style offers limited audit transparency. +* Accounting-style correction: Uses a two-step representation. First, the original record is reversed using a charge, in which all cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original. This reversal charge is typically followed by a new record with the corrected values, although in some cases only the reversal is provided. This style preserves full correction history. -FOCUS supports both Replacement and Append-only cost and usage data delivery mechanisms for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only Append-only delivery mechanism is permitted. This ensures financial integrity and enables accurate audit trails. +To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. All correction charge records adhere to the correction handling requirements listed below. @@ -58,13 +59,27 @@ Defines how updates to previously provided charge records are represented in FOC > WORK IN PROGRESS !!! -* Corrections to charges in previously closed billing periods adhere to the following additional requirements: - * The correction MUST NOT replace or omit the original record. - * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. - * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued (correspond to the open billing period in which the correction is issued). - * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time window in which the charge occurred (cost was actually incurred). - * ChargeClass MUST be set to "Correction". -* Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). +* Data Generator MUST publish the provisioning and correction styles in use (Replacement, Ledger-style, Accounting-style) within their respective documentation. +* Correction MUST NOT result in double counting of any cost- or quantity-related values. + +### Invoice and Billing Period + +* Invoice MUST be considered finalized and immutable once issued. +* Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: + * Charge record MUST be considered finalized and immutable. + * Charge record MUST NOT be updated, deleted, or omitted. +* Additional charge records MUST NOT be associated with an invoice once it is issued. +* Billing period MUST be considered invoiced and closed once all invoices for that period are issued. +* Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. + +### Corrections to charges from a previously invoiced and closed billing period + +* Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: + * ChargeClass MUST be "Correction". + * Correction MUST NOT replace or omit the original record. + * Corrected row(s) MUST be assigned to a different `InvoiceId` than the original record. + * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. + * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. ## Exceptions @@ -76,6 +91,10 @@ Potential exceptions, to be discussed: * Technical issues mentioned by Riley. * Replacment over Append-only explicitly specified by the end-user. +* Replacement provisioning style MAY be applied, even for charges included in datasets associated with previously invoiced billing periods, when xplicitly requested by the end-user. +* Providers MAY apply the Replacement provisioning style instead of Append-only, even for charges included in datasets associated with previously invoiced billing periods, provided that updates affect only non-invoiced dimensions and the integrity of finalized invoices is preserved. +* (TODO) Technical issues mentioned by Riley. + ## Introduced (version) 1.3 From c656424cce8d036af088c1032f83406ef88e578c Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 01:28:05 +0200 Subject: [PATCH 06/71] FOCUS #962: Correction Handling attribute spec update - supporting content scrub --- specification/attributes/correction_handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 7416359d4..8d536fdc5 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -15,7 +15,7 @@ Accurate correction handling is essential for a range of business-critical proce Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. From a4347b0c2bbcac6fbc6e95a1ea307128735b1b78 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 01:39:45 +0200 Subject: [PATCH 07/71] FOCUS #962: Correction Handling attribute - ignore --- specification/attributes/correction_handling.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 8d536fdc5..8877bafa3 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,5 +1,7 @@ # Correction Handling +Test. + Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. From 4ea2c86661b60037b2e21289ee4ed682c56a379e Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 14:07:40 +0200 Subject: [PATCH 08/71] FOCUS #962: Correction Handling attribute spec update --- .../attributes/correction_handling.md | 55 ++++++++----------- 1 file changed, 22 insertions(+), 33 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 8877bafa3..0543abd70 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,10 +1,8 @@ # Correction Handling -Test. - Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously invoiced billing period or an uninvoiced billing period (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. @@ -21,7 +19,7 @@ A billing period is considered invoiced (or closed) once all invoices for that p FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. -In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, and therefore historical snapshots must be retained externally to support traceability. +In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. Subsequent datasets in the Replacement mechanism may include the following: @@ -30,16 +28,16 @@ Subsequent datasets in the Replacement mechanism may include the following: * Additional records supplement previously delivered data. * Omitted records are removed if no longer applicable. -Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Modifications or deletions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. +Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Updated or omissions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. -Corrections in the Append-only mechanism are represented exclusively by adding new records, and duplicate entries are explicitly disallowed. +Corrections in the Append-only mechanism are represented exclusively by adding new records. Within the Append-only mechanism, two correction styles are commonly used: -* Ledger-style correction: Adds records that adjust selected cost- and quantity-related columns by incrementing or decrementing their values. All other columns remain unchanged. No explicit reversal is performed. This style offers limited audit transparency. -* Accounting-style correction: Uses a two-step representation. First, the original record is reversed using a charge, in which all cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original. This reversal charge is typically followed by a new record with the corrected values, although in some cases only the reversal is provided. This style preserves full correction history. +* Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. +* Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. @@ -59,47 +57,38 @@ Defines how updates to previously provided charge records are represented in FOC ## Requirements -> WORK IN PROGRESS !!! - -* Data Generator MUST publish the provisioning and correction styles in use (Replacement, Ledger-style, Accounting-style) within their respective documentation. -* Correction MUST NOT result in double counting of any cost- or quantity-related values. - -### Invoice and Billing Period - * Invoice MUST be considered finalized and immutable once issued. * Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: * Charge record MUST be considered finalized and immutable. * Charge record MUST NOT be updated, deleted, or omitted. -* Additional charge records MUST NOT be associated with an invoice once it is issued. * Billing period MUST be considered invoiced and closed once all invoices for that period are issued. +* Additional charge records MUST NOT be associated with an invoice once it is issued. * Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. -### Corrections to charges from a previously invoiced and closed billing period +* Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. +* Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. +* Correction MUST NOT result in double counting of any cost- or quantity-related values. * Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. - * Corrected row(s) MUST be assigned to a different `InvoiceId` than the original record. + * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. -## Exceptions - -> WORK IN PROGRESS !!! - ---- +* Replacement mechanism adheres to the following additional requirements: + * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). + * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. + * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. +* Append-only mechanism adheres to the following additional requirements: + * All previously delivered records MUST be retained without modification or deletion. + * All corrections MUST be represented exclusively by adding new records. -Potential exceptions, to be discussed: - -* Restatement of Dimensions Not on Original Invoice: Determine whether exceptions will be allowed for corrections that modify only non-invoiced dimensions. -* Technical issues mentioned by Riley. -* Replacment over Append-only explicitly specified by the end-user. - ---- +## Exceptions -* Replacement provisioning style MAY be applied, even for charges included in datasets associated with previously invoiced billing periods, when xplicitly requested by the end-user. -* Providers MAY apply the Replacement provisioning style instead of Append-only, even for charges included in datasets associated with previously invoiced billing periods, provided that updates affect only non-invoiced dimensions and the integrity of finalized invoices is preserved. -* (TODO) Technical issues mentioned by Riley. +* Exceptions to the restrictions on issued invoices, invoiced billing periods, and finalized charge records 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) From 46e3dd1a3fe3b0ca54b139796b90d69ee4796949 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 14:19:13 +0200 Subject: [PATCH 09/71] FOCUS #962: Correction Handling attribute supporting content scrub --- .../attributes/correction_handling.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/supporting_content/attributes/correction_handling.md b/supporting_content/attributes/correction_handling.md index 6d30c965a..2d5c2337e 100644 --- a/supporting_content/attributes/correction_handling.md +++ b/supporting_content/attributes/correction_handling.md @@ -2,13 +2,11 @@ ## Prevent Replacement After Invoice Finalization (and Billing Period Closure) -> **TODO:** Mention/address in upcoming Correction Handling attribute - ***Note:*** *See S-1: Itemized Correction Scenarios with Cost Calculation Integrity Respected - S-1.1 and S-1.2 in particular* We should prevent the use of the Replacement provisioning style once an invoice has been finalized and the corresponding billing period closed. -Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections — and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: +Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections - and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: - A finalized invoice is considered legally issued and immutable. - The associated billing period is closed, prohibiting any modifications or overwriting of previously delivered records. @@ -20,14 +18,13 @@ Therefore, only append-only provisioning styles (such as ledger-style increments - Contributors are encouraged to document any exception to the general rule. - Should we allow restating in cases where corrections apply to dimensions that were not included in the original invoice? -Personally, I would prefer not to allow this — but this is currently the only scenario where I can see a possible justification. + *Note: Personally, I would prefer not to allow this.* - Technical issues mentioned by Riley. - Explicitly specified by the end-user. ### Normative Requirements for Post-Invoice Finalization Corrections -> **TODO:** Mention/address in upcoming Correction Handling attribute -> (Shawn has added numbers to the statements that would become normative requirements in the attribute) +> Shawn has added numbers to the statements that would become normative requirements in the attribute The following applies to all corrections to a previously closed billing period, i.e., correction charge records provisioned after invoice finalization and billing period closure, but which pertain to activity that occurred during that already invoiced and closed period: @@ -47,8 +44,6 @@ The following applies to all corrections to a previously closed billing period, ## Cost and Usage data Provisioning Styles -> **TODO:** Mention/address in upcoming Correction Handling attribute - Data Generators typically use two main provisioning styles/mechanisms when delivering cost and usage data: - **Replacement:** Overwrites previously delivered records with updated ones. This approach ensures data accuracy by reflecting corrections directly in place. @@ -59,10 +54,9 @@ Data Generators typically use two main provisioning styles/mechanisms when deliv ## Finalized Invoice and Closed Billing Period -> **TODO:** Mention/address in upcoming Correction Handling attribute > See [FR #Add invoice-level correction handling rules](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/issues/1013) -While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **“closed”** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. +While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **"closed"** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. To address these **gaps** in this scenario, we assume the following: From f0d658bfac909a6c4b74ba32e3972dd6a31deeb0 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:49:04 +0200 Subject: [PATCH 10/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 0543abd70..7e70710ea 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,11 +1,17 @@ # Correction Handling +## Overview + +### Terminology and Purpose + Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously invoiced billing period or an uninvoiced billing period (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. +### Business Requirements and Invoice Finalization and Billing Period Closure + Accurate correction handling is essential for a range of business-critical processes, including but not limited to: * Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). @@ -17,8 +23,12 @@ Once an invoice is issued, it serves as the authoritative financial document and A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +### Data Delivery Mechanisms and Correction Styles + FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. +#### Replacement Mechanism + In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. Subsequent datasets in the Replacement mechanism may include the following: @@ -30,6 +40,8 @@ Subsequent datasets in the Replacement mechanism may include the following: Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Updated or omissions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. +#### Append-only Mechanism + In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. Corrections in the Append-only mechanism are represented exclusively by adding new records. @@ -39,6 +51,8 @@ Within the Append-only mechanism, two correction styles are commonly used: * Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. * Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. +### Data Integrity and Auditability + To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. All correction charge records adhere to the correction handling requirements listed below. From 724aad4d86a5c72370ae031f186f007645507864 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:49:57 +0200 Subject: [PATCH 11/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 7e70710ea..5fa8fb346 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,7 +2,7 @@ ## Overview -### Terminology and Purpose +### Definition and Scope of Corrections Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. @@ -10,7 +10,7 @@ Correction Handling attribute defines how updates to previously provided charge Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. -### Business Requirements and Invoice Finalization and Billing Period Closure +### Business Requirements and Constraints in Invoiced Billing Periods Accurate correction handling is essential for a range of business-critical processes, including but not limited to: @@ -23,7 +23,7 @@ Once an invoice is issued, it serves as the authoritative financial document and A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -### Data Delivery Mechanisms and Correction Styles +### Delivery Mechanisms and Correction Representation FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. From 077459c888919c25b4595b50ae54b21ca852a694 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:58:11 +0200 Subject: [PATCH 12/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 5fa8fb346..62ddcb970 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -51,12 +51,10 @@ Within the Append-only mechanism, two correction styles are commonly used: * Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. * Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. -### Data Integrity and Auditability +### Data Integrity To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. -All correction charge records adhere to the correction handling requirements listed below. - ## Attribute ID CorrectionHandling @@ -71,6 +69,8 @@ Defines how updates to previously provided charge records are represented in FOC ## Requirements +All corrections adhere to the following requirements: + * Invoice MUST be considered finalized and immutable once issued. * Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: * Charge record MUST be considered finalized and immutable. From 46feb48fb7eef0630f37c50ef2758d60587ba6db Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 16:33:33 +0200 Subject: [PATCH 13/71] FOCUS #962: Correction Handling attribute - requirements breakdown --- .../attributes/correction_handling.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 62ddcb970..e005a9bab 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -65,24 +65,31 @@ Correction Handling ## Description -Defines how updates to previously provided charge records are represented in FOCUS datasets. +Defines how updates to previously provided [*charges*](#glossary:charge) are represented in FOCUS datasets. ## Requirements All corrections adhere to the following requirements: +### Invoice and Billing Period Requirements + * Invoice MUST be considered finalized and immutable once issued. -* Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: - * Charge record MUST be considered finalized and immutable. - * Charge record MUST NOT be updated, deleted, or omitted. +* Once the associated invoice is issued, each underlying *charges* adheres to the following additional requirements: + * *Charge* MUST be considered finalized and immutable. + * *Charge* MUST NOT be updated, deleted, or omitted. * Billing period MUST be considered invoiced and closed once all invoices for that period are issued. -* Additional charge records MUST NOT be associated with an invoice once it is issued. -* Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. +* Additional *charges* MUST NOT be associated with an invoice once it is issued. +* Additional *charges* MUST NOT be associated with a billing period once it is invoiced and closed. + +### General Requirements for Corrections * Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. * Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. +* ChargeClass MUST be null when the *charge* does not represent a correction to a previously invoiced *billing period*. * Correction MUST NOT result in double counting of any cost- or quantity-related values. +### Constraints in an Invoiced Billing Period + * Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. @@ -90,10 +97,15 @@ All corrections adhere to the following requirements: * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. +### Constraints in the Replacement Mechanism + * Replacement mechanism adheres to the following additional requirements: * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. + +### Constraints in the Append-only Mechanism + * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. * All corrections MUST be represented exclusively by adding new records. From 4d411ccb2f8053a8c784ed0566ff1369754aaa32 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 19 Aug 2025 16:07:14 +0200 Subject: [PATCH 14/71] FOCUS #962: Correction Handling attribute spec --- specification/attributes/attributes.mdpp | 1 + .../attributes/correction_handling.md | 88 +++++++++++++++++++ .../attributes/correction_handling.md | 72 +++++++++++++++ 3 files changed, 161 insertions(+) create mode 100644 specification/attributes/correction_handling.md create mode 100644 supporting_content/attributes/correction_handling.md diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index d3b72cc96..c269665b0 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -6,6 +6,7 @@ for data granularity, recency, frequency, etc. Requirements defined in attribute [FinOps capabilities][FODOFC] accurately using a standard set of instructions regardless of the origin of the data. !INCLUDE "column_handling.md",1 +!INCLUDE "correction_handling.md",1 !INCLUDE "currency_format.md",1 !INCLUDE "datetime_format.md",1 !INCLUDE "discount_handling.md",1 diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md new file mode 100644 index 000000000..d92c5a269 --- /dev/null +++ b/specification/attributes/correction_handling.md @@ -0,0 +1,88 @@ +# Correction Handling + +Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. + +**Terminology Note:** Correction (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections to previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to all previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. + +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors or post-processing adjustments, etc. + +Accurate correction handling is essential for a range of business-critical processes, including but not limited to: + +* Temporal accuracy - capturing both when the charge was incurred (reflected in the charge periods, i.e., Charge Period Start and Charge Period End columns) and when the correction was invoiced (reflected in the billing period, i.e., Billing Period Start and Billing Period End columns). +* Financial and legal integrity - preserving original charge records associated with finalized invoices and recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. +* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). +* Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. + +## Provisioning Styles + +To ensure consistent interpretation and correct implementation, it is important to clarify how Correction Handling relates to other foundational concepts such as data delivery styles and invoice finalization. + +Data generators typically deliver cost and usage records using one of two models: + +* Replacement: + * Previously delivered records are overwritten with updated versions, omitted if obsolete, or supplemented with additional records. This model assumes consumers will discard prior versions and always use the latest available data. + * Previously delivered records may be overwritten with updated versions, omitted when obsolete, or supplemented with additional records to represent related corrections (e.g., refunds). Multiple records for the same dimensions may coexist, so consumers should handle such cases appropriately. This model does not provide a built-in audit trail; consumers must maintain historical snapshots independently to enable auditability. +* Append-only: + * To correct the original, one or more new records are added without modifying existing ones. Corrections are represented by adding new rows, and previously delivered rows remain unchanged. + * Corrections are implemented by adding one or more new records without modifying or deleting any previously delivered records. Duplicate records are explicitly disallowed. All original and correction records are preserved as distinct entries, inherently supporting a built-in audit trail. + +FOCUS supports both Replacement and Append-only delivery styles for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only append-only modeling is permitted. This ensures financial integrity and enables accurate audit trails. + +There are two standard approaches to modeling corrections in append-only delivery model: + +* In ledger-style correction, adjustments are modeled by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. + +## Invoice Finalization + +A billing period is considered closed once all invoices for that period are finalized. After that point, the original invoice and its records must remain immutable. Corrections to such periods must not overwrite existing records and must follow special provisioning rules (see below). + +If a correction is applied to a charge from a closed billing period, the corrected record must: + +* The correction MUST NOT replace or omit the original record. +* Be assigned to a different invoice (i.e., not the one originally associated with the charge). +* Have BillingPeriodStart and BillingPeriodEnd values that correspond to the open billing period in which the correction is issued. +* Preserve the original ChargePeriodStart and ChargePeriodEnd values to indicate when the corrected cost was actually incurred. + +This dual treatment—distinguishing the charge period from the billing period—allows cost data consumers to understand both the historical intent and the current accounting context for each correction. + +## Attribute ID + +CorrectionHandling + +## Attribute Name + +Correction Handling + +## Description + +Defines how updates to previously provided charge records are represented in FOCUS datasets. + +## Requirements + +> WORK IN PROGRESS !!! + +All corrections/changes to previously provided charge records in FOCUS dataset MUST follow the correction handling requirements listed below. + +* Corrections to charges in previously closed billing periods MUST satisfy the following: + * The correction MUST NOT replace or omit the original record. + * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. + * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued. + * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time interval in which the charge occurred. + * ChargeClass MUST be set to "Correction". +* Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). +* Etc. + +## Exceptions + +> WORK IN PROGRESS !!! + +Potential exceptions, to be discussed: + +* Restatement of Dimensions Not on Original Invoice: Determine whether exceptions will be allowed for corrections that modify only non-invoiced dimensions. +* Technical issues mentioned by Riley. +* Replacment over Append-only explicitly specified by the end-user. + +## Introduced (version) + +1.3 diff --git a/supporting_content/attributes/correction_handling.md b/supporting_content/attributes/correction_handling.md new file mode 100644 index 000000000..6d30c965a --- /dev/null +++ b/supporting_content/attributes/correction_handling.md @@ -0,0 +1,72 @@ +# Correction handling + +## Prevent Replacement After Invoice Finalization (and Billing Period Closure) + +> **TODO:** Mention/address in upcoming Correction Handling attribute + +***Note:*** *See S-1: Itemized Correction Scenarios with Cost Calculation Integrity Respected - S-1.1 and S-1.2 in particular* + +We should prevent the use of the Replacement provisioning style once an invoice has been finalized and the corresponding billing period closed. + +Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections — and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: + +- A finalized invoice is considered legally issued and immutable. +- The associated billing period is closed, prohibiting any modifications or overwriting of previously delivered records. + +Therefore, only append-only provisioning styles (such as ledger-style increments/decrements or accounting-style reversals followed by corrected entries) should be permitted for handling Post-Invoice Finalization Corrections. + +**Exceptions:** + +- Contributors are encouraged to document any exception to the general rule. + +- Should we allow restating in cases where corrections apply to dimensions that were not included in the original invoice? +Personally, I would prefer not to allow this — but this is currently the only scenario where I can see a possible justification. +- Technical issues mentioned by Riley. +- Explicitly specified by the end-user. + +### Normative Requirements for Post-Invoice Finalization Corrections + +> **TODO:** Mention/address in upcoming Correction Handling attribute +> (Shawn has added numbers to the statements that would become normative requirements in the attribute) + +The following applies to all corrections to a previously closed billing period, i.e., correction charge records provisioned after invoice finalization and billing period closure, but which pertain to activity that occurred during that already invoiced and closed period: + +- **Legal and Procedural Perspective:** + - <<1>> The invoice is considered legally issued and immutable. + - The billing period is considered closed, thereby prohibiting any modifications to or overwriting of the originally invoiced records. + +- **Provisioning perspective**: `x_ExportDateTime = T2` (i.e., the date it became available to the consumer) + +- **Operational Perspective**: All Correction records (Increments and Decrements in case of the Ledger style, Negations and Corrected records in case of Accounting style) pertain to activity that occurred in **May**, so in case of Usage records <<2>> `ChargePeriodStart`/`ChargePeriodEnd` **must reflect the actual usage period** (e.g., `ChargePeriodStart = 2025-05-01`) + +- **Financial Perspective**: The original invoice (e.g., `INV-20250501-20250601`) has already been finalized (issued and sent e.g., as PDF). The May billing period is **considered closed** therefore + - <<3>> `BillingPeriodStart`/`BillingPeriodEnd` **must be equal to or later than** the first **open** billing period (i.e., June 2025 or later) + - <<4>> `InvoiceId` must not match the original invoice (e.g., `INV-20250501-20250601`). + +- **Charge Class:** <<5>> ChargeClass must be set to "Correction". + +## Cost and Usage data Provisioning Styles + +> **TODO:** Mention/address in upcoming Correction Handling attribute + +Data Generators typically use two main provisioning styles/mechanisms when delivering cost and usage data: + +- **Replacement:** Overwrites previously delivered records with updated ones. This approach ensures data accuracy by reflecting corrections directly in place. + +- **Append-only:** Delivers only new records without modifying previously sent data. This approach can be further divided into two subtypes: + - **Ledger-style:** Adds incremental (or decremental) records over time. Corrections are reflected as additional entries where the cost or quantity metrics are adjusted (+/-), while all other dimensions remain identical to the original record. This supports an append-only model but offers limited auditability, as there is typically no explicit reversal. + - **Accounting-style:** Tracks changes explicitly via negative (reversal) entries followed by corrected records. This ensures full auditability and provides a clear historical trail of adjustments. + +## Finalized Invoice and Closed Billing Period + +> **TODO:** Mention/address in upcoming Correction Handling attribute +> See [FR #Add invoice-level correction handling rules](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/issues/1013) + +While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **“closed”** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. + +To address these **gaps** in this scenario, we assume the following: + +- Data Generator (Providers) finalize invoices at some point, marking them as ready for invoice reconciliation. +- A billing period is considered closed once all invoices for that period are finalized. + +***Note:** These information are assumed to be provided not within the cost and usage dataset itself, but in separate, adjacent datasets (e.g., invoice-related datasets). From 11fb6df43be7bcf7b130fd3f7255fb0d5ec85559 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 19 Aug 2025 17:01:56 +0200 Subject: [PATCH 15/71] FOCUS #962: Correction Handling attribute spec --- specification/attributes/correction_handling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index d92c5a269..4c1236dae 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,14 +2,14 @@ Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** Correction (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections to previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to all previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. +**Terminology Note:** The term "Correction" (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections for previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. -Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors or post-processing adjustments, etc. +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors, post-processing adjustments, etc. Accurate correction handling is essential for a range of business-critical processes, including but not limited to: -* Temporal accuracy - capturing both when the charge was incurred (reflected in the charge periods, i.e., Charge Period Start and Charge Period End columns) and when the correction was invoiced (reflected in the billing period, i.e., Billing Period Start and Billing Period End columns). -* Financial and legal integrity - preserving original charge records associated with finalized invoices and recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. +* Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). +* Financial and legal integrity - preserving original charge records associated with finalized invoices while recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. From ed9371bbaf6868927da67016b4c72082e83e71f1 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 20 Aug 2025 16:35:17 +0200 Subject: [PATCH 16/71] FOCUS #962: Correction Handling attribute spec update - work in progress --- .../attributes/correction_handling.md | 47 ++++++++----------- 1 file changed, 20 insertions(+), 27 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 4c1236dae..2d47ab003 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -13,38 +13,34 @@ Accurate correction handling is essential for a range of business-critical proce * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. -## Provisioning Styles +Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -To ensure consistent interpretation and correct implementation, it is important to clarify how Correction Handling relates to other foundational concepts such as data delivery styles and invoice finalization. +A billing period is considered closed once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is closed, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in a closed billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -Data generators typically deliver cost and usage records using one of two models: +FOCUS datasets can be delivered using one of two mechanisms - Replacement or sppend-only. -* Replacement: - * Previously delivered records are overwritten with updated versions, omitted if obsolete, or supplemented with additional records. This model assumes consumers will discard prior versions and always use the latest available data. - * Previously delivered records may be overwritten with updated versions, omitted when obsolete, or supplemented with additional records to represent related corrections (e.g., refunds). Multiple records for the same dimensions may coexist, so consumers should handle such cases appropriately. This model does not provide a built-in audit trail; consumers must maintain historical snapshots independently to enable auditability. -* Append-only: - * To correct the original, one or more new records are added without modifying existing ones. Corrections are represented by adding new rows, and previously delivered rows remain unchanged. - * Corrections are implemented by adding one or more new records without modifying or deleting any previously delivered records. Duplicate records are explicitly disallowed. All original and correction records are preserved as distinct entries, inherently supporting a built-in audit trail. +For the Replacement mechanism, the initial and each subsequent dataset for a billing period provide a complete snapshot of cost and usage data collected for that period up to the time of delivery, with each subsequent dataset reflecting any updates, omissions, or additions since the previous one. This mechanism does not provide a built-in audit trail, so historical snapshots must be maintained separately to support traceability. -FOCUS supports both Replacement and Append-only delivery styles for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only append-only modeling is permitted. This ensures financial integrity and enables accurate audit trails. +In the Replacement mechanism, charge records in subsequent datasets are handled as follows: -There are two standard approaches to modeling corrections in append-only delivery model: +* Unchanged charge records – carried over unchanged from the previously delivered dataset. +* Updated charge records – overwritten with the latest values. +* Additional charge records – new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). +* Omitted charge records – removed from the dataset because they are no longer applicable. -* In ledger-style correction, adjustments are modeled by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. +In the Append-only mechanism, corrections are represented exclusively by appending one or more new records, while previously delivered records remain unchanged. Duplicate records are explicitly disallowed. This mechanism inherently supports a built-in audit trail, since all original and correction records are retained as distinct entries. + +When the Append-only delivery mechanism is used, there are two common styles for modeling corrections: -## Invoice Finalization +* In ledger-style correction, corrections are represented by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. -A billing period is considered closed once all invoices for that period are finalized. After that point, the original invoice and its records must remain immutable. Corrections to such periods must not overwrite existing records and must follow special provisioning rules (see below). +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a charge record that matches all fields of the original except for the numeric values, which are inverted, followed by a new record with the corrected values. This model preserves a full correction history and is preferred when transparency and traceability are required. -If a correction is applied to a charge from a closed billing period, the corrected record must: +* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. -* The correction MUST NOT replace or omit the original record. -* Be assigned to a different invoice (i.e., not the one originally associated with the charge). -* Have BillingPeriodStart and BillingPeriodEnd values that correspond to the open billing period in which the correction is issued. -* Preserve the original ChargePeriodStart and ChargePeriodEnd values to indicate when the corrected cost was actually incurred. +FOCUS supports both Replacement and Append-only cost and usage data delivery mechanisms for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only Append-only delivery mechanism is permitted. This ensures financial integrity and enables accurate audit trails. -This dual treatment—distinguishing the charge period from the billing period—allows cost data consumers to understand both the historical intent and the current accounting context for each correction. +All correction charge records adhere to the correction handling requirements listed below. ## Attribute ID @@ -62,16 +58,13 @@ Defines how updates to previously provided charge records are represented in FOC > WORK IN PROGRESS !!! -All corrections/changes to previously provided charge records in FOCUS dataset MUST follow the correction handling requirements listed below. - -* Corrections to charges in previously closed billing periods MUST satisfy the following: +* Corrections to charges in previously closed billing periods adhere to the following additional requirements: * The correction MUST NOT replace or omit the original record. * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. - * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued. - * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time interval in which the charge occurred. + * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued (correspond to the open billing period in which the correction is issued). + * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time window in which the charge occurred (cost was actually incurred). * ChargeClass MUST be set to "Correction". * Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). -* Etc. ## Exceptions From 35d26a6a77313e482fc22cf65a75885807dbf459 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 00:38:40 +0200 Subject: [PATCH 17/71] FOCUS #962: Correction Handling attribute spec update - work in progress --- .../attributes/correction_handling.md | 65 ++++++++++++------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 2d47ab003..75f1212d4 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,9 +2,9 @@ Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** The term "Correction" (uppercase) refers specifically to the allowed value in the Charge Class column, which is limited to corrections for previously invoiced billing periods. In contrast, the Correction Handling attribute covers corrections (lowercase) to previously provided charge records, including those that occurred in previously invoiced, uninvoiced, or current billing periods. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. -Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing usage data, rounding errors, post-processing adjustments, etc. +Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. Accurate correction handling is essential for a range of business-critical processes, including but not limited to: @@ -15,30 +15,31 @@ Accurate correction handling is essential for a range of business-critical proce Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -A billing period is considered closed once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is closed, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in a closed billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -FOCUS datasets can be delivered using one of two mechanisms - Replacement or sppend-only. +FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. -For the Replacement mechanism, the initial and each subsequent dataset for a billing period provide a complete snapshot of cost and usage data collected for that period up to the time of delivery, with each subsequent dataset reflecting any updates, omissions, or additions since the previous one. This mechanism does not provide a built-in audit trail, so historical snapshots must be maintained separately to support traceability. +In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, and therefore historical snapshots must be retained externally to support traceability. -In the Replacement mechanism, charge records in subsequent datasets are handled as follows: +Subsequent datasets in the Replacement mechanism may include the following: -* Unchanged charge records – carried over unchanged from the previously delivered dataset. -* Updated charge records – overwritten with the latest values. -* Additional charge records – new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). -* Omitted charge records – removed from the dataset because they are no longer applicable. +* Unchanged records are carried over. +* Updated records overwrite previous values. +* Additional records supplement previously delivered data. +* Omitted records are removed if no longer applicable. -In the Append-only mechanism, corrections are represented exclusively by appending one or more new records, while previously delivered records remain unchanged. Duplicate records are explicitly disallowed. This mechanism inherently supports a built-in audit trail, since all original and correction records are retained as distinct entries. +Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Modifications or deletions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. -When the Append-only delivery mechanism is used, there are two common styles for modeling corrections: +In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. -* In ledger-style correction, corrections are represented by adding one or more records that increment or decrement the cost or usage quantity. These records MUST retain all non-numeric fields (e.g., service, region, usage type) identical to the original. There is no explicit reversal of the original record; only the net effect is reflected. This method reduces data volume but provides limited audit transparency. +Corrections in the Append-only mechanism are represented exclusively by adding new records, and duplicate entries are explicitly disallowed. -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a charge record that matches all fields of the original except for the numeric values, which are inverted, followed by a new record with the corrected values. This model preserves a full correction history and is preferred when transparency and traceability are required. +Within the Append-only mechanism, two correction styles are commonly used: -* In contrast, accounting-style correction uses a two-step representation: the original record is first reversed using a row with negative values for cost and quantity, and then followed by a new record with the corrected values. The reversal MUST match the original in all fields, except for the negated numeric amounts. This model preserves a full correction history and is RECOMMENDED when transparency and traceability are required. +* Ledger-style correction: Adds records that adjust selected cost- and quantity-related columns by incrementing or decrementing their values. All other columns remain unchanged. No explicit reversal is performed. This style offers limited audit transparency. +* Accounting-style correction: Uses a two-step representation. First, the original record is reversed using a charge, in which all cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original. This reversal charge is typically followed by a new record with the corrected values, although in some cases only the reversal is provided. This style preserves full correction history. -FOCUS supports both Replacement and Append-only cost and usage data delivery mechanisms for most use cases. However, for corrections to charges originally incurred in previously invoiced billing periods, only Append-only delivery mechanism is permitted. This ensures financial integrity and enables accurate audit trails. +To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. All correction charge records adhere to the correction handling requirements listed below. @@ -58,13 +59,27 @@ Defines how updates to previously provided charge records are represented in FOC > WORK IN PROGRESS !!! -* Corrections to charges in previously closed billing periods adhere to the following additional requirements: - * The correction MUST NOT replace or omit the original record. - * The corrected row(s) MUST be assigned to a different InvoiceId than the one associated with the original record. - * The BillingPeriodStart and BillingPeriodEnd MUST reflect the current open billing period in which the correction is being issued (correspond to the open billing period in which the correction is issued). - * The ChargePeriodStart and ChargePeriodEnd MUST retain the original time window in which the charge occurred (cost was actually incurred). - * ChargeClass MUST be set to "Correction". -* Providers MUST clearly document which provisioning and correction styles are in use (Replacement, Ledger-style, Accounting-style). +* Data Generator MUST publish the provisioning and correction styles in use (Replacement, Ledger-style, Accounting-style) within their respective documentation. +* Correction MUST NOT result in double counting of any cost- or quantity-related values. + +### Invoice and Billing Period + +* Invoice MUST be considered finalized and immutable once issued. +* Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: + * Charge record MUST be considered finalized and immutable. + * Charge record MUST NOT be updated, deleted, or omitted. +* Additional charge records MUST NOT be associated with an invoice once it is issued. +* Billing period MUST be considered invoiced and closed once all invoices for that period are issued. +* Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. + +### Corrections to charges from a previously invoiced and closed billing period + +* Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: + * ChargeClass MUST be "Correction". + * Correction MUST NOT replace or omit the original record. + * Corrected row(s) MUST be assigned to a different `InvoiceId` than the original record. + * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. + * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. ## Exceptions @@ -76,6 +91,10 @@ Potential exceptions, to be discussed: * Technical issues mentioned by Riley. * Replacment over Append-only explicitly specified by the end-user. +* Replacement provisioning style MAY be applied, even for charges included in datasets associated with previously invoiced billing periods, when xplicitly requested by the end-user. +* Providers MAY apply the Replacement provisioning style instead of Append-only, even for charges included in datasets associated with previously invoiced billing periods, provided that updates affect only non-invoiced dimensions and the integrity of finalized invoices is preserved. +* (TODO) Technical issues mentioned by Riley. + ## Introduced (version) 1.3 From af9b7cbc91b2bef2ebaecfbbf32e0695573840b2 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Thu, 21 Aug 2025 12:09:13 -0700 Subject: [PATCH 18/71] linter fix --- specification/attributes/correction_handling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 75f1212d4..317348700 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -23,10 +23,10 @@ In the Replacement mechanism, each dataset provides a complete snapshot of cost Subsequent datasets in the Replacement 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. +* Unchanged charge records - carried over unchanged from the previously delivered dataset. +* Updated charge records - overwritten with the latest values. +* Additional charge records - new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). +* Omitted charge records - removed from the dataset because they are no longer applicable. Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Modifications or deletions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. From 84fad39ae96e7f719f85df9721f86ad2276517fc Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 01:28:05 +0200 Subject: [PATCH 19/71] FOCUS #962: Correction Handling attribute spec update - supporting content scrub --- specification/attributes/correction_handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 317348700..4e7b254d6 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -15,7 +15,7 @@ Accurate correction handling is essential for a range of business-critical proce Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. -A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. From ababbc8eeae34af2ea379eec20bea2b7c04b2a19 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 01:39:45 +0200 Subject: [PATCH 20/71] FOCUS #962: Correction Handling attribute - ignore --- specification/attributes/correction_handling.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 4e7b254d6..10d04b3e3 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,5 +1,7 @@ # Correction Handling +Test. + Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. From be31cd967eaf2acc741f84a434702fdde2eeb825 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 14:07:40 +0200 Subject: [PATCH 21/71] FOCUS #962: Correction Handling attribute spec update --- .../attributes/correction_handling.md | 51 ++++++++----------- 1 file changed, 22 insertions(+), 29 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 10d04b3e3..116ecf571 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,10 +1,8 @@ # Correction Handling -Test. - Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which includes charge records used to correct cost and usage data originally associated with a previously invoiced billing period, an uninvoiced billing period, or the current billing period, as well as the omission of a previously provisioned charge if it is no longer applicable. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously invoiced billing period or an uninvoiced billing period (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. @@ -21,7 +19,7 @@ A billing period is considered invoiced (or closed) once all invoices for that p FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. -In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, and therefore historical snapshots must be retained externally to support traceability. +In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. Subsequent datasets in the Replacement mechanism may include the following: @@ -30,16 +28,16 @@ Subsequent datasets in the Replacement mechanism may include the following: * Additional charge records - new entries representing either billing period segments not previously reported, or supplements to segments included in the previously delivered dataset (e.g., refunds or delayed cost and usage data). * Omitted charge records - removed from the dataset because they are no longer applicable. -Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Modifications or deletions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. +Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Updated or omissions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. -Corrections in the Append-only mechanism are represented exclusively by adding new records, and duplicate entries are explicitly disallowed. +Corrections in the Append-only mechanism are represented exclusively by adding new records. Within the Append-only mechanism, two correction styles are commonly used: -* Ledger-style correction: Adds records that adjust selected cost- and quantity-related columns by incrementing or decrementing their values. All other columns remain unchanged. No explicit reversal is performed. This style offers limited audit transparency. -* Accounting-style correction: Uses a two-step representation. First, the original record is reversed using a charge, in which all cost- and quantity-related columns carry values with the opposite sign, while all other columns match the original. This reversal charge is typically followed by a new record with the corrected values, although in some cases only the reversal is provided. This style preserves full correction history. +* Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. +* Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. @@ -59,43 +57,38 @@ Defines how updates to previously provided charge records are represented in FOC ## Requirements -> WORK IN PROGRESS !!! - -* Data Generator MUST publish the provisioning and correction styles in use (Replacement, Ledger-style, Accounting-style) within their respective documentation. -* Correction MUST NOT result in double counting of any cost- or quantity-related values. - -### Invoice and Billing Period - * Invoice MUST be considered finalized and immutable once issued. * Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: * Charge record MUST be considered finalized and immutable. * Charge record MUST NOT be updated, deleted, or omitted. -* Additional charge records MUST NOT be associated with an invoice once it is issued. * Billing period MUST be considered invoiced and closed once all invoices for that period are issued. +* Additional charge records MUST NOT be associated with an invoice once it is issued. * Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. -### Corrections to charges from a previously invoiced and closed billing period +* Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. +* Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. +* Correction MUST NOT result in double counting of any cost- or quantity-related values. * Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. - * Corrected row(s) MUST be assigned to a different `InvoiceId` than the original record. + * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. -## Exceptions - -> WORK IN PROGRESS !!! - -Potential exceptions, to be discussed: +* Replacement mechanism adheres to the following additional requirements: + * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). + * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. + * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. +* Append-only mechanism adheres to the following additional requirements: + * All previously delivered records MUST be retained without modification or deletion. + * All corrections MUST be represented exclusively by adding new records. -* Restatement of Dimensions Not on Original Invoice: Determine whether exceptions will be allowed for corrections that modify only non-invoiced dimensions. -* Technical issues mentioned by Riley. -* Replacment over Append-only explicitly specified by the end-user. +## Exceptions -* Replacement provisioning style MAY be applied, even for charges included in datasets associated with previously invoiced billing periods, when xplicitly requested by the end-user. -* Providers MAY apply the Replacement provisioning style instead of Append-only, even for charges included in datasets associated with previously invoiced billing periods, provided that updates affect only non-invoiced dimensions and the integrity of finalized invoices is preserved. -* (TODO) Technical issues mentioned by Riley. +* Exceptions to the restrictions on issued invoices, invoiced billing periods, and finalized charge records 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) From 52c423a538fc19931faaf73e76eb3bf07b2fa4ca Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 22 Aug 2025 14:19:13 +0200 Subject: [PATCH 22/71] FOCUS #962: Correction Handling attribute supporting content scrub --- .../attributes/correction_handling.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/supporting_content/attributes/correction_handling.md b/supporting_content/attributes/correction_handling.md index 6d30c965a..2d5c2337e 100644 --- a/supporting_content/attributes/correction_handling.md +++ b/supporting_content/attributes/correction_handling.md @@ -2,13 +2,11 @@ ## Prevent Replacement After Invoice Finalization (and Billing Period Closure) -> **TODO:** Mention/address in upcoming Correction Handling attribute - ***Note:*** *See S-1: Itemized Correction Scenarios with Cost Calculation Integrity Respected - S-1.1 and S-1.2 in particular* We should prevent the use of the Replacement provisioning style once an invoice has been finalized and the corresponding billing period closed. -Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections — and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: +Since Replacement relies on overwriting or replacing previously delivered charge records within the original billing period, it inherently conflicts with the Normative Requirements for Post-Invoice Finalization Corrections - and in particular the Legal and Procedural Perspective, which states that once an invoice has been finalized and the corresponding billing period closed: - A finalized invoice is considered legally issued and immutable. - The associated billing period is closed, prohibiting any modifications or overwriting of previously delivered records. @@ -20,14 +18,13 @@ Therefore, only append-only provisioning styles (such as ledger-style increments - Contributors are encouraged to document any exception to the general rule. - Should we allow restating in cases where corrections apply to dimensions that were not included in the original invoice? -Personally, I would prefer not to allow this — but this is currently the only scenario where I can see a possible justification. + *Note: Personally, I would prefer not to allow this.* - Technical issues mentioned by Riley. - Explicitly specified by the end-user. ### Normative Requirements for Post-Invoice Finalization Corrections -> **TODO:** Mention/address in upcoming Correction Handling attribute -> (Shawn has added numbers to the statements that would become normative requirements in the attribute) +> Shawn has added numbers to the statements that would become normative requirements in the attribute The following applies to all corrections to a previously closed billing period, i.e., correction charge records provisioned after invoice finalization and billing period closure, but which pertain to activity that occurred during that already invoiced and closed period: @@ -47,8 +44,6 @@ The following applies to all corrections to a previously closed billing period, ## Cost and Usage data Provisioning Styles -> **TODO:** Mention/address in upcoming Correction Handling attribute - Data Generators typically use two main provisioning styles/mechanisms when delivering cost and usage data: - **Replacement:** Overwrites previously delivered records with updated ones. This approach ensures data accuracy by reflecting corrections directly in place. @@ -59,10 +54,9 @@ Data Generators typically use two main provisioning styles/mechanisms when deliv ## Finalized Invoice and Closed Billing Period -> **TODO:** Mention/address in upcoming Correction Handling attribute > See [FR #Add invoice-level correction handling rules](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/issues/1013) -While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **“closed”** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. +While the FOCUS specification mentions closed billing periods, it currently does not define the process for invoice issuance or billing period closure. It also does not define any explicit **“finalized”** status for invoices, nor a **"closed"** status for billing periods, nor the point at which an invoice is considered finalized or a billing period considered closed. To address these **gaps** in this scenario, we assume the following: From 42d62a5c29b4a3a91c82b76515c39acb15aae4e7 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:49:04 +0200 Subject: [PATCH 23/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 116ecf571..d150709ef 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -1,11 +1,17 @@ # Correction Handling +## Overview + +### Terminology and Purpose + Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously invoiced billing period or an uninvoiced billing period (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. +### Business Requirements and Invoice Finalization and Billing Period Closure + Accurate correction handling is essential for a range of business-critical processes, including but not limited to: * Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). @@ -17,8 +23,12 @@ Once an invoice is issued, it serves as the authoritative financial document and A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +### Data Delivery Mechanisms and Correction Styles + FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. +#### Replacement Mechanism + In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. Subsequent datasets in the Replacement mechanism may include the following: @@ -30,6 +40,8 @@ Subsequent datasets in the Replacement mechanism may include the following: Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Updated or omissions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. +#### Append-only Mechanism + In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. Corrections in the Append-only mechanism are represented exclusively by adding new records. @@ -39,6 +51,8 @@ Within the Append-only mechanism, two correction styles are commonly used: * Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. * Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. +### Data Integrity and Auditability + To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. All correction charge records adhere to the correction handling requirements listed below. From f1bcc7c7ee2c88c1773fbeefc5dac33f393a2a88 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:49:57 +0200 Subject: [PATCH 24/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index d150709ef..7da6ca1bc 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,7 +2,7 @@ ## Overview -### Terminology and Purpose +### Definition and Scope of Corrections Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. @@ -10,7 +10,7 @@ Correction Handling attribute defines how updates to previously provided charge Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. -### Business Requirements and Invoice Finalization and Billing Period Closure +### Business Requirements and Constraints in Invoiced Billing Periods Accurate correction handling is essential for a range of business-critical processes, including but not limited to: @@ -23,7 +23,7 @@ Once an invoice is issued, it serves as the authoritative financial document and A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. -### Data Delivery Mechanisms and Correction Styles +### Delivery Mechanisms and Correction Representation FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. From 64ae9dd3ba32a44a4ed12daac2e6c5352bcc3f5b Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 15:58:11 +0200 Subject: [PATCH 25/71] FOCUS #962: Correction Handling attribute - adding subtitles --- specification/attributes/correction_handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 7da6ca1bc..9acd67ef4 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -51,12 +51,10 @@ Within the Append-only mechanism, two correction styles are commonly used: * Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. * Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. -### Data Integrity and Auditability +### Data Integrity To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. -All correction charge records adhere to the correction handling requirements listed below. - ## Attribute ID CorrectionHandling @@ -71,6 +69,8 @@ Defines how updates to previously provided charge records are represented in FOC ## Requirements +All corrections adhere to the following requirements: + * Invoice MUST be considered finalized and immutable once issued. * Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: * Charge record MUST be considered finalized and immutable. From fe9895be01c6016ab607ce812caafdf7b869dfe5 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 2 Sep 2025 16:33:33 +0200 Subject: [PATCH 26/71] FOCUS #962: Correction Handling attribute - requirements breakdown --- .../attributes/correction_handling.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 9acd67ef4..a2b3fa002 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -65,24 +65,31 @@ Correction Handling ## Description -Defines how updates to previously provided charge records are represented in FOCUS datasets. +Defines how updates to previously provided [*charges*](#glossary:charge) are represented in FOCUS datasets. ## Requirements All corrections adhere to the following requirements: +### Invoice and Billing Period Requirements + * Invoice MUST be considered finalized and immutable once issued. -* Once the associated invoice is issued, each underlying charge record adheres to the following additional requirements: - * Charge record MUST be considered finalized and immutable. - * Charge record MUST NOT be updated, deleted, or omitted. +* Once the associated invoice is issued, each underlying *charges* adheres to the following additional requirements: + * *Charge* MUST be considered finalized and immutable. + * *Charge* MUST NOT be updated, deleted, or omitted. * Billing period MUST be considered invoiced and closed once all invoices for that period are issued. -* Additional charge records MUST NOT be associated with an invoice once it is issued. -* Additional charge records MUST NOT be associated with a billing period once it is invoiced and closed. +* Additional *charges* MUST NOT be associated with an invoice once it is issued. +* Additional *charges* MUST NOT be associated with a billing period once it is invoiced and closed. + +### General Requirements for Corrections * Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. * Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. +* ChargeClass MUST be null when the *charge* does not represent a correction to a previously invoiced *billing period*. * Correction MUST NOT result in double counting of any cost- or quantity-related values. +### Constraints in an Invoiced Billing Period + * Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. @@ -90,10 +97,15 @@ All corrections adhere to the following requirements: * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. +### Constraints in the Replacement Mechanism + * Replacement mechanism adheres to the following additional requirements: * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. + +### Constraints in the Append-only Mechanism + * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. * All corrections MUST be represented exclusively by adding new records. From 45d1219453fe318d27683d32ba3e9e4f5f30f444 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 16 Sep 2025 11:43:37 +0200 Subject: [PATCH 27/71] FOCUS #962: correction-handling-attribute - temp minimum alignment with matt_cowsert/1082-invoice-handling-requirements --- specification/attributes/attributes.mdpp | 1 + specification/attributes/invoice_handling.md | 30 +++++++++++++++++++ .../datasets/cost_and_usage/dataset.md | 1 + 3 files changed, 32 insertions(+) create mode 100644 specification/attributes/invoice_handling.md diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index c1545a26c..37ab99736 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -7,6 +7,7 @@ Attributes are requirements that apply either across a [*FOCUS dataset*](#glossa !INCLUDE "currency_format.md",1 !INCLUDE "datetime_format.md",1 !INCLUDE "discount_handling.md",1 +!INCLUDE "invoice_handling.md",1 !INCLUDE "key_value_format.md",1 !INCLUDE "null_handling.md",1 !INCLUDE "numeric_format.md",1 diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md new file mode 100644 index 000000000..959687246 --- /dev/null +++ b/specification/attributes/invoice_handling.md @@ -0,0 +1,30 @@ +# 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. + +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. + +## Attribute ID + +InvoiceHandling + +## Attribute Name + +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. + +## Requirements + +* All costs that appear on an invoice MUST be included in the FOCUS Cost and Usage dataset. +* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. + +## Exceptions + +None + +## Introduced (version) + +1.3 diff --git a/specification/datasets/cost_and_usage/dataset.md b/specification/datasets/cost_and_usage/dataset.md index 47f39b2ce..aa79521cd 100644 --- a/specification/datasets/cost_and_usage/dataset.md +++ b/specification/datasets/cost_and_usage/dataset.md @@ -77,6 +77,7 @@ The CostAndUsage dataset adheres to the following requirements: * CostAndUsage MUST conform to [ColumnHandling](#columnhandling) requirements. * CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [NullHandling](#nullhandling) requirements. +* CostAndUsage MUST conform to [InvoiceHandling](#invoicehandling) requirements.
Dataset ID
From 296c5c0185abea289eaf5f489e860abb55f25944 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 16 Sep 2025 12:17:12 +0200 Subject: [PATCH 28/71] FOCUS #962: correction-handling-attribute - cost and usage dataset requirements update --- specification/datasets/cost_and_usage/dataset.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/datasets/cost_and_usage/dataset.md b/specification/datasets/cost_and_usage/dataset.md index aa79521cd..00afea17d 100644 --- a/specification/datasets/cost_and_usage/dataset.md +++ b/specification/datasets/cost_and_usage/dataset.md @@ -75,6 +75,7 @@ None The CostAndUsage dataset adheres to the following requirements: * CostAndUsage MUST conform to [ColumnHandling](#columnhandling) requirements. +* CostAndUsage MUST conform to [CorrectionHandling](#correctionhandling) requirements. * CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [NullHandling](#nullhandling) requirements. * CostAndUsage MUST conform to [InvoiceHandling](#invoicehandling) requirements. From 7ce3459d79aab490d9f98db78a3d9c7c2ea3fd29 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 16 Sep 2025 12:34:07 +0200 Subject: [PATCH 29/71] FOCUS #962-correction-handling-attribute: relocating AS-IS invoice and billing period content from correction-handling to invoice-handling --- .../attributes/correction_handling.md | 25 ------------------- specification/attributes/invoice_handling.md | 11 ++++++++ 2 files changed, 11 insertions(+), 25 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index e005a9bab..46e147aaf 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -19,10 +19,6 @@ Accurate correction handling is essential for a range of business-critical proce * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. -Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. - -A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. - ### Delivery Mechanisms and Correction Representation FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. @@ -71,41 +67,20 @@ Defines how updates to previously provided [*charges*](#glossary:charge) are rep All corrections adhere to the following requirements: -### Invoice and Billing Period Requirements - -* Invoice MUST be considered finalized and immutable once issued. -* Once the associated invoice is issued, each underlying *charges* adheres to the following additional requirements: - * *Charge* MUST be considered finalized and immutable. - * *Charge* MUST NOT be updated, deleted, or omitted. -* Billing period MUST be considered invoiced and closed once all invoices for that period are issued. -* Additional *charges* MUST NOT be associated with an invoice once it is issued. -* Additional *charges* MUST NOT be associated with a billing period once it is invoiced and closed. - -### General Requirements for Corrections - * Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. * Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. * ChargeClass MUST be null when the *charge* does not represent a correction to a previously invoiced *billing period*. * Correction MUST NOT result in double counting of any cost- or quantity-related values. - -### Constraints in an Invoiced Billing Period - * Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. - -### Constraints in the Replacement Mechanism - * Replacement mechanism adheres to the following additional requirements: * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. - -### Constraints in the Append-only Mechanism - * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. * All corrections MUST be represented exclusively by adding new records. diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 959687246..c2d0acac5 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,6 +4,10 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. +Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. + +A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. + ## Attribute ID InvoiceHandling @@ -19,6 +23,13 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Requirements * All costs that appear on an invoice MUST be included in the FOCUS Cost and Usage dataset. +* Invoice MUST be considered finalized and immutable once issued. +* Billing period MUST be considered invoiced and closed once all invoices for that period are issued. +* Once the associated invoice is issued, each underlying *charge* adheres to the following additional requirements: + * *Charge* MUST be considered finalized and immutable. + * *Charge* MUST NOT be updated, deleted, or omitted. +* Additional *charges* MUST NOT be associated with an invoice once it is issued. +* Additional *charges* MUST NOT be associated with a billing period once it is invoiced and closed. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. ## Exceptions From e0ca6d06420de22711b9520df19a62f1aa90a494 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 16 Sep 2025 13:42:31 +0200 Subject: [PATCH 30/71] FOCUS #962-correction-handling-attribute: Correction Handling attribute update --- specification/attributes/correction_handling.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 46e147aaf..f6ed151c2 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -21,13 +21,13 @@ Accurate correction handling is essential for a range of business-critical proce ### Delivery Mechanisms and Correction Representation -FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. +FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. These mechanisms are not mutually exclusive and hybrid implementations are common, allowing Data Generators to meet specific delivery and auditability requirements. #### Replacement Mechanism -In the Replacement mechanism, each dataset provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. Subsequent datasets typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. +In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. -Subsequent datasets in the Replacement mechanism may include the following: +Subsequent dataset artifacts in the Replacement mechanism may include the following: * Unchanged records are carried over. * Updated records overwrite previous values. @@ -38,7 +38,7 @@ Corrections in the Replacement mechanism are modeled through updates, additions, #### Append-only Mechanism -In the Append-only mechanism, each dataset appends new records without modifying or removing previously delivered ones. This mechanism inherently supports auditability, as all original and correction records are retained. +In the Append-only mechanism, each 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. Corrections in the Append-only mechanism are represented exclusively by adding new records. From e8a14932bc34f8183e6dde6da79c02a1a3c09110 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 16 Sep 2025 16:26:34 +0200 Subject: [PATCH 31/71] FOCUS #962-correction-handling-attribute: relocating AS-IS Exceptions from correction-handling to invoice-handling --- specification/attributes/correction_handling.md | 4 +--- specification/attributes/invoice_handling.md | 4 +++- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index f6ed151c2..9790f6512 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -87,9 +87,7 @@ All corrections adhere to the following requirements: ## Exceptions -* Exceptions to the restrictions on issued invoices, invoiced billing periods, and finalized charge records 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. +None ## Introduced (version) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index c2d0acac5..e7431fd54 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -34,7 +34,9 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Exceptions -None +* Exceptions to the restrictions on issued invoices, invoiced billing periods, and finalized charge records 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) From f518a9f30f684749c2fcf6923a6b96c467c3a867 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 23 Sep 2025 14:52:37 +0200 Subject: [PATCH 32/71] FOCUS #962-correction-handling-attribute: updates to invoice handling and glossary --- specification/attributes/invoice_handling.md | 28 +++++++++++++------- specification/glossary.md | 4 +++ 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index e7431fd54..3a236fdf7 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,9 +4,9 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. -Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. All charge records associated with an issued invoice are also considered finalized and must remain unchanged (i.e., corrections to finalized charge records, whether as updates, deletions or omissions, are not permitted). Furthermore, no additional charge records may be associated with an invoice once it has been issued. This ensures that issued invoices and their underlying charge records remain immutable for financial, auditing, and compliance purposes. +Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, deletions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, deletions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. -A billing period is considered invoiced (or closed) once all invoices for that period have been issued and all charge records for that period are finalized. After a billing period is invoiced, no new charge records may be associated with it, and all previously finalized charge records remain unchanged. Any necessary corrections to charges originally incurred in an invoiced billing period must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This provides a clear temporal boundary between billing cycles, preserving immutability while still allowing corrections to be tracked transparently in later billing periods. +For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. ## Attribute ID @@ -22,19 +22,27 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Requirements -* All costs that appear on an invoice MUST be included in the FOCUS Cost and Usage dataset. +* All costs that appear on an invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. +* Invoice Issuer MUST document all metrics and dimensions presented on the invoice and included in Invoice Reconciliation. +* Invoice Reconciliation MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. +* Invoice Issuer MUST perform internal invoice reconciliation before invoice issuance. * Invoice MUST be considered finalized and immutable once issued. -* Billing period MUST be considered invoiced and closed once all invoices for that period are issued. -* Once the associated invoice is issued, each underlying *charge* adheres to the following additional requirements: - * *Charge* MUST be considered finalized and immutable. - * *Charge* MUST NOT be updated, deleted, or omitted. -* Additional *charges* MUST NOT be associated with an invoice once it is issued. -* Additional *charges* MUST NOT be associated with a billing period once it is invoiced and closed. +* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) MUST NOT be applied if they would impact reconciled invoice data. +* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback unless explicitly requested by the end-user. +* Invoice Issuer MUST document how to identify an invoiced (closed) billing period. +* Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. +* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed unless explicitly requested by the end-user. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. ## Exceptions -* Exceptions to the restrictions on issued invoices, invoiced billing periods, and finalized charge records MAY apply in the following cases: +* Informational line items that have zero monetary impact and are included solely for transparency MAY be excluded. Examples include: + * Free tier usage tracking with $0.00 charges + * Breakdowns of bundled services where only the bundle total is billed + * Tax exemption notifications + * SLA credit details when the credit is already applied to the charged amount +* If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. +* Exceptions to the restrictions on issued invoices and invoiced billing periods 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. diff --git a/specification/glossary.md b/specification/glossary.md index 3e69805aa..d0ed3466a 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -104,6 +104,10 @@ The collection of datasets are designed to provide billing insight, additional c A Date/Time Format value that is contained within the beginning bound of a time period. +Invoice Reconciliation + +The process of ensuring that all financial metrics and dimensions presented on an invoice are fully aligned with the underlying cost and usage data associated with that invoice. + Interruptible A category of compute resources that can be paused or terminated by the CSP within certain criteria, often advertised at reduced unit pricing when compared to the equivalent non-interruptible resource. From 6b70ba778f68d50f9b07c7fb8b0232dda67c6c21 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 23 Sep 2025 16:27:26 +0200 Subject: [PATCH 33/71] FOCUS #962-correction-handling-attribute: updates to correction handling --- specification/attributes/correction_handling.md | 12 +++++++----- specification/attributes/invoice_handling.md | 6 +++--- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 9790f6512..47f73d92c 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -25,7 +25,7 @@ FOCUS supports two cost and usage data delivery mechanisms: Replacement and Appe #### Replacement Mechanism -In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. For uninvoiced billing periods (including both previous and current) this mechanism lacks a built-in audit trail, as records may be updated or omitted. To support traceability in uninvoiced billing periods, the Replacement mechanism should support optional external retention of historical snapshots. For invoiced billing periods, auditability is ensured through immutable finalized records and correction handling rules that prohibit updates, deletions, or omissions. +In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, as records may be updated or omitted. The Replacement mechanism should support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. For invoiced billing periods, auditability is ensured through correction handling rules that prohibit updates, deletions, or omissions to charges associated with an issued invoice if they would impact reconciled invoice data. Subsequent dataset artifacts in the Replacement mechanism may include the following: @@ -34,7 +34,7 @@ Subsequent dataset artifacts in the Replacement mechanism may include the follow * Additional records supplement previously delivered data. * Omitted records are removed if no longer applicable. -Corrections in the Replacement mechanism are modeled through updates, additions, or omissions relative to the previous snapshot — with the restriction that corrections to charges originally incurred in previously invoiced billing periods must be represented exclusively through the addition of new records. Updated or omissions of finalized records are not allowed, as they would compromise the immutability of issued invoices and the integrity of audit trails. +Corrections to charges associated with an issued invoice that impact reconciled invoice data must be represented exclusively through the addition of new records associated with a subsequent open billing period, with the charge period indicating when the cost was incurred. #### Append-only Mechanism @@ -71,15 +71,17 @@ All corrections adhere to the following requirements: * Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. * ChargeClass MUST be null when the *charge* does not represent a correction to a previously invoiced *billing period*. * Correction MUST NOT result in double counting of any cost- or quantity-related values. -* Corrections to charges from a previously invoiced and closed billing period adhere to the following additional requirements: +* Corrections to charges associated with an issued invoice that impact *reconciled invoice* data adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. +* Corrections to charges associated with an issued invoice that do not impact *reconciled invoice* data but do affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, SHOULD adhere to the same requirements as corrections that impact *reconciled invoice* data, unless explicitly requested by the end-user. * Replacement mechanism adheres to the following additional requirements: - * Correction handling implementation SHOULD support optional external retention of historical snapshots to enable traceability in uninvoiced billing periods (including both previous and current). - * Corrections for previously invoiced billing periods MUST be represented exclusively through the addition of new records. + * Corrections for previously invoiced billing periods that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. + * Corrections for previously invoiced billing periods that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. + * Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 3a236fdf7..0940568b6 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,7 +4,7 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. -Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, deletions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, deletions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. +Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. @@ -28,10 +28,10 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Invoice Issuer MUST perform internal invoice reconciliation before invoice issuance. * Invoice MUST be considered finalized and immutable once issued. * Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) MUST NOT be applied if they would impact reconciled invoice data. -* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback unless explicitly requested by the end-user. +* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, unless explicitly requested by the end-user. * Invoice Issuer MUST document how to identify an invoiced (closed) billing period. * Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. -* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed unless explicitly requested by the end-user. +* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed, unless explicitly requested by the end-user. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. ## Exceptions From 1399b0e8989d572fdcf92578cc3a1a049d2a1fe0 Mon Sep 17 00:00:00 2001 From: ijurica Date: Mon, 29 Sep 2025 18:13:35 +0200 Subject: [PATCH 34/71] FOCUS #962-correction-handling-attribute: invoice_handling - temp. revert --- specification/attributes/invoice_handling.md | 22 +++----------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 0940568b6..05059c001 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,10 +4,6 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. -Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. - -For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. - ## Attribute ID InvoiceHandling @@ -22,29 +18,17 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Requirements -* All costs that appear on an invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. -* Invoice Issuer MUST document all metrics and dimensions presented on the invoice and included in Invoice Reconciliation. -* Invoice Reconciliation MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. -* Invoice Issuer MUST perform internal invoice reconciliation before invoice issuance. -* Invoice MUST be considered finalized and immutable once issued. -* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) MUST NOT be applied if they would impact reconciled invoice data. -* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, unless explicitly requested by the end-user. -* Invoice Issuer MUST document how to identify an invoiced (closed) billing period. -* Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. -* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed, unless explicitly requested by the end-user. +* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. ## Exceptions * Informational line items that have zero monetary impact and are included solely for transparency MAY be excluded. Examples include: - * Free tier usage tracking with $0.00 charges - * Breakdowns of bundled services where only the bundle total is billed * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -* Exceptions to the restrictions on issued invoices and invoiced billing periods 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. + +None ## Introduced (version) From 14389ebf9d459b15dc99192261cfd527697a82b4 Mon Sep 17 00:00:00 2001 From: ijurica Date: Mon, 29 Sep 2025 18:45:18 +0200 Subject: [PATCH 35/71] FOCUS #962-correction-handling-attribute: invoice_handling update --- specification/attributes/invoice_handling.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 05059c001..c1b8c8e55 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,6 +4,10 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. +Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. + +For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. + ## Attribute ID InvoiceHandling @@ -19,6 +23,15 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Requirements * All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. +* Invoice Issuer MUST document all metrics and dimensions presented on the invoice and included in Invoice Reconciliation. +* Invoice Reconciliation MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. +* Invoice Issuer MUST perform internal invoice reconciliation before invoice issuance. +* Invoice MUST be considered finalized and immutable once issued. +* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) MUST NOT be applied if they would impact reconciled invoice data. +* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, unless explicitly requested by the end-user. +* Invoice Issuer MUST document how to identify an invoiced (closed) billing period. +* Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. +* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed, unless explicitly requested by the end-user. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. ## Exceptions @@ -27,8 +40,9 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. - -None +* Exceptions to the restrictions on issued invoices and invoiced billing periods 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) From 4cef823ceae97e3492fbccd9f7f758fb96bce3f8 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 30 Sep 2025 00:27:53 +0200 Subject: [PATCH 36/71] FOCUS #962-correction-handling-attribute: Additional glossary terms. --- specification/attributes/invoice_handling.md | 2 +- specification/glossary.md | 10 +++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index c1b8c8e55..1333e5613 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -4,7 +4,7 @@ FinOps practitioners must be able to reconcile FOCUS datasets with the correspon 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. -Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoicereconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. +Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoice-reconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. diff --git a/specification/glossary.md b/specification/glossary.md index 14130ab96..e72e96c26 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -120,7 +120,7 @@ The collection of datasets are designed to provide billing insight, additional c A Date/Time Format value that is contained within the beginning bound of a time period. -Invoice Reconciliation +Invoice Reconciliation The process of ensuring that all financial metrics and dimensions presented on an invoice are fully aligned with the underlying cost and usage data associated with that invoice. @@ -128,6 +128,14 @@ The process of ensuring that all financial metrics and dimensions presented on a A category of compute resources that can be paused or terminated by the CSP within certain criteria, often advertised at reduced unit pricing when compared to the equivalent non-interruptible resource. +Invoiced Billing Period + +A billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The "invoiced" designation is established once invoice issuance is confirmed as complete by the responsible Invoice Issuer entity. Exceptionally, additional invoices may be associated with an invoiced (closed) billing period if explicitly requested by the end-user, and in such cases the associated charges must have ChargeClass explicitly set to "Correction". + +Issued Invoice + +An invoice that has been formally generated and released by the designated Invoice Issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and charge records. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. + JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. From 96ece46e48e15bae79f8c36e5d3766716a619c4c Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 30 Sep 2025 14:12:47 +0200 Subject: [PATCH 37/71] FOCUS #962-correction-handling-attribute: glossary update --- specification/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index e72e96c26..a020d2c00 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -122,7 +122,7 @@ A Date/Time Format value that is contained within the beginning bound of a time Invoice Reconciliation -The process of ensuring that all financial metrics and dimensions presented on an invoice are fully aligned with the underlying cost and usage data associated with that invoice. +The process of reconciling the invoice (i.e., the metrics and dimensions presented on an invoice) with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Data presented on an invoice is typically derived through aggregation of cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Interruptible @@ -134,7 +134,7 @@ A billing period for which all planned invoices have been successfully issued by Issued Invoice -An invoice that has been formally generated and released by the designated Invoice Issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and charge records. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. +An invoice that has been formally generated and released by the designated Invoice Issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. From 2ab603c759ad30318beaa625bb1398c7cfe143c1 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 30 Sep 2025 16:45:55 +0200 Subject: [PATCH 38/71] FOCUS #962-correction-handling-attribute: invoice-handling and correction-handling updates --- .../attributes/correction_handling.md | 10 ++--- specification/attributes/invoice_handling.md | 41 ++++++++++++++----- 2 files changed, 35 insertions(+), 16 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 47f73d92c..e6958bb72 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -15,8 +15,8 @@ Corrections may arise from a variety of operational or technical causes, such as Accurate correction handling is essential for a range of business-critical processes, including but not limited to: * Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). -* Financial and legal integrity - preserving original charge records associated with finalized invoices while recording changes to those records separately, as finalized invoices represent binding financial documents requiring immutability and traceability. -* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID). +* Financial and legal integrity - ensuring that data presented on issued invoices remains unchanged and aligned with associated underlying charges provided in the FOCUS Cost and Usage dataset artifacts, while any related corrections do not compromise invoice reconciliation. +* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID) to ensure accurate downstream processing. * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. ### Delivery Mechanisms and Correction Representation @@ -79,10 +79,10 @@ All corrections adhere to the following requirements: * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. * Corrections to charges associated with an issued invoice that do not impact *reconciled invoice* data but do affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, SHOULD adhere to the same requirements as corrections that impact *reconciled invoice* data, unless explicitly requested by the end-user. * Replacement mechanism adheres to the following additional requirements: - * Corrections for previously invoiced billing periods that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. - * Corrections for previously invoiced billing periods that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. + * Corrections to previously invoiced billing periods that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. + * Corrections to previously invoiced billing periods that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. * Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. - * Corrections for uninvoiced billing periods MAY include updates, additions, or omissions. + * Corrections to uninvoiced billing periods MAY include updates, additions, or omissions. * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. * All corrections MUST be represented exclusively by adding new records. diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 1333e5613..f9a3f8e18 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -1,12 +1,30 @@ # 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 + +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*](#glossary:invoice-reconciliation), financial reporting, and chargeback. 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. -Prior to invoice issuance, all charges in FOCUS Cost and Usage dataset artifacts associated with the invoice must be aligned and [*reconciled*](#glossary:invoice-reconciliation) with the financial values presented on the invoice. Once an invoice is issued, it serves as the authoritative financial document and is considered finalized and immutable. Modifications to charges associated with an issued invoice (whether as updates, additions, or omissions) are not permitted if they would change reconciled invoice data. The scope of *invoice reconciliation* includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd. Depending on the Invoice Issuer, these restrictions may extend to additional metrics and dimensions included on the invoice. These constraints ensure the integrity of issued invoices and their supporting data for financial, audit, and compliance purposes. Modifications (including updates, additions, or omissions) that do not impact any invoice-presented financial data are allowed but must be applied with care to preserve traceability. This is particularly important for dimensions and metrics used in essential downstream FinOps capabilities subject to financial data, such as chargeback. +### Invoice Reconciliation and Issuance + +Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artifacts that are associated with the invoice must be reconciled with the metrics and dimensions presented on the invoice. This reconciliation ensures alignment between invoice content and the underlying cost and usage data. + +Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. + +Once an invoice is issued, it becomes the authoritative financial document and is considered finalized and immutable. This means that the financial data presented on an issued invoice must not be changed. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice’s financial validity. + +Modifications to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications do not affect invoice reconciliation, they can still result in loss of auditability and traceability, which in turn complicates corrections and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such modifications are not preferred and should only be applied when explicitly requested by the end-user. + +### Handling Invoiced Billing Periods -For an invoiced (closed) billing period, it is understood that all invoices for that period have been issued, and no new invoices may be associated with it unless explicitly requested by the end-user. The Invoice Issuer must publish in their respective documentation how to identify an invoiced (closed) billing period. Any necessary corrections to charges originally incurred in an invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. This establishes a clear temporal boundary between billing cycles, preserving the historical accuracy and integrity of closed billing periods, while enabling transparent and auditable tracking of any necessary corrections in subsequent open billing periods. +An invoiced billing period represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The ability to identify an invoiced billing period must be documented by the invoice issuer and made accessible to practitioners. + +Any necessary corrections to previously invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in 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. + +Exceptionally, additional invoices may be issued for a closed billing period only if explicitly requested by the end-user. ## Attribute ID @@ -23,16 +41,17 @@ Indicates how invoice-level *charges*, including those not directly tied to usag ## Requirements * All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. -* Invoice Issuer MUST document all metrics and dimensions presented on the invoice and included in Invoice Reconciliation. -* Invoice Reconciliation MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. -* Invoice Issuer MUST perform internal invoice reconciliation before invoice issuance. -* Invoice MUST be considered finalized and immutable once issued. -* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) MUST NOT be applied if they would impact reconciled invoice data. -* Modifications to charges associated with an issued invoice (including updates, additions, deletions, or omissions) that do not impact reconciled invoice data SHOULD NOT be applied if they affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, unless explicitly requested by the end-user. +* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. +* All metrics and dimensions presented on the invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. +* *Invoice reconciliation* MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. +* Invoice Issuer MUST perform internal *invoice reconciliation* before invoice issuance. +* Issued invoice MUST be considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). +* Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice MUST NOT be applied. +* Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice SHOULD NOT be applied, unless explicitly requested by the end-user. +* Ability to identify an invoiced billing period MUST be documented by the invoice issuer and accessible to practitioners. * Invoice Issuer MUST document how to identify an invoiced (closed) billing period. * Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. -* Additional invoices MUST NOT be associated with a billing period once it is invoiced and closed, unless explicitly requested by the end-user. -* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. +* Additional invoices MUST NOT be associated with an invoiced billing period, unless explicitly requested by the end-user. ## Exceptions From 29d74a769a2c8dc688cb004cfb0fc9fb6e32628c Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Tue, 30 Sep 2025 10:29:43 -0700 Subject: [PATCH 39/71] linter fix --- specification/attributes/invoice_handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index f9a3f8e18..1fc59a149 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,7 +12,7 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document and is considered finalized and immutable. This means that the financial data presented on an issued invoice must not be changed. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice’s financial validity. +Once an invoice is issued, it becomes the authoritative financial document and is considered finalized and immutable. This means that the financial data presented on an issued invoice must not be changed. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. Modifications to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications do not affect invoice reconciliation, they can still result in loss of auditability and traceability, which in turn complicates corrections and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such modifications are not preferred and should only be applied when explicitly requested by the end-user. From b56c1420d8bac0461aac0238bf1485fbb020ada2 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 16:09:54 +0200 Subject: [PATCH 40/71] FOCUS #962-correction-handling-attribute: renaming invoiced to closed billing period --- .../datasets/cost_and_usage/columns/chargeclass.md | 8 ++++---- specification/glossary.md | 12 ++++++------ supporting_content/columns/chargeclass.md | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/specification/datasets/cost_and_usage/columns/chargeclass.md b/specification/datasets/cost_and_usage/columns/chargeclass.md index f8fedcc9b..ec6453703 100644 --- a/specification/datasets/cost_and_usage/columns/chargeclass.md +++ b/specification/datasets/cost_and_usage/columns/chargeclass.md @@ -1,6 +1,6 @@ # Charge Class -Charge Class indicates whether the [*row*](#glossary:row) represents a correction to a previously invoiced [*billing period*](#glossary:billing-period). Charge Class is commonly used to differentiate [*corrections](#glossary:correction) from regularly incurred [*charges*](#glossary:charge). +Charge Class indicates whether the [*row*](#glossary:row) represents a correction to a previously [*closed billing period*](#glossary:closed-billing-period). Charge Class is commonly used to differentiate [*corrections](#glossary:correction) from regularly incurred [*charges*](#glossary:charge). The ChargeClass column adheres to the following requirements: @@ -8,7 +8,7 @@ The ChargeClass column adheres to the following requirements: * ChargeClass MUST be of type String. * ChargeClass nullability is defined as follows: * ChargeClass MUST be null when the *row* does not represent a correction or when it represents a correction within the current *billing period*. - * ChargeClass MUST NOT be null when the *row* represents a correction to a previously invoiced *billing period*. + * ChargeClass MUST NOT be null when the *row* represents a correction to a previously *closed billing period*. * ChargeClass MUST be "Correction" when ChargeClass is not null. ## Column ID @@ -21,7 +21,7 @@ Charge Class ## Description -Indicates whether the *row* represents a correction to a previously invoiced *billing period*. +Indicates whether the *row* represents a correction to a previously *closed billing period*. ## Content Constraints @@ -37,7 +37,7 @@ Allowed values: | Value | Description | | :--------- | :----------------------------------------------------------------------------------------------| -| Correction | Correction to a previously invoiced *billing period* (e.g., refunds and credit modifications). | +| Correction | Correction to a previously *closed billing period* (e.g., refunds and credit modifications). | ## Introduced (version) diff --git a/specification/glossary.md b/specification/glossary.md index a020d2c00..cc22e8f98 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -52,6 +52,10 @@ A row in a FOCUS-compatible cost and usage dataset. The time window for which a charge is effective, inclusive of the start date and exclusive of the end date. The charge period for continuous usage should match the time granularity of the dataset (e.g., 1 hour for hourly, 1 day for daily). The charge period for a non-usage charge with time boundaries should match the duration of eligibility. +Closed Billing Period + +A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated invoice issuer. Upon assigning the "closed" status, the responsible invoice issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. + Cloud Service Provider (CSP) A company or organization that provides remote access to computing resources, infrastructure, or applications for a fee. @@ -82,7 +86,7 @@ The agreed-upon unit price for a single [Pricing Unit](#pricingunit) of the asso Correction -A charge to correct cost or usage data in a previously invoiced [*billing period*](#glossary:billing-period). +A charge to correct cost or usage data in a previously [*closed billing period*](#glossary:closed-billing-period). Credit @@ -128,13 +132,9 @@ The process of reconciling the invoice (i.e., the metrics and dimensions present A category of compute resources that can be paused or terminated by the CSP within certain criteria, often advertised at reduced unit pricing when compared to the equivalent non-interruptible resource. -Invoiced Billing Period - -A billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The "invoiced" designation is established once invoice issuance is confirmed as complete by the responsible Invoice Issuer entity. Exceptionally, additional invoices may be associated with an invoiced (closed) billing period if explicitly requested by the end-user, and in such cases the associated charges must have ChargeClass explicitly set to "Correction". - Issued Invoice -An invoice that has been formally generated and released by the designated Invoice Issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. +An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. diff --git a/supporting_content/columns/chargeclass.md b/supporting_content/columns/chargeclass.md index 4297801d7..6e2261941 100644 --- a/supporting_content/columns/chargeclass.md +++ b/supporting_content/columns/chargeclass.md @@ -6,7 +6,7 @@ * Initially, ChargeClass was defined as a non-nullable column with two allowed values: Regular and Correction. * Various alternative names for Regular charges were discussed, including Regular, Standard, Original, and Direct. -* Eventually, the team decided on a nullable column approach, where Correction is the sole allowed value, representing corrections to a previously invoiced billing period. +* Eventually, the team decided on a nullable column approach, where Correction is the sole allowed value, representing corrections to a previously closed billing period. ### Impacts of 1.0 ChargeCategory and ChargeClass cleanup From 460c5596d07689df273adb5f054ef7881f5be071 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 16:21:09 +0200 Subject: [PATCH 41/71] FOCUS #962-correction-handling-attribute: adding open billing period glossary term --- specification/glossary.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/glossary.md b/specification/glossary.md index cc22e8f98..7eff03541 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -163,6 +163,10 @@ A contractual agreement where a customer commits to specific spend or usage goal A term that describes a service that is available and provided immediately or as needed, without requiring a pre-scheduled appointment or prior arrangement. In cloud computing, virtual machines can be created and terminated as needed, i.e., on demand. +Open Billing Period + +A [*billing period*](glossary:billing-period) that has not yet been financially closed, regardless of whether it refers to the current or a past timeframe. The "open" status indicates that billing activities are ongoing and the period remains subject to updates until formally closed. + Origin Charge The [charge](#glossary:charge) that existed prior to an operation. This is used in the context of Provider-Calculated Split Cost Allocation to identify the charge that existed prior to the application of [Provider-Calculated Split Cost Allocation](#providercalculatedsplitcosthandling) to produce [allocated charges](#glossary:allocated-charge). From e1bdda756d2fe655b1b5647817051c2ce7d6a257 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 16:54:55 +0200 Subject: [PATCH 42/71] FOCUS #962-correction-handling-attribute: invoice handling and correction handling updates in progress --- .../attributes/correction_handling.md | 24 +++++++++---------- specification/attributes/invoice_handling.md | 15 ++++++------ 2 files changed, 19 insertions(+), 20 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index e6958bb72..673f9e8d2 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -6,15 +6,15 @@ Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously invoiced [*billing period*](#glossary:billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously invoiced billing period or an uninvoiced billing period (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously [*closed billing period*](#glossary:closed-billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an [*open billing period*](#glossary:open-billing-period) (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. -### Business Requirements and Constraints in Invoiced Billing Periods +### Business Requirements and Constraints in Closed Billing Periods Accurate correction handling is essential for a range of business-critical processes, including but not limited to: -* Temporal accuracy - capturing both when the charge was incurred (reflected in charge period columns, i.e., Charge Period Start and Charge Period End) and when the correction was invoiced (reflected in billing period columns, i.e., Billing Period Start and Billing Period End columns). +* Temporal accuracy - capturing both when the 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 remains unchanged and aligned with associated underlying charges provided in the FOCUS Cost and Usage dataset artifacts, while any related corrections do not compromise invoice reconciliation. * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID) to ensure accurate downstream processing. * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. @@ -25,7 +25,7 @@ FOCUS supports two cost and usage data delivery mechanisms: Replacement and Appe #### Replacement Mechanism -In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a billing period, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, as records may be updated or omitted. The Replacement mechanism should support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. For invoiced billing periods, auditability is ensured through correction handling rules that prohibit updates, deletions, or omissions to charges associated with an issued invoice if they would impact reconciled invoice data. +In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a *billing period*, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, as records may be updated or omitted. The Replacement mechanism should support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. For *closed billing periods*, auditability is ensured through correction handling rules that prohibit updates, deletions, or omissions to charges associated with an issued invoice if they would impact reconciled invoice data. Subsequent dataset artifacts in the Replacement mechanism may include the following: @@ -34,7 +34,7 @@ Subsequent dataset artifacts in the Replacement mechanism may include the follow * Additional records supplement previously delivered data. * Omitted records are removed if no longer applicable. -Corrections to charges associated with an issued invoice that impact reconciled invoice data must be represented exclusively through the addition of new records associated with a subsequent open billing period, with the charge period indicating when the cost was incurred. +Corrections to charges associated with an issued invoice that impact reconciled invoice data must be represented exclusively through the addition of new records associated with a subsequent *open billing period*, with the *charge period* indicating when the cost was incurred. #### Append-only Mechanism @@ -67,22 +67,22 @@ Defines how updates to previously provided [*charges*](#glossary:charge) are rep All corrections adhere to the following requirements: -* Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for invoiced billing periods. +* Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for *closed billing periods*. * Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. -* ChargeClass MUST be null when the *charge* does not represent a correction to a previously invoiced *billing period*. +* ChargeClass MUST be null when the *charge* does not represent a correction to a previously *closed billing period*. * Correction MUST NOT result in double counting of any cost- or quantity-related values. * Corrections to charges associated with an issued invoice that impact *reconciled invoice* data adhere to the following additional requirements: * ChargeClass MUST be "Correction". * Correction MUST NOT replace or omit the original record. * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. - * [BillingPeriodStart](#billingperiodstart) and [BillingPeriodEnd](#billingperiodend) MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent open billing period in which the correction is issued. - * [ChargePeriodStart](#chargeperiodstart) and [ChargePeriodEnd](#chargeperiodend) MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. + * BillingPeriodStart and BillingPeriodEnd MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent *open billing period* in which the correction is issued. + * ChargePeriodStart and ChargePeriodEnd MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. * Corrections to charges associated with an issued invoice that do not impact *reconciled invoice* data but do affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, SHOULD adhere to the same requirements as corrections that impact *reconciled invoice* data, unless explicitly requested by the end-user. * Replacement mechanism adheres to the following additional requirements: - * Corrections to previously invoiced billing periods that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. - * Corrections to previously invoiced billing periods that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. + * Corrections to previously *closed billing periods* that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. + * Corrections to previously *closed billing periods* that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. * Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. - * Corrections to uninvoiced billing periods MAY include updates, additions, or omissions. + * Corrections to *open billing periods* MAY include updates, additions, or omissions. * Append-only mechanism adheres to the following additional requirements: * All previously delivered records MUST be retained without modification or deletion. * All corrections MUST be represented exclusively by adding new records. diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 1fc59a149..a9de63d64 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -16,11 +16,11 @@ Once an invoice is issued, it becomes the authoritative financial document and i Modifications to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications do not affect invoice reconciliation, they can still result in loss of auditability and traceability, which in turn complicates corrections and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such modifications are not preferred and should only be applied when explicitly requested by the end-user. -### Handling Invoiced Billing Periods +### Handling Closed Billing Periods -An invoiced billing period represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The ability to identify an invoiced billing period must be documented by the invoice issuer and made accessible to practitioners. +A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The ability to identify a *closed billing period* must be documented by the invoice issuer and made accessible to practitioners. -Any necessary corrections to previously invoiced billing period that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. +Any necessary corrections to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in 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. @@ -48,10 +48,9 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Issued invoice MUST be considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). * Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice MUST NOT be applied. * Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice SHOULD NOT be applied, unless explicitly requested by the end-user. -* Ability to identify an invoiced billing period MUST be documented by the invoice issuer and accessible to practitioners. -* Invoice Issuer MUST document how to identify an invoiced (closed) billing period. -* Billing period MUST be considered invoiced (closed) only if all invoices for that billing period have been issued. -* Additional invoices MUST NOT be associated with an invoiced billing period, unless explicitly requested by the end-user. +* Ability to identify a *closed billing period* MUST be documented by the invoice issuer and accessible to practitioners. +* Billing period MUST be considered closed only if all invoices for that billing period have been issued. +* Additional invoices MUST NOT be associated with a *closed billing period*, unless explicitly requested by the end-user. ## Exceptions @@ -59,7 +58,7 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -* Exceptions to the restrictions on issued invoices and invoiced billing periods MAY apply in the following cases: +* Exceptions to the restrictions on issued invoices and *closed billing period* 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. From 7c2d5cd7d9ce7112b3f5d93d112b1972311c9127 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 19:27:04 +0200 Subject: [PATCH 43/71] FOCUS #962-correction-handling-attribute: invoice handling and correction handling updates in progress --- specification/attributes/invoice_handling.md | 13 +++++++------ specification/glossary.md | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index a9de63d64..dcb59038c 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,7 +12,7 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document and is considered finalized and immutable. This means that the financial data presented on an issued invoice must not be changed. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. Modifications to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications do not affect invoice reconciliation, they can still result in loss of auditability and traceability, which in turn complicates corrections and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such modifications are not preferred and should only be applied when explicitly requested by the end-user. @@ -42,14 +42,15 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. * If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. -* All metrics and dimensions presented on the invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. * *Invoice reconciliation* MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. -* Invoice Issuer MUST perform internal *invoice reconciliation* before invoice issuance. -* Issued invoice MUST be considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). +* *Invoice reconciliation* MUST be performed by the invoice issuer before issuing an invoice. +* Financial data presented on an invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. +* Financial data presented on an *issued invoice* MUST NOT be altered. * Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice MUST NOT be applied. * Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice SHOULD NOT be applied, unless explicitly requested by the end-user. -* Ability to identify a *closed billing period* MUST be documented by the invoice issuer and accessible to practitioners. -* Billing period MUST be considered closed only if all invoices for that billing period have been issued. +* Billing period MUST be considered "open" until all planned invoices for that period have been issued. +* Billing period MUST be considered "closed" when all planned invoices for that period have been issued. +* Ability to determine whether a billing period is "open" or "closed" MUST be documented by the invoice issuer and accessible to practitioners. * Additional invoices MUST NOT be associated with a *closed billing period*, unless explicitly requested by the end-user. ## Exceptions diff --git a/specification/glossary.md b/specification/glossary.md index 7eff03541..a61c9addc 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -54,7 +54,7 @@ The time window for which a charge is effective, inclusive of the start date and Closed Billing Period -A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated invoice issuer. Upon assigning the "closed" status, the responsible invoice issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. +A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated invoice issuer for that period. Upon assigning the "closed" status, the responsible invoice issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. Cloud Service Provider (CSP) From c98791ccd8641d0936d338d1a8cd41979d9719a6 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 19:35:53 +0200 Subject: [PATCH 44/71] FOCUS #962-correction-handling-attribute: invoice handling updates --- specification/attributes/invoice_handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index dcb59038c..5afb99bfa 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -46,12 +46,12 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * *Invoice reconciliation* MUST be performed by the invoice issuer before issuing an invoice. * Financial data presented on an invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. * Financial data presented on an *issued invoice* MUST NOT be altered. -* Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice MUST NOT be applied. -* Modifications (e.g., updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice that affect data presented on the invoice SHOULD NOT be applied, unless explicitly requested by the end-user. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. * Ability to determine whether a billing period is "open" or "closed" MUST be documented by the invoice issuer and accessible to practitioners. -* Additional invoices MUST NOT be associated with a *closed billing period*, unless explicitly requested by the end-user. +* Additional invoices MUST NOT be associated with a *closed billing period*. ## Exceptions From 8288299ef05326e2a0bcbf6100a886c71c6fff75 Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 19:55:48 +0200 Subject: [PATCH 45/71] FOCUS #962-correction-handling-attribute updates --- specification/attributes/correction_handling.md | 8 ++++---- specification/attributes/invoice_handling.md | 14 ++++++++------ specification/glossary.md | 2 +- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 673f9e8d2..957a1ed49 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -79,13 +79,13 @@ All corrections adhere to the following requirements: * ChargePeriodStart and ChargePeriodEnd MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. * Corrections to charges associated with an issued invoice that do not impact *reconciled invoice* data but do affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, SHOULD adhere to the same requirements as corrections that impact *reconciled invoice* data, unless explicitly requested by the end-user. * Replacement mechanism adheres to the following additional requirements: - * Corrections to previously *closed billing periods* that impact *reconciled invoice* data MUST be represented exclusively through the addition of new records. - * Corrections to previously *closed billing periods* that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new records, unless explicitly requested otherwise by the end-user. + * Corrections to previously *closed billing periods* that impact *reconciled invoice* data MUST be represented exclusively through the addition of new charges. + * Corrections to previously *closed billing periods* that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new charges, unless explicitly requested otherwise by the end-user. * Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. * Corrections to *open billing periods* MAY include updates, additions, or omissions. * Append-only mechanism adheres to the following additional requirements: - * All previously delivered records MUST be retained without modification or deletion. - * All corrections MUST be represented exclusively by adding new records. + * All previously delivered charges MUST be retained without modification or deletion. + * All corrections MUST be represented exclusively by adding new charges. ## Exceptions diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 5afb99bfa..b90885481 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,15 +12,17 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While corrections to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only corrections that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. -Modifications to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications do not affect invoice reconciliation, they can still result in loss of auditability and traceability, which in turn complicates corrections and mappings required in downstream FinOps activities, such as cost allocation, chargeback, or budgeting. For this reason, such modifications are not preferred and should only be applied when explicitly requested by the end-user. +Corrections to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the 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 corrections 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. ### Handling Closed Billing Periods -A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. The ability to identify a *closed billing period* must be documented by the invoice issuer and made accessible to practitioners. +A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. -Any necessary corrections to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in a subsequent open billing period, with the charge period indicating when the cost was incurred. +Any necessary corrections to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. + +The ability to determine whether a billing period is "open" or "closed" must be documented by the invoice issuer and made accessible to practitioners. 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. @@ -46,8 +48,8 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * *Invoice reconciliation* MUST be performed by the invoice issuer before issuing an invoice. * Financial data presented on an invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. * Financial data presented on an *issued invoice* MUST NOT be altered. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. +* Corrections (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. +* Corrections (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. * Ability to determine whether a billing period is "open" or "closed" MUST be documented by the invoice issuer and accessible to practitioners. diff --git a/specification/glossary.md b/specification/glossary.md index a61c9addc..068f8b651 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -134,7 +134,7 @@ A category of compute resources that can be paused or terminated by the CSP with Issued Invoice -An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and immutable (i.e., the data presented on the invoice cannot be changed). While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. +An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and the financial data presented on the invoice must not be altered. While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. From bfc8a1a99d27837777e99b1e00e3c4c2eea6324e Mon Sep 17 00:00:00 2001 From: ijurica Date: Wed, 1 Oct 2025 20:03:31 +0200 Subject: [PATCH 46/71] FOCUS #962-correction-handling-attribute: invoice-handling updates --- specification/attributes/invoice_handling.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index b90885481..633ca4870 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,15 +12,15 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While corrections to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only corrections that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. -Corrections to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the 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 corrections 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 the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications 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 modifications are not preferred and should only be applied when explicitly requested by the end-user. ### Handling Closed Billing Periods A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. -Any necessary corrections to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. +Any necessary modifications to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. The ability to determine whether a billing period is "open" or "closed" must be documented by the invoice issuer and made accessible to practitioners. @@ -48,8 +48,8 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * *Invoice reconciliation* MUST be performed by the invoice issuer before issuing an invoice. * Financial data presented on an invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. * Financial data presented on an *issued invoice* MUST NOT be altered. -* Corrections (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. -* Corrections (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. * Ability to determine whether a billing period is "open" or "closed" MUST be documented by the invoice issuer and accessible to practitioners. From 63d48d635371fff7b028b5f5f46f934230d50274 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 10:51:34 +0200 Subject: [PATCH 47/71] FOCUS #962-correction-handling-attribute: clarification updates based on feedback --- .../attributes/correction_handling.md | 4 +- specification/attributes/invoice_handling.md | 38 +++++++++---------- specification/glossary.md | 2 +- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 957a1ed49..2ebdc306b 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -4,7 +4,7 @@ ### Definition and Scope of Corrections -Correction Handling attribute defines how updates to previously provided charge records are represented in FOCUS datasets. +Correction Handling attribute defines how modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from closed or open billing periods, are represented in FOCUS Cost and Usage dataset artifacts. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously [*closed billing period*](#glossary:closed-billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an [*open billing period*](#glossary:open-billing-period) (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. @@ -61,7 +61,7 @@ Correction Handling ## Description -Defines how updates to previously provided [*charges*](#glossary:charge) are represented in FOCUS datasets. +Defines how modifications (including updates, additions, or omissions) to previously provided *charges*, whether from closed or open billing periods, are represented in FOCUS Cost and Usage dataset artifacts. ## Requirements diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 633ca4870..38e9067dd 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -2,27 +2,27 @@ ## Overview -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*](#glossary:invoice-reconciliation), financial reporting, and chargeback. +FinOps practitioners must be able to reconcile FOCUS dataset artifacts with the corresponding invoices and usage statements they receive from Invoice Issuers. 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) artifact. Without this alignment, it becomes difficult to perform accurate [*invoice reconciliation*](#glossary:invoice-reconciliation), financial reporting, and chargeback. -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. +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 artifact, enabling FOCUS dataset artifacts to be used in a system of record for all invoiced costs. ### Invoice Reconciliation and Issuance Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artifacts that are associated with the invoice must be reconciled with the metrics and dimensions presented on the invoice. This reconciliation ensures alignment between invoice content and the underlying cost and usage data. -Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. +Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the Invoice Issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the financial data it contains must not be altered. While modifications to the underlying cost and usage charges associated with an issued invoice (e.g., updates, additions, or omissions) may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable. Any misalignment would invalidate the prior reconciliation and undermine the invoice's financial validity. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. While corrections to the underlying cost and usage charges associated with an *issued invoice* (including updates, additions, or omissions) may be permitted, they must not compromise the integrity of the 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 cost and usage charges associated with an issued invoice that do not impact data presented on the invoice are allowed. However, although these modifications 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 modifications are not preferred and should only be applied when explicitly requested by the end-user. +Corrections to the underlying cost and usage charges associated with an issued invoice that do not impact data presented on the 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. ### Handling Closed Billing Periods -A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated invoice issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. +A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. -Any necessary modifications to previously *closed billing period* that have financial impact and require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. +Any necessary corrections to previously *closed billing period* that require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. -The ability to determine whether a billing period is "open" or "closed" must be documented by the invoice issuer and made accessible to practitioners. +The ability to determine whether a billing period is "open" or "closed" must be documented by the Invoice Issuer and made accessible to practitioners. 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. @@ -38,21 +38,21 @@ 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. +Indicates how invoice-level *charges*, including those not directly tied to usage, should be represented in a FOCUS Cost and Usage dataset artifacts. ## Requirements -* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset. -* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset. -* *Invoice reconciliation* MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, BillingPeriodEnd, and ChargeCategory. -* *Invoice reconciliation* MUST be performed by the invoice issuer before issuing an invoice. -* Financial data presented on an invoice and included in *invoice reconciliation* MUST be documented by the invoice issuer and accessible to practitioners. -* Financial data presented on an *issued invoice* MUST NOT be altered. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice MUST NOT be applied when they affect the financial data presented on the invoice. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an issued invoice SHOULD NOT be applied when they do not affect the financial data presented on the invoice. +* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in the FOCUS Cost and Usage dataset artifacts. +* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. +* *Invoice reconciliation* MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. +* *Invoice reconciliation* MUST be performed by the Invoice Issuer before issuing an invoice. +* Cost and usage data presented on an invoice and included in *invoice reconciliation* MUST be documented by the Invoice Issuer and accessible to practitioners. +* Cost and usage data presented on an *issued invoice* MUST NOT be altered. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an *issued invoice* MUST NOT be applied when they affect the cost and usage data presented on the invoice. +* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an *issued invoice* SHOULD NOT be applied when they do not affect the cost and usage data presented on the invoice. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. -* Ability to determine whether a billing period is "open" or "closed" MUST be documented by the invoice issuer and accessible to practitioners. +* Ability to determine whether a billing period is "open" or "closed" MUST be documented by the Invoice Issuer and accessible to practitioners. * Additional invoices MUST NOT be associated with a *closed billing period*. ## Exceptions @@ -61,7 +61,7 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -* Exceptions to the restrictions on issued invoices and *closed billing period* MAY apply in the following cases: +* Exceptions to the restrictions on *issued invoices* and *closed billing period* 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. diff --git a/specification/glossary.md b/specification/glossary.md index 068f8b651..788388e66 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -54,7 +54,7 @@ The time window for which a charge is effective, inclusive of the start date and Closed Billing Period -A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated invoice issuer for that period. Upon assigning the "closed" status, the responsible invoice issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. +A [*billing period*](glossary:billing-period) that has been financially closed following the successful issuance of all planned invoices by the designated Invoice Issuer for that period. Upon assigning the "closed" status, the responsible Invoice Issuer entity confirms that no additional invoices will be associated with this period. Exceptionally, additional invoices may be associated with a closed billing period if explicitly requested by the end-user. Cloud Service Provider (CSP) From 62102930533018d7fe1379b7d504afa42725ecfd Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 11:32:38 +0200 Subject: [PATCH 48/71] FOCUS #962-correction-handling-attribute: adding issued charge glossary term --- specification/attributes/invoice_handling.md | 12 ++++++------ specification/glossary.md | 8 ++++++-- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 38e9067dd..2d6da98bc 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,15 +12,15 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the Invoice Issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. While corrections to the underlying cost and usage charges associated with an *issued invoice* (including updates, additions, or omissions) may be permitted, they must not compromise the integrity of the 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. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. While corrections to the underlying [*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 cost and usage charges associated with an issued invoice that do not impact data presented on the 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 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. ### Handling Closed Billing Periods A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. -Any necessary corrections to previously *closed billing period* that require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period indicating when the cost was incurred. +Any necessary corrections to previously *closed billing period* that require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period of the underlying cost and usage charges indicating when the cost was incurred. The ability to determine whether a billing period is "open" or "closed" must be documented by the Invoice Issuer and made accessible to practitioners. @@ -48,12 +48,12 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * *Invoice reconciliation* MUST be performed by the Invoice Issuer before issuing an invoice. * Cost and usage data presented on an invoice and included in *invoice reconciliation* MUST be documented by the Invoice Issuer and accessible to practitioners. * Cost and usage data presented on an *issued invoice* MUST NOT be altered. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an *issued invoice* MUST NOT be applied when they affect the cost and usage data presented on the invoice. -* Modifications (including updates, additions, or omissions) to the underlying cost and usage charges associated with an *issued invoice* SHOULD NOT be applied when they do not affect the cost and usage data presented on the invoice. +* Corrections (including updates, additions, or omissions) to the underlying *issued charges* MUST NOT be applied when they affect the cost and usage data presented on the associated *issued invoice*. +* Corrections (including updates, additions, or omissions) to the underlying *issued charges* SHOULD NOT be applied when they do not affect the cost and usage data presented on the associated *issued invoice*. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. * Ability to determine whether a billing period is "open" or "closed" MUST be documented by the Invoice Issuer and accessible to practitioners. -* Additional invoices MUST NOT be associated with a *closed billing period*. +* Additional invoice MUST NOT be associated with a *closed billing period*. ## Exceptions diff --git a/specification/glossary.md b/specification/glossary.md index 788388e66..b5a60f0ed 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -126,7 +126,7 @@ A Date/Time Format value that is contained within the beginning bound of a time Invoice Reconciliation -The process of reconciling the invoice (i.e., the metrics and dimensions presented on an invoice) with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Data presented on an invoice is typically derived through aggregation of cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. +The process of reconciling the invoice (i.e., the metrics and dimensions presented on an invoice) with the underlying [*charges*](#glossary:charge) provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Data presented on an invoice is typically derived through aggregation of cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Interruptible @@ -134,7 +134,11 @@ A category of compute resources that can be paused or terminated by the CSP with Issued Invoice -An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying charges provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and the financial data presented on the invoice must not be altered. While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. +An invoice that has been formally generated and released by the designated invoice issuer. Prior to issuance, the invoice must be reconciled with the underlying [*charges*](#glossary:charge) provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Once issued, the invoice becomes the authoritative financial document and is considered finalized and the financial data presented on the invoice must not be altered. While modifications (including updates, additions, or omissions) of underlaying cost and usage charges may be permitted, they must not compromise the integrity of the issued invoice. Only modifications that maintain alignment with the invoice content are acceptable, as any misalignment would invalidate the prior reconciliation. + +Issued Charge + +A [*charge*](#glossary:charge) associated with an [*issued invoice*](glossary:issued-invoice). JSON A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. From 93628179c04708a9cda0691c0b2c3a9bcb1c3ffd Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 12:50:00 +0200 Subject: [PATCH 49/71] FOCUS #962-correction-handling-attribute: Changing the Correction glossary term definition and (non-material) updates to ChargeClass column definition upon feedback --- specification/attributes/correction_handling.md | 4 +--- .../datasets/cost_and_usage/columns/chargeclass.md | 8 ++++---- specification/glossary.md | 4 +++- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 2ebdc306b..7329eed9f 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,11 +2,9 @@ ## Overview -### Definition and Scope of Corrections - Correction Handling attribute defines how modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from closed or open billing periods, are represented in FOCUS Cost and Usage dataset artifacts. -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously [*closed billing period*](#glossary:closed-billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an [*open billing period*](#glossary:open-billing-period) (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable, subject to applicable correction handling restrictions. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously [*closed billing period*](#glossary:closed-billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an [*open billing period*](#glossary:open-billing-period) (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. diff --git a/specification/datasets/cost_and_usage/columns/chargeclass.md b/specification/datasets/cost_and_usage/columns/chargeclass.md index ec6453703..b5ee341ca 100644 --- a/specification/datasets/cost_and_usage/columns/chargeclass.md +++ b/specification/datasets/cost_and_usage/columns/chargeclass.md @@ -1,14 +1,14 @@ # Charge Class -Charge Class indicates whether the [*row*](#glossary:row) represents a correction to a previously [*closed billing period*](#glossary:closed-billing-period). Charge Class is commonly used to differentiate [*corrections](#glossary:correction) from regularly incurred [*charges*](#glossary:charge). +Charge Class indicates whether a [*charge*](#glossary:charge) represents a [*correction](#glossary:correction) to a previously [*closed billing period*](#glossary:closed-billing-period). Charge Class is commonly used to differentiate such corrections from all other charges, including both regularly incurred *charges* and *corrections* to [*open billing periods*](#glossary:open-billing-period). The ChargeClass column adheres to the following requirements: * ChargeClass MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). * ChargeClass MUST be of type String. * ChargeClass nullability is defined as follows: - * ChargeClass MUST be null when the *row* does not represent a correction or when it represents a correction within the current *billing period*. - * ChargeClass MUST NOT be null when the *row* represents a correction to a previously *closed billing period*. + * ChargeClass MUST be null when the *charge* does not represent a correction or when it represents a correction within the current *billing period*. + * ChargeClass MUST NOT be null when the *charge* represents a correction to a previously *closed billing period*. * ChargeClass MUST be "Correction" when ChargeClass is not null. ## Column ID @@ -21,7 +21,7 @@ Charge Class ## Description -Indicates whether the *row* represents a correction to a previously *closed billing period*. +Indicates whether a *charge* represents a correction to a previously *closed billing period*. ## Content Constraints diff --git a/specification/glossary.md b/specification/glossary.md index b5a60f0ed..49485817b 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -86,7 +86,9 @@ The agreed-upon unit price for a single [Pricing Unit](#pricingunit) of the asso Correction -A charge to correct cost or usage data in a previously [*closed billing period*](#glossary:closed-billing-period). +Any modification (update, addition, or omission) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period). + +The term "Correction" (capitalized) refers specifically to an allowed value in the [Charge Class](#chargeclass) column, designating charges used to correct cost or usage data from a previously closed billing period. In contrast, the broader concept of "corrections" (lowercase) includes all types of modifications, regardless of the [*billing period*](#glossary:billing-period) status. Credit From 0046b4b78d59300f524bfc3cb9b379cc43a99a5a Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 16:01:48 +0200 Subject: [PATCH 50/71] FOCUS #962-correction-handling-attribute: Correction glossary term update --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 49485817b..caecf0463 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -86,7 +86,7 @@ The agreed-upon unit price for a single [Pricing Unit](#pricingunit) of the asso Correction -Any modification (update, addition, or omission) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period). +Any modification (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period). A correction may consist of multiple simultaneous modifications, each representing an update or omission of a previously delivered charge, or the addition of a new charge, collectively forming the correction. The term "Correction" (capitalized) refers specifically to an allowed value in the [Charge Class](#chargeclass) column, designating charges used to correct cost or usage data from a previously closed billing period. In contrast, the broader concept of "corrections" (lowercase) includes all types of modifications, regardless of the [*billing period*](#glossary:billing-period) status. From 0f61ced669a4e54424f96bdbd10b648cc3c72348 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 16:55:24 +0200 Subject: [PATCH 51/71] FOCUS #962-correction-handling-attribute: moving corrections-related content from invoice handling to correction handling --- .../attributes/correction_handling.md | 54 ++++++++++--------- specification/attributes/invoice_handling.md | 18 +++---- 2 files changed, 37 insertions(+), 35 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 7329eed9f..250d76631 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,9 +2,9 @@ ## Overview -Correction Handling attribute defines how modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from closed or open billing periods, are represented in FOCUS Cost and Usage dataset artifacts. +Correction Handling attribute defines how [*corrections*](#glossary:correction), i.e., modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period), are represented in FOCUS Cost and Usage dataset artifacts. -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously [*closed billing period*](#glossary:closed-billing-period). In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an [*open billing period*](#glossary:open-billing-period) (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable. +**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously *closed billing period*. In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an *open billing period* (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable. Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. @@ -32,8 +32,6 @@ Subsequent dataset artifacts in the Replacement mechanism may include the follow * Additional records supplement previously delivered data. * Omitted records are removed if no longer applicable. -Corrections to charges associated with an issued invoice that impact reconciled invoice data must be represented exclusively through the addition of new records associated with a subsequent *open billing period*, with the *charge period* indicating when the cost was incurred. - #### Append-only Mechanism In the Append-only mechanism, each 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. @@ -49,6 +47,18 @@ Within the Append-only mechanism, two correction styles are commonly used: To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. +### Corrections to Issued Charges + +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 + +Any necessary corrections to previously *closed billing period* that require issuing additional invoices must be result in additional charge(s) associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred. (An exception to this rule may apply if explicitly requested by the end-user.) + +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 @@ -59,35 +69,31 @@ Correction Handling ## Description -Defines how modifications (including updates, additions, or omissions) to previously provided *charges*, whether from closed or open billing periods, are represented in FOCUS Cost and Usage dataset artifacts. +Defines how modifications (including updates, additions, or omissions) to previously provided *charges*, whether from an *open billing period* or a *closed billing period*, are represented in FOCUS Cost and Usage dataset artifacts. ## Requirements All corrections adhere to the following requirements: -* Correction handling implementation MUST support auditability by enabling traceability from the original record through all subsequent corrections for *closed billing periods*. -* Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented within the Data Generator documentation. -* ChargeClass MUST be null when the *charge* does not represent a correction to a previously *closed billing period*. +* Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented by the Data Generator. +* Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability when Replacement mechanism is used, allowing end-users to enable traceability. * Correction MUST NOT result in double counting of any cost- or quantity-related values. -* Corrections to charges associated with an issued invoice that impact *reconciled invoice* data adhere to the following additional requirements: - * ChargeClass MUST be "Correction". - * Correction MUST NOT replace or omit the original record. - * Corrected row(s) MUST be assigned to a different InvoiceId than the original record. - * BillingPeriodStart and BillingPeriodEnd MUST equal the [*inclusive start bound*](#glossary:inclusivestartbound) and [*exclusive end bound*](#glossary:exclusiveendbound) of a subsequent *open billing period* in which the correction is issued. - * ChargePeriodStart and ChargePeriodEnd MUST equal the *inclusive start bound* and *exclusive end bound* of the period in which the cost was originally incurred. -* Corrections to charges associated with an issued invoice that do not impact *reconciled invoice* data but do affect dimensions and metrics used in downstream FinOps capabilities subject to financial data, such as chargeback, SHOULD adhere to the same requirements as corrections that impact *reconciled invoice* data, unless explicitly requested by the end-user. -* Replacement mechanism adheres to the following additional requirements: - * Corrections to previously *closed billing periods* that impact *reconciled invoice* data MUST be represented exclusively through the addition of new charges. - * Corrections to previously *closed billing periods* that do not impact *reconciled invoice* data but affect dimensions and metrics used in downstream FinOps capabilities (e.g., chargeback) SHOULD be represented exclusively through the addition of new charges, unless explicitly requested otherwise by the end-user. - * Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. - * Corrections to *open billing periods* MAY include updates, additions, or omissions. -* Append-only mechanism adheres to the following additional requirements: - * All previously delivered charges MUST be retained without modification or deletion. - * All corrections MUST be represented exclusively by adding new charges. +* Correction MAY consist of multiple simultaneous modifications, each representing an update or omission of a previously delivered charge, or the addition of a new charge. +* Correction to *issued charges* adheres to the following additional requirements: + * Correction MUST NOT be applied when it results in discrepancies with the cost and usage data presented on the associated *issued invoice*. + * Correction SHOULD NOT be applied when it does not results in discrepancies with the cost and usage data presented on the associated *issued invoice*, but still affects downstream FinOps capabilities (e.g., chargeback). + * Correction MAY include additional charges associated with a different InvoiceId than the original charges. + * Correction MAY include additional charges associated with a different billing period than the original charges. +* Correction to 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-only 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 -None +* 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) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 2d6da98bc..50717e37d 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,21 +12,19 @@ Prior to invoice issuance, all charges in the FOCUS Cost and Usage dataset artif Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the Invoice Issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. While corrections to the underlying [*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. +Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. -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*](#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*. Only corrections that maintain alignment with the invoice content are acceptable. -### Handling Closed Billing Periods +For more information on *corrections* to *issued charges*, refer to the [Correction Handling](#correctionhandling) section. -A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. +### Handling Closed Billing Periods -Any necessary corrections to previously *closed billing period* that require issuing additional invoices must instead be reflected in a subsequent [*open billing period*](#glossary:open-billing-period), with the charge period of the underlying cost and usage charges indicating when the cost was incurred. +A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. This approach establishes a clear temporal boundary between billing cycles. Exceptionally, additional invoices may be issued for a closed billing period only if explicitly requested by the end-user. The ability to determine whether a billing period is "open" or "closed" must be documented by the Invoice Issuer and made accessible to practitioners. -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. - -Exceptionally, additional invoices may be issued for a closed billing period only if explicitly requested by the end-user. +For information on *corrections* to *closed billing periods*, refer to the [Correction Handling](#correctionhandling) section. ## Attribute ID @@ -48,8 +46,6 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * *Invoice reconciliation* MUST be performed by the Invoice Issuer before issuing an invoice. * Cost and usage data presented on an invoice and included in *invoice reconciliation* MUST be documented by the Invoice Issuer and accessible to practitioners. * Cost and usage data presented on an *issued invoice* MUST NOT be altered. -* Corrections (including updates, additions, or omissions) to the underlying *issued charges* MUST NOT be applied when they affect the cost and usage data presented on the associated *issued invoice*. -* Corrections (including updates, additions, or omissions) to the underlying *issued charges* SHOULD NOT be applied when they do not affect the cost and usage data presented on the associated *issued invoice*. * Billing period MUST be considered "open" until all planned invoices for that period have been issued. * Billing period MUST be considered "closed" when all planned invoices for that period have been issued. * Ability to determine whether a billing period is "open" or "closed" MUST be documented by the Invoice Issuer and accessible to practitioners. @@ -61,7 +57,7 @@ Indicates how invoice-level *charges*, including those not directly tied to usag * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount * If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -* Exceptions to the restrictions on *issued invoices* and *closed billing period* MAY apply in the following cases: +* Exceptions to the restrictions on *issued invoices* and *closed billing periods* 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. From c47d6ff09a75b40a3ec57b13803bd7890ff79170 Mon Sep 17 00:00:00 2001 From: ijurica Date: Fri, 3 Oct 2025 16:58:38 +0200 Subject: [PATCH 52/71] linter fix --- specification/attributes/invoice_handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 50717e37d..927aa4c57 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -14,7 +14,7 @@ Invoice data is typically derived through aggregation of individual cost and usa Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. -[*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*. Only corrections that maintain alignment with the invoice content are acceptable. +[*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*. Only corrections that maintain alignment with the invoice content are acceptable. For more information on *corrections* to *issued charges*, refer to the [Correction Handling](#correctionhandling) section. From b0d27055569c8cf3df75d460cadde146f7b7392a Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Fri, 3 Oct 2025 10:44:38 -0700 Subject: [PATCH 53/71] draft commit --- .../attributes/correction_handling.md | 48 ++++++++++++++ specification/attributes/delivery_handling.md | 62 +++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 specification/attributes/delivery_handling.md diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 250d76631..c076c342f 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,6 +2,54 @@ ## Overview +The Correction Handling attribute defines how [*corrections*](#glossary:correction) to a previously delivered [*dataset artifact*](#glossary:dataset-artifact) are represented in a subsequently delivered *dataset artifact*. + +Corrections may include some combination of added, updated, or removed *charges*. 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. + +### Correction Mechanisms + +FOCUS supports two delivery mechanisms: Overwrite and Append. For more information, see the [Delivery Handling attribute](#deliveryhandling). + +FOCUS supports three correction mechanisms: + +* Replacement. Existing records are replaced by new records. +* Delta. Existing records are preserved, modified by new records. +* Ledger. Existing records are preserved, fully debited by new records, and then credited by more new records. + +#### Replacement Corrections + +In the Replacement correction mechanism, a given *dataset artifact* provides a complete snapshot of data for a *billing period*, based on the data available at the time of delivery. Subsequent dataset artifacts use the Overwrite delivery mechanism and completely replace all previous *dataset artifacts* to reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks inherent auditability. + +#### Delta Corrections + +In the Revision correction mechanism, a given *dataset artifact* uses the Append delivery mechanism to add records that update or supplement previous *dataset artifacts* within a *billing period*. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This mechanism offers limited inherent auditability. + +### Ledger Corrections + +In the Ledger correction mechanism, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping style of debits and credits 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. This mechanism offers full inherent auditability. + + + + +#### Append-only Correction Mechanism + +In the Append-only correction mechanism, a subsequent dataset artifact appends new records without modifying or removing previously delivered ones. Corrections in the Append-only mechanism are represented exclusively by adding new records. This mechanism inherently supports auditability, as all original and correction records are retained. + +Within the Append-only mechanism, two correction styles are commonly used: + +* Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. +* Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. + + +For *closed billing periods*, auditability is ensured through correction handling rules that typically prohibit updates, deletions, or omissions to *charges* associated with an *issued invoice* if they would impact reconciled invoice data. + + + + + + + + Correction Handling attribute defines how [*corrections*](#glossary:correction), i.e., modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period), are represented in FOCUS Cost and Usage dataset artifacts. **Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously *closed billing period*. In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an *open billing period* (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable. diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md new file mode 100644 index 000000000..7310a7df4 --- /dev/null +++ b/specification/attributes/delivery_handling.md @@ -0,0 +1,62 @@ +# 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 in 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 in the Replace mechanism may include the following: + +* + +## 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: + +* A *dataset artifact* SHOULD be applicable to one and only one [BillingPeriodStart](#billingperiodstart) and [#BillingPeriodEnd](#billingperiodend). +* A *dataset artifact* SHOULD be delivered using either the Replacement or Append-only delivery mechanism. + +## Exceptions + +None + +## Introduced (version) + +1.3 From f94f8c2acd48475c94b887439a206ddd7cfae23c Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:44:37 -0700 Subject: [PATCH 54/71] revision --- .../attributes/correction_handling.md | 115 ++++-------------- specification/attributes/delivery_handling.md | 13 +- specification/attributes/invoice_handling.md | 52 ++++---- specification/glossary.md | 6 +- 4 files changed, 65 insertions(+), 121 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index c076c342f..5bfd438a9 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -2,110 +2,54 @@ ## Overview -The Correction Handling attribute defines how [*corrections*](#glossary:correction) to a previously delivered [*dataset artifact*](#glossary:dataset-artifact) are represented in a subsequently delivered *dataset artifact*. +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 *charges*. 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. - -### Correction Mechanisms - -FOCUS supports two delivery mechanisms: Overwrite and Append. For more information, see the [Delivery Handling attribute](#deliveryhandling). - -FOCUS supports three correction mechanisms: - -* Replacement. Existing records are replaced by new records. -* Delta. Existing records are preserved, modified by new records. -* Ledger. Existing records are preserved, fully debited by new records, and then credited by more new records. - -#### Replacement Corrections - -In the Replacement correction mechanism, a given *dataset artifact* provides a complete snapshot of data for a *billing period*, based on the data available at the time of delivery. Subsequent dataset artifacts use the Overwrite delivery mechanism and completely replace all previous *dataset artifacts* to reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks inherent auditability. - -#### Delta Corrections - -In the Revision correction mechanism, a given *dataset artifact* uses the Append delivery mechanism to add records that update or supplement previous *dataset artifacts* within a *billing period*. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This mechanism offers limited inherent auditability. - -### Ledger Corrections - -In the Ledger correction mechanism, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping style of debits and credits 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. This mechanism offers full inherent auditability. - - - - -#### Append-only Correction Mechanism - -In the Append-only correction mechanism, a subsequent dataset artifact appends new records without modifying or removing previously delivered ones. Corrections in the Append-only mechanism are represented exclusively by adding new records. This mechanism inherently supports auditability, as all original and correction records are retained. - -Within the Append-only mechanism, two correction styles are commonly used: - -* Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. -* Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. - - -For *closed billing periods*, auditability is ensured through correction handling rules that typically prohibit updates, deletions, or omissions to *charges* associated with an *issued invoice* if they would impact reconciled invoice data. - - - - - - - - -Correction Handling attribute defines how [*corrections*](#glossary:correction), i.e., modifications (including updates, additions, or omissions) to previously provided [*charges*](#glossary:charge), whether from an [*open billing period*](#glossary:open-billing-period) or a [*closed billing period*](#glossary:closed-billing-period), are represented in FOCUS Cost and Usage dataset artifacts. - -**Terminology Note:** The term "Correction" (capitalized) refers specifically to an allowed value in the [ChargeClass](#chargeclass) column, which designates charge records used to correct cost and usage data from a previously *closed billing period*. In contrast, the Correction Handling attribute covers the broader concept of "corrections" (lowercase), which may include charge records used to correct cost and usage data originally associated with a previously *closed billing period* or an *open billing period* (including both previous and current), as well as the omission of a previously provisioned charge if it is no longer applicable. - -Corrections may arise from a variety of operational or technical causes, such as refunds, delayed or missing cost and usage data, rounding errors, post-processing adjustments, etc. - -### Business Requirements and Constraints in Closed Billing Periods +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 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 remains unchanged and aligned with associated underlying charges provided in the FOCUS Cost and Usage dataset artifacts, while any related corrections do not compromise invoice reconciliation. +* Financial and legal integrity - ensuring that data presented on issued invoices remains unchanged and aligned with associated underlying charges provided in the FOCUS dataset artifacts, while any related corrections do not compromise invoice reconciliation. * Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID) to ensure accurate downstream processing. * Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. -### Delivery Mechanisms and Correction Representation - -FOCUS supports two cost and usage data delivery mechanisms: Replacement and Append-only. These mechanisms are not mutually exclusive and hybrid implementations are common, allowing Data Generators to meet specific delivery and auditability requirements. - -#### Replacement Mechanism +### Correction Styles -In the Replacement mechanism, each dataset artifact provides a complete snapshot of cost and usage data for a *billing period*, based on the data collected up to the time of delivery. Subsequent dataset artifacts typically reflect updates, additions, or omissions relative to the previous snapshot. This mechanism lacks a built-in audit trail, as records may be updated or omitted. The Replacement mechanism should support external retention of historical snapshots as an optional capability, allowing end-users to enable traceability. For *closed billing periods*, auditability is ensured through correction handling rules that prohibit updates, deletions, or omissions to charges associated with an issued invoice if they would impact reconciled invoice data. +FOCUS supports three correction styles: -Subsequent dataset artifacts in the Replacement mechanism may include the following: +| Correction Style | Delivery Mechanism | Correction Style Description | +| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | +| Replacement | Overwrite | Existing records are replaced by new records. | +| Delta | Append | Existing records are preserved, modified by new records. | +| Ledger | Append | Existing records are preserved, fully debited by new records, and then credited by more new records. | -* Unchanged records are carried over. -* Updated records overwrite previous values. -* Additional records supplement previously delivered data. -* Omitted records are removed if no longer applicable. +For more information on delivery mechanisms, see the [Delivery Handling attribute](#deliveryhandling). -#### Append-only Mechanism - -In the Append-only mechanism, each 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. +#### Replacement Corrections -Corrections in the Append-only mechanism are represented exclusively by adding new records. +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. Given that historical data is discarded, this style lacks inherent auditability. -Within the Append-only mechanism, two correction styles are commonly used: +#### Delta Corrections -* Ledger-style correction adds records that update or supplement cost and usage data. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited audit transparency. -* Accounting-style correction generally follows a two-step representation. 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. This style preserves full correction history. +In the Revision correction style, a given *dataset artifact* uses the Append delivery mechanism to add records that update or supplement previous *dataset artifacts* within a *billing period*. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited inherent auditability. -### Data Integrity +#### Ledger Corrections -To ensure data integrity, correction records must not result in double counting of any cost- or quantity-related values. This applies regardless of the correction style or delivery mechanism used. +In the Ledger correction style, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping style of debits and credits 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. 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 -Any necessary corrections to previously *closed billing period* that require issuing additional invoices must be result in additional charge(s) associated with a subsequent *open billing period*, with the charge period indicating when the cost was incurred. (An exception to this rule may apply if explicitly requested by the end-user.) +A billing period is considered closed when all expected invoices for that timeframe have been issued. -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. +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 @@ -117,23 +61,16 @@ Correction Handling ## Description -Defines how modifications (including updates, additions, or omissions) to previously provided *charges*, whether from an *open billing period* or a *closed billing period*, are represented in FOCUS Cost and Usage dataset artifacts. +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: -* Correction handling implementation MUST ensure that the delivery mechanisms and correction styles in use are documented by the Data Generator. -* Correction handling implementation SHOULD support external retention of historical snapshots as an optional capability when Replacement mechanism is used, allowing end-users to enable traceability. -* Correction MUST NOT result in double counting of any cost- or quantity-related values. -* Correction MAY consist of multiple simultaneous modifications, each representing an update or omission of a previously delivered charge, or the addition of a new charge. -* Correction to *issued charges* adheres to the following additional requirements: - * Correction MUST NOT be applied when it results in discrepancies with the cost and usage data presented on the associated *issued invoice*. - * Correction SHOULD NOT be applied when it does not results in discrepancies with the cost and usage data presented on the associated *issued invoice*, but still affects downstream FinOps capabilities (e.g., chargeback). - * Correction MAY include additional charges associated with a different InvoiceId than the original charges. - * Correction MAY include additional charges associated with a different billing period than the original charges. -* Correction to 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-only mechanism adheres to the following additional 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. diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md index 7310a7df4..dc8d0c635 100644 --- a/specification/attributes/delivery_handling.md +++ b/specification/attributes/delivery_handling.md @@ -19,7 +19,7 @@ For more information on corrections, see the [Correction Handling attribute](*co 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 in the Overwrite mechanism may include the following: +Subsequent dataset artifacts using the Overwrite mechanism may include the following: * Unchanged records are carried over. * Updated records overwrite previous values. @@ -30,9 +30,12 @@ Subsequent dataset artifacts in the Overwrite mechanism may include the followin 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 in the Replace mechanism may include the following: +Subsequent dataset artifacts using the Replace 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. +* Ommitted records are recorded as new entries, representing the reversal. ## Attribute ID @@ -50,8 +53,8 @@ Defines how a data generator delivers a *dataset artifact* to a customer. The delivery of a *dataset artifact* adheres to the following requirements: -* A *dataset artifact* SHOULD be applicable to one and only one [BillingPeriodStart](#billingperiodstart) and [#BillingPeriodEnd](#billingperiodend). -* A *dataset artifact* SHOULD be delivered using either the Replacement or Append-only delivery mechanism. +* A FOCUS *dataset artifact* SHOULD be delivered using either the Overwrite or Append delivery mechanism. +* The delivery mechanism(s) used to correct FOCUS dataset artifacts MUST be documented by the data generator. ## Exceptions diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 927aa4c57..85135f0d4 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -2,29 +2,38 @@ ## Overview -FinOps practitioners must be able to reconcile FOCUS dataset artifacts with the corresponding invoices and usage statements they receive from Invoice Issuers. 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) artifact. Without this alignment, it becomes difficult to perform accurate [*invoice reconciliation*](#glossary:invoice-reconciliation), financial reporting, and chargeback. +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 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 artifact, enabling FOCUS dataset artifacts to be used in a system of record for all invoiced costs. +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, all charges in the FOCUS Cost and Usage dataset artifacts that are associated with the invoice must be reconciled with the metrics and dimensions presented on the invoice. This reconciliation ensures alignment between invoice content and the underlying cost and usage data. +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: -Invoice data is typically derived through aggregation of individual cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. Depending on the Invoice Issuer, reconciliation may also extend to additional metrics and dimensions included on the invoice. +* [*Billing Account ID*](#billingaccountid) +* [*Billing Currency*](#billingcurrency) +* [*Billing Period Start*](#billingperiodstart) +* [*Billing Period End*](#billingperiodend) +* [*Invoice ID*](#invoiceid) +* [*Invoice Issuer Name*](#invoiceissuername) -Once an invoice is issued, it becomes the authoritative financial document. Issued invoice is considered finalized, and the cost and usage data it contains must not be altered. +Depending on the invoice issuer, reconciliation may also extend to additional metrics and dimensions. -[*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*. Only corrections that maintain alignment with the invoice content are acceptable. +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). -For more information on *corrections* to *issued charges*, refer to the [Correction Handling](#correctionhandling) section. +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. -### Handling Closed Billing Periods +### Open and Closed Billing Periods -A [*closed billing period*](#glossary:closed-billing-period) represents a billing period for which all planned invoices have been successfully issued by the designated Invoice Issuer. This status indicates that the billing period is financially closed, and no additional invoices will be associated with that timeframe. This approach establishes a clear temporal boundary between billing cycles. Exceptionally, additional invoices may be issued for a closed billing period only if explicitly requested by the end-user. +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. -The ability to determine whether a billing period is "open" or "closed" must be documented by the Invoice Issuer and made accessible to practitioners. +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. -For information on *corrections* to *closed billing periods*, refer to the [Correction Handling](#correctionhandling) section. +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 @@ -36,30 +45,21 @@ 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 artifacts. +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 Cost and Usage dataset artifacts. -* If an invoice-level *charge* appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. -* *Invoice reconciliation* MUST include (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. -* *Invoice reconciliation* MUST be performed by the Invoice Issuer before issuing an invoice. -* Cost and usage data presented on an invoice and included in *invoice reconciliation* MUST be documented by the Invoice Issuer and accessible to practitioners. -* Cost and usage data presented on an *issued invoice* MUST NOT be altered. -* Billing period MUST be considered "open" until all planned invoices for that period have been issued. -* Billing period MUST be considered "closed" when all planned invoices for that period have been issued. -* Ability to determine whether a billing period is "open" or "closed" MUST be documented by the Invoice Issuer and accessible to practitioners. -* Additional invoice MUST NOT be associated with a *closed billing period*. +* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in a FOCUS dataset. +* If cost or usage appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. +* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. +* The contents of a FOCUS dataset associated with an *issued invoice* MUST NOT be altered after final delivery, except in the cases of explicit user request or the resolution of technical issues. ## Exceptions * Informational line items that have zero monetary impact and are included solely for transparency MAY be excluded. Examples include: * Tax exemption notifications * SLA credit details when the credit is already applied to the charged amount -* If such informational items are excluded, providers MUST document this in their FOCUS implementation guide and ensure the sum of included charges still equals the invoice total. -* Exceptions to the restrictions on *issued invoices* and *closed billing periods* 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. +* 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. ## Introduced (version) diff --git a/specification/glossary.md b/specification/glossary.md index caecf0463..76cda5152 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -126,9 +126,13 @@ The collection of datasets are designed to provide billing insight, additional c A Date/Time Format value that is contained within the beginning bound of a time period. +Invoice + +A formal document that reflects the charges for resources or services consumed by a customer. + Invoice Reconciliation -The process of reconciling the invoice (i.e., the metrics and dimensions presented on an invoice) with the underlying [*charges*](#glossary:charge) provided in the FOCUS Cost and Usage dataset artifacts, ensuring alignment between invoice content and associated charges. Data presented on an invoice is typically derived through aggregation of cost and usage charges. The aggregation set and the scope of reconciliation are defined by a subset of metrics and dimensions present in the FOCUS cost and usage charges, including but not limited to: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. +The process of ensuring that the aggregated cost and usage information presented on an [*invoice*](#glossary:invoice) matches the detailed cost and usage [*charges*](#glossary:charge) presented in a [*FOCUS dataset](#glossary:FOCUS-dataset). Interruptible From 45084cb19289619750f164cbcb58a91ec991e044 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:49:19 -0700 Subject: [PATCH 55/71] linter fix --- specification/attributes/attributes.mdpp | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index 4b46a3310..58e3ea286 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -6,6 +6,7 @@ Attributes are requirements that apply either across a [*FOCUS dataset*](#glossa !INCLUDE "correction_handling.md",1 !INCLUDE "currency_format.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 From 060b820e41d382a0e91aab200fd993a33f3ed994 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:57:54 -0700 Subject: [PATCH 56/71] linter fixes --- specification/attributes/delivery_handling.md | 4 ++-- specification/attributes/invoice_handling.md | 4 ++-- specification/datasets/cost_and_usage/dataset.md | 1 + 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md index dc8d0c635..59091ada3 100644 --- a/specification/attributes/delivery_handling.md +++ b/specification/attributes/delivery_handling.md @@ -6,7 +6,7 @@ The Delivery Handling attribute defines how a data generator delivers a *dataset ### Delivery Mechanisms -FOCUS supports two delivery mechanisms: +FOCUS supports two delivery mechanisms: * Overwrite. Existing rows are replaced. * Append. Existing rows are preserved. @@ -17,7 +17,7 @@ For more information on corrections, see the [Correction Handling attribute](*co #### 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. +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: diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 85135f0d4..289a4457e 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -2,7 +2,7 @@ ## Overview -The Invoice Handling attribute defines how a [*FOCUS dataset*](#glossary:FOCUS-dataset) should reflect details for the information presented on an [*invoice*](#glossary:invoice). +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. @@ -12,7 +12,7 @@ FinOps practitioners must be able to reconcile *FOCUS datasets* with the corresp 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: +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) diff --git a/specification/datasets/cost_and_usage/dataset.md b/specification/datasets/cost_and_usage/dataset.md index ea30346be..7508cb0d6 100644 --- a/specification/datasets/cost_and_usage/dataset.md +++ b/specification/datasets/cost_and_usage/dataset.md @@ -86,6 +86,7 @@ The CostAndUsage dataset adheres to the following requirements: * CostAndUsage MUST conform to [ColumnHandling](#columnhandling) requirements. * CostAndUsage MUST conform to [CorrectionHandling](#correctionhandling) requirements. +* CostAndUsage MUST conform to [DeliveryHandling](#deliveryhandling) requirements. * CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [NullHandling](#nullhandling) requirements. * CostAndUsage MUST conform to [InvoiceHandling](#invoicehandling) requirements. From 70e437d6505b8a004edad33aa96502ff4147cb1f Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Fri, 3 Oct 2025 15:02:37 -0700 Subject: [PATCH 57/71] typo --- specification/attributes/invoice_handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 289a4457e..ff2ae82dd 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -51,7 +51,7 @@ Defines how a *FOCUS dataset* should reflect details for the information present * All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in a FOCUS dataset. * If cost or usage appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. -* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuer, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. +* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuerName, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. * The contents of a FOCUS dataset associated with an *issued invoice* MUST NOT be altered after final delivery, except in the cases of explicit user request or the resolution of technical issues. ## Exceptions From e6451df98e32bf3f2d48d024ce7b7408cfa3443d Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sat, 4 Oct 2025 13:15:31 -0700 Subject: [PATCH 58/71] revised draft --- .../attributes/correction_handling.md | 30 ++++++++++++++----- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index 5bfd438a9..e58117a87 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -8,10 +8,10 @@ Corrections may include some combination of added, updated, or removed *rows*. C Accurate correction handling is essential for a range of business-critical processes, including but not limited to: -* Temporal accuracy - capturing both when the 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 remains unchanged and aligned with associated underlying charges provided in the FOCUS dataset artifacts, while any related corrections do not compromise invoice reconciliation. -* Cost allocation and chargeback - attributing corrections to the correct dimensions (e.g., Billing Account, Sub Account, SKU ID, SKU Price ID, Resource ID) to ensure accurate downstream processing. -* Auditability - tracing the full lifecycle of a charge from the original record through all subsequent corrections. +* 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 @@ -23,19 +23,33 @@ FOCUS supports three correction styles: | Delta | Append | Existing records are preserved, modified by new records. | | Ledger | Append | Existing records are preserved, fully debited by new records, and then credited by more new records. | -For more information on delivery mechanisms, see the [Delivery Handling attribute](#deliveryhandling). +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. Given that historical data is discarded, this style lacks inherent auditability. +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 previous versions of *charges* are discarded, this style lacks inherent auditability. #### Delta Corrections -In the Revision correction style, a given *dataset artifact* uses the Append delivery mechanism to add records that update or supplement previous *dataset artifacts* within a *billing period*. Updates increment or decrement values in selected cost- and quantity-related columns, while all other columns remain unchanged. 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. This style offers limited inherent auditability. +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*. + +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*. + +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. + +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 style of debits and credits 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. This style offers full inherent auditability. +In the Ledger correction style, a given *dataset artifact* uses the Append delivery mechanism in combination with a double-entry bookkeeping method of debits and credits 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*. + +This style offers full inherent auditability. ### Corrections to Issued Charges From f0101cd52c01bcc5795354e4ed243378f2591d61 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sat, 4 Oct 2025 13:55:06 -0700 Subject: [PATCH 59/71] updates per recommendations from @ijurica --- specification/attributes/delivery_handling.md | 10 +++++----- specification/attributes/invoice_handling.md | 5 +++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md index 59091ada3..245ce27ed 100644 --- a/specification/attributes/delivery_handling.md +++ b/specification/attributes/delivery_handling.md @@ -17,9 +17,9 @@ For more information on corrections, see the [Correction Handling attribute](*co #### 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. +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: +Subsequent *dataset artifacts* using the Overwrite mechanism may include the following: * Unchanged records are carried over. * Updated records overwrite previous values. @@ -28,9 +28,9 @@ Subsequent dataset artifacts using the Overwrite mechanism may include the follo #### 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. +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 Replace mechanism may include the following: +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. @@ -54,7 +54,7 @@ Defines how a data generator delivers a *dataset artifact* to a customer. The delivery of a *dataset artifact* adheres to the following requirements: * A FOCUS *dataset artifact* SHOULD be delivered using either the Overwrite or Append delivery mechanism. -* The delivery mechanism(s) used to correct FOCUS dataset artifacts MUST be documented by the data generator. +* The delivery mechanism(s) used to deliver FOCUS *dataset artifacts* MUST be documented by the data generator. ## Exceptions diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index ff2ae82dd..2e4a79718 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -51,8 +51,9 @@ Defines how a *FOCUS dataset* should reflect details for the information present * All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in a FOCUS dataset. * If cost or usage appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. -* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: BilledCost, BillingCurrency, InvoiceId, InvoiceIssuerName, BillingAccountId, BillingPeriodStart, and BillingPeriodEnd. -* The contents of a FOCUS dataset associated with an *issued invoice* MUST NOT be altered after final delivery, except in the cases of explicit user request or the resolution of technical issues. +* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: *BilledCost*, *BillingCurrency*, *InvoiceId*, *InvoiceIssuerName*, *BillingAccountId*, *BillingPeriodStart*, and *BillingPeriodEnd*. +* Values presented on an *issued invoice* MUST match [*BilledCost*](#billedcost) when aggregated by the relevant combination of the following dimensions: *BillingCurrency*, *InvoiceId*, *InvoiceIssuerName*, *BillingAccountId*, *BillingPeriodStart*, and *BillingPeriodEnd*. +* The data generator MUST notify the customer if the contents of a *dataset artifact* associated with an *issued invoice* are altered after final delivery. ## Exceptions From 83faca9c8becef7032cd6e379127b06a289815c8 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sat, 4 Oct 2025 14:21:35 -0700 Subject: [PATCH 60/71] revise correction verbiage --- .../attributes/correction_handling.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index e58117a87..b64b51c98 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -15,13 +15,13 @@ Accurate correction handling is essential for a range of business-critical proce ### Correction Styles -FOCUS supports three correction styles: +FOCUS supports three styles for correcting original records: | Correction Style | Delivery Mechanism | Correction Style Description | | ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------- | -| Replacement | Overwrite | Existing records are replaced by new records. | -| Delta | Append | Existing records are preserved, modified by new records. | -| Ledger | Append | Existing records are preserved, fully debited by new records, and then credited by more new records. | +| 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). @@ -31,25 +31,25 @@ In the Replacement correction style, a given *dataset artifact* uses the Overwri 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 previous versions of *charges* are discarded, this style lacks inherent auditability. +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*. -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*. - 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. -This style offers limited inherent auditability. +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 debits and credits 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. +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*. -This style offers full inherent auditability. +Given that the entire change history is presented, this style offers full inherent auditability. ### Corrections to Issued Charges From 779f780001b53427908103ce4d21b46655b9bcc6 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sat, 4 Oct 2025 14:24:12 -0700 Subject: [PATCH 61/71] Typos --- specification/attributes/correction_handling.md | 4 ++-- specification/attributes/delivery_handling.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/attributes/correction_handling.md b/specification/attributes/correction_handling.md index b64b51c98..969b0a573 100644 --- a/specification/attributes/correction_handling.md +++ b/specification/attributes/correction_handling.md @@ -81,8 +81,8 @@ Defines how *corrections* to a previously delivered FOCUS *dataset artifact* are 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. +* 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. diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md index 245ce27ed..3742cc26f 100644 --- a/specification/attributes/delivery_handling.md +++ b/specification/attributes/delivery_handling.md @@ -35,7 +35,7 @@ Subsequent *dataset artifacts* using the Append mechanism may include the follow * Unchanged recorded are not included. * Updated records are recorded as new entries, representing the difference. * Additional records supplement previously delivered data. -* Ommitted records are recorded as new entries, representing the reversal. +* Omitted records are recorded as new entries, representing the reversal. ## Attribute ID From 24da9e52647d91e5810f7dbb2a85111340b5ac1d Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sun, 5 Oct 2025 13:35:40 -0700 Subject: [PATCH 62/71] Apply suggestions from code review with @ijurica Co-authored-by: Irena Jurica --- specification/attributes/delivery_handling.md | 1 - specification/attributes/invoice_handling.md | 23 +++++++++++-------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/specification/attributes/delivery_handling.md b/specification/attributes/delivery_handling.md index 3742cc26f..dc6bad38a 100644 --- a/specification/attributes/delivery_handling.md +++ b/specification/attributes/delivery_handling.md @@ -53,7 +53,6 @@ Defines how a data generator delivers a *dataset artifact* to a customer. The delivery of a *dataset artifact* adheres to the following requirements: -* A FOCUS *dataset artifact* SHOULD be delivered using either the Overwrite or Append delivery mechanism. * The delivery mechanism(s) used to deliver FOCUS *dataset artifacts* MUST be documented by the data generator. ## Exceptions diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 2e4a79718..fa2ee534f 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -12,14 +12,14 @@ FinOps practitioners must be able to reconcile *FOCUS datasets* with the corresp 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: +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) +* [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. @@ -49,11 +49,14 @@ Defines how a *FOCUS dataset* should reflect details for the information present ## Requirements -* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in a FOCUS dataset. +* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in one or more FOCUS *dataset artifacts*. * If cost or usage appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. -* An invoice issuer MUST reconcile an invoice with its associated FOCUS dataset artifacts before issuing an invoice. The scope of that reconciliation includes (but is not limited to) the following metrics and dimensions: *BilledCost*, *BillingCurrency*, *InvoiceId*, *InvoiceIssuerName*, *BillingAccountId*, *BillingPeriodStart*, and *BillingPeriodEnd*. -* Values presented on an *issued invoice* MUST match [*BilledCost*](#billedcost) when aggregated by the relevant combination of the following dimensions: *BillingCurrency*, *InvoiceId*, *InvoiceIssuerName*, *BillingAccountId*, *BillingPeriodStart*, and *BillingPeriodEnd*. +* *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 From 10cecd77c4cfcced4eaa61246f01ed8c9f249357 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sun, 5 Oct 2025 13:46:46 -0700 Subject: [PATCH 63/71] Apply suggestions from code review Co-authored-by: Irena Jurica --- specification/datasets/cost_and_usage/columns/chargeclass.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/datasets/cost_and_usage/columns/chargeclass.md b/specification/datasets/cost_and_usage/columns/chargeclass.md index b5ee341ca..f47ef1b3f 100644 --- a/specification/datasets/cost_and_usage/columns/chargeclass.md +++ b/specification/datasets/cost_and_usage/columns/chargeclass.md @@ -7,7 +7,7 @@ The ChargeClass column adheres to the following requirements: * ChargeClass MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). * ChargeClass MUST be of type String. * ChargeClass nullability is defined as follows: - * ChargeClass MUST be null when the *charge* does not represent a correction or when it represents a correction within the current *billing period*. + * ChargeClass MUST be null when the *charge* does not represent a correction to a previously *closed billing period*. * ChargeClass MUST NOT be null when the *charge* represents a correction to a previously *closed billing period*. * ChargeClass MUST be "Correction" when ChargeClass is not null. From eaa9807586b2c461b9e9a2d8ae518d0183d8693a Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sun, 5 Oct 2025 13:57:28 -0700 Subject: [PATCH 64/71] Update glossary.md --- specification/glossary.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index 76cda5152..7d56dd9d4 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -94,6 +94,10 @@ The term "Correction" (capitalized) refers specifically to an allowed value in t A financial incentive or allowance granted by a provider unrelated to other past/current/future charges. +Dataset Artifact + +A physical representation of a [*FOCUS dataset*](#glossary:FOCUS-dataset) delivered by a data generator. + Dimension A specification-defined categorical attribute that provides context or categorization to billing data. @@ -116,9 +120,9 @@ An open-source specification that defines requirements for billing data. FOCUS Dataset -A FOCUS dataset is a structured collection of records that conforms to the BCP14 criteria established by FOCUS. All columns included must be defined in the FOCUS Columns section of the specification. +A structured collection of columns that conforms to the BCP14 criteria established by FOCUS. All columns included must be defined in the FOCUS Columns section of the specification. -In addition to these standardized columns, data generators may include custom provider-specific columns (prefixed with `x_`) where additional context is needed beyond what is captured in the defined FOCUS columns. If such custom columns introduce record-splitting (i.e., a single original charge results in multiple rows), the data generator is responsible for ensuring that all cost and quantity metrics still meet the aggregation and consistency rules required by the specification. +In addition to these standardized columns, data generators may include custom provider-specific columns (prefixed with `x_`) where additional context is needed beyond what is captured in the defined FOCUS columns. If custom provider-specific columns introduce record-splitting (i.e., a single original charge results in multiple rows), the data generator is responsible for ensuring that all cost and quantity metrics still meet the aggregation and consistency rules required by the specification. The collection of datasets are designed to provide billing insight, additional context, metadata, mapping, or enrichment information that enhances the interpretability or completeness. From e6206b92866d84e20944dd7e512baa8daf8821f5 Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sun, 5 Oct 2025 14:00:08 -0700 Subject: [PATCH 65/71] Update specification/glossary.md --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 7d56dd9d4..947aac792 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -132,7 +132,7 @@ A Date/Time Format value that is contained within the beginning bound of a time Invoice -A formal document that reflects the charges for resources or services consumed by a customer. +A document that summarizes the charges for resources or services consumed by a customer. Invoice Reconciliation From e29121c575bd4ecb08653b1b851706ef46bc6f4d Mon Sep 17 00:00:00 2001 From: Shawn Alpay <77511110+shawnalpay@users.noreply.github.com> Date: Sun, 5 Oct 2025 14:02:16 -0700 Subject: [PATCH 66/71] Update specification/glossary.md --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 947aac792..6ccb3400f 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -136,7 +136,7 @@ A document that summarizes the charges for resources or services consumed by a c Invoice Reconciliation -The process of ensuring that the aggregated cost and usage information presented on an [*invoice*](#glossary:invoice) matches the detailed cost and usage [*charges*](#glossary:charge) presented in a [*FOCUS dataset](#glossary:FOCUS-dataset). +The process of ensuring that the aggregated cost and usage information presented on an [*invoice*](#glossary:invoice) matches the detailed cost and usage [*charges*](#glossary:charge) presented in a [*FOCUS dataset*](#glossary:FOCUS-dataset). Interruptible From cbfb87f4a9424170af9eaf5cfbfde6296eaf9626 Mon Sep 17 00:00:00 2001 From: ijurica Date: Mon, 17 Nov 2025 17:22:56 +0100 Subject: [PATCH 67/71] FOCUS #962: Left over - Merge remote-tracking branch 'origin/working_draft' into 962-correction-handling-attribute-shawn-refactor --- .../datasets/cost_and_usage/dataset.md | 152 +++++++++--------- 1 file changed, 79 insertions(+), 73 deletions(-) diff --git a/specification/datasets/cost_and_usage/dataset.md b/specification/datasets/cost_and_usage/dataset.md index 7508cb0d6..32ce6db48 100644 --- a/specification/datasets/cost_and_usage/dataset.md +++ b/specification/datasets/cost_and_usage/dataset.md @@ -2,95 +2,101 @@ The Cost and Usage dataset is the primary dataset for FOCUS cost and usage data. -The specification for the Cost and Usage dataset defines a group of columns that provide qualitative values (such as dates, resource, and provider information) categorized as "dimensions" and quantitative values (numeric values) categorized as "metrics" that can be used for performing various [FinOps capabilities][FODOFC]. Metrics are commonly used for aggregations (sum, multiplication, averaging etc.) and statistical operations within the dataset. Dimensions are commonly used to categorize, filter, and reveal details in your data when combined with metrics. The columns are presented in alphabetical order. +The specification for the Cost and Usage dataset defines a group of columns that provide qualitative values (such as dates, resource, and service provider information) categorized as "dimensions" and quantitative values (numeric values) categorized as "metrics" that can be used for performing various [FinOps capabilities][FODOFC]. Metrics are commonly used for aggregations (sum, multiplication, averaging etc.) and statistical operations within the dataset. Dimensions are commonly used to categorize, filter, and reveal details in your data when combined with metrics. The columns are presented in alphabetical order.
Columns
-| Column | Column Type | Feature Level | Allows Nulls | Data Type | -| ----------------------------------------------------------------------------- | ----------- | ------------- | ------------ | --------- | -| [Allocated Method ID](#allocatedmethodid) | Dimension | Conditional | True | String | -| [Allocated Method Details](#allocatedmethoddetails) | Dimension | Recommended | True | JSON | -| [Allocated Resource ID](#allocatedresourceid) | Dimension | Conditional | True | String | -| [Allocated Resource Name](#allocatedresourcename) | Dimension | Conditional | True | String | -| [Allocated Tags](#allocatedtags) | Dimension | Conditional | True | JSON | -| [Availability Zone](#availabilityzone) | Dimension | Recommended | True | String | -| [Billed Cost](#billedcost) | Metric | Mandatory | False | Decimal | -| [Billing Account ID](#billingaccountid) | Dimension | Mandatory | False | String | -| [Billing Account Name](#billingaccountname) | Dimension | Mandatory | True | String | -| [Billing Account Type](#billingaccounttype) | Dimension | Conditional | False | String | -| [Billing Currency](#billingcurrency) | Dimension | Mandatory | False | String | -| [Billing Period End](#billingperiodend) | Dimension | Mandatory | False | Date/Time | -| [Billing Period Start](#billingperiodstart) | Dimension | Mandatory | False | Date/Time | -| [Capacity Reservation ID](#capacityreservationid) | Dimension | Conditional | True | String | -| [Capacity Reservation Status](#capacityreservationstatus) | Dimension | Conditional | True | String | -| [Charge Category](#chargecategory) | Dimension | Mandatory | False | String | -| [Charge Class](#chargeclass) | Dimension | Mandatory | True | String | -| [Charge Description](#chargedescription) | Dimension | Mandatory | True | String | -| [Charge Frequency](#chargefrequency) | Dimension | Recommended | False | String | -| [Charge Period End](#chargeperiodend) | Dimension | Mandatory | False | Date/Time | -| [Charge Period Start](#chargeperiodstart) | Dimension | Mandatory | False | Date/Time | -| [Commitment Discount Category](#commitmentdiscountcategory) | Dimension | Conditional | True | String | -| [Commitment Discount ID](#commitmentdiscountid) | Dimension | Conditional | True | String | -| [Commitment Discount Name](#commitmentdiscountname) | Dimension | Conditional | True | String | -| [Commitment Discount Quantity](#commitmentdiscountquantity) | Metric | Conditional | True | Decimal | -| [Commitment Discount Status](#commitmentdiscountstatus) | Dimension | Conditional | True | String | -| [Commitment Discount Type](#commitmentdiscounttype) | Dimension | Conditional | True | String | -| [Commitment Discount Unit](#commitmentdiscountunit) | Dimension | Conditional | True | String | -| [Consumed Quantity](#consumedquantity) | Metric | Conditional | True | Decimal | -| [Consumed Unit](#consumedunit) | Dimension | Conditional | True | String | +| Column | Column Type | Feature Level | Allows Nulls | Data Type | +| ----------------------------------------------------------------------------- | ------------------ | ------------- | ------------ | --------- | +| [Allocated Method Details](#allocatedmethoddetails) | Dimension | Recommended | True | JSON | +| [Allocated Method ID](#allocatedmethodid) | Dimension | Conditional | True | String | +| [Allocated Resource ID](#allocatedresourceid) | Dimension | Conditional | True | String | +| [Allocated Resource Name](#allocatedresourcename) | Dimension | Conditional | True | String | +| [Allocated Tags](#allocatedtags) | Dimension | Conditional | True | JSON | +| [Availability Zone](#availabilityzone) | Dimension | Recommended | True | String | +| [Billed Cost](#billedcost) | Metric | Mandatory | False | Decimal | +| [Billing Account ID](#billingaccountid) | Dimension | Mandatory | False | String | +| [Billing Account Name](#billingaccountname) | Dimension | Mandatory | True | String | +| [Billing Account Type](#billingaccounttype) | Dimension | Conditional | False | String | +| [Billing Currency](#billingcurrency) | Dimension | Mandatory | False | String | +| [Billing Period End](#billingperiodend) | Dimension | Mandatory | False | Date/Time | +| [Billing Period Start](#billingperiodstart) | Dimension | Mandatory | False | Date/Time | +| [Capacity Reservation ID](#capacityreservationid) | Dimension | Conditional | True | String | +| [Capacity Reservation Status](#capacityreservationstatus) | Dimension | Conditional | True | String | +| [Charge Category](#chargecategory) | Dimension | Mandatory | False | String | +| [Charge Class](#chargeclass) | Dimension | Mandatory | True | String | +| [Charge Description](#chargedescription) | Dimension | Mandatory | True | String | +| [Charge Frequency](#chargefrequency) | Dimension | Recommended | False | String | +| [Charge Period End](#chargeperiodend) | Dimension | Mandatory | False | Date/Time | +| [Charge Period Start](#chargeperiodstart) | Dimension | Mandatory | False | Date/Time | +| [Commitment Discount Category](#commitmentdiscountcategory) | Dimension | Conditional | True | String | +| [Commitment Discount ID](#commitmentdiscountid) | Dimension | Conditional | True | String | +| [Commitment Discount Name](#commitmentdiscountname) | Dimension | Conditional | True | String | +| [Commitment Discount Quantity](#commitmentdiscountquantity) | Metric | Conditional | True | Decimal | +| [Commitment Discount Status](#commitmentdiscountstatus) | Dimension | Conditional | True | String | +| [Commitment Discount Type](#commitmentdiscounttype) | Dimension | Conditional | True | String | +| [Commitment Discount Unit](#commitmentdiscountunit) | Dimension | Conditional | True | String | +| [Consumed Quantity](#consumedquantity) | Metric | Conditional | True | Decimal | +| [Consumed Unit](#consumedunit) | Dimension | Conditional | True | String | | [Contract Applied](#contractapplied) | Dimension / Metric | Conditional | True | JSON | -| [Contracted Cost](#contractedcost) | Metric | Mandatory | False | Decimal | -| [Contracted Unit Price](#contractedunitprice) | Metric | Conditional | True | Decimal | -| [Effective Cost](#effectivecost) | Metric | Mandatory | False | Decimal | -| [Invoice ID](#invoiceid) | Dimension | Recommended | True | String | -| [Invoice Issuer](#invoiceissuername) | Dimension | Mandatory | False | String | -| [List Cost](#listcost) | Metric | Mandatory | False | Decimal | -| [List Unit Price](#listunitprice) | Metric | Conditional | True | Decimal | -| [Pricing Category](#pricingcategory) | Dimension | Conditional | True | String | -| [Pricing Currency Contracted Unit Price](#pricingcurrencycontractedunitprice) | Metric | Conditional | True | Decimal | -| [Pricing Currency Effective Cost](#pricingcurrencyeffectivecost) | Metric | Conditional | True | Decimal | -| [Pricing Currency List Unit Price](#pricingcurrencylistunitprice) | Metric | Conditional | True | Decimal | -| [Pricing Currency](#pricingcurrency) | Dimension | Conditional | True | String | -| [Pricing Quantity](#pricingquantity) | Metric | Mandatory | True | Decimal | -| [Pricing Unit](#pricingunit) | Dimension | Mandatory | True | String | -| [Provider](#providername) | Dimension | Mandatory | False | String | -| [Publisher](#publishername) | Dimension | Mandatory | False | String | -| [Region ID](#regionid) | Dimension | Conditional | True | String | -| [Region Name](#regionname) | Dimension | Conditional | True | String | -| [Resource ID](#resourceid) | Dimension | Conditional | True | String | -| [Resource Name](#resourcename) | Dimension | Conditional | True | String | -| [Resource Type](#resourcetype) | Dimension | Conditional | True | String | -| [Service Category](#servicecategory) | Dimension | Mandatory | False | String | -| [Service Name](#servicename) | Dimension | Mandatory | False | String | -| [Service Subcategory](#servicesubcategory) | Dimension | Recommended | False | String | -| [SKU ID](#skuid) | Dimension | Conditional | True | String | -| [SKU Meter](#skumeter) | Dimension | Conditional | True | String | -| [SKU Price Details](#skupricedetails) | Dimension | Conditional | True | JSON | -| [SKU Price ID](#skupriceid) | Dimension | Conditional | True | String | -| [Sub Account ID](#subaccountid) | Dimension | Conditional | True | String | -| [Sub Account Name](#subaccountname) | Dimension | Conditional | True | String | -| [Sub Account Type](#subaccounttype) | Dimension | Conditional | True | String | -| [Tags](#tags) | Dimension | Conditional | True | JSON | +| [Contracted Cost](#contractedcost) | Metric | Mandatory | False | Decimal | +| [Contracted Unit Price](#contractedunitprice) | Metric | Conditional | True | Decimal | +| [Effective Cost](#effectivecost) | Metric | Mandatory | False | Decimal | +| [Host Provider Name](#hostprovidername) | Dimension | Mandatory | False | String | +| [Invoice ID](#invoiceid) | Dimension | Recommended | True | String | +| [Invoice Issuer Name](#invoiceissuername) | Dimension | Mandatory | False | String | +| [List Cost](#listcost) | Metric | Mandatory | False | Decimal | +| [List Unit Price](#listunitprice) | Metric | Conditional | True | Decimal | +| [Pricing Category](#pricingcategory) | Dimension | Conditional | True | String | +| [Pricing Currency](#pricingcurrency) | Dimension | Conditional | True | String | +| [Pricing Currency Contracted Unit Price](#pricingcurrencycontractedunitprice) | Metric | Conditional | True | Decimal | +| [Pricing Currency Effective Cost](#pricingcurrencyeffectivecost) | Metric | Conditional | True | Decimal | +| [Pricing Currency List Unit Price](#pricingcurrencylistunitprice) | Metric | Conditional | True | Decimal | +| [Pricing Quantity](#pricingquantity) | Metric | Mandatory | True | Decimal | +| [Pricing Unit](#pricingunit) | Dimension | Mandatory | True | String | +| [Provider - DEPRECATED](#providername) | Dimension | Mandatory | False | String | +| [Publisher - DEPRECATED](#publishername) | Dimension | Mandatory | False | String | +| [Region ID](#regionid) | Dimension | Conditional | True | String | +| [Region Name](#regionname) | Dimension | Conditional | True | String | +| [Resource ID](#resourceid) | Dimension | Conditional | True | String | +| [Resource Name](#resourcename) | Dimension | Conditional | True | String | +| [Resource Type](#resourcetype) | Dimension | Conditional | True | String | +| [Service Category](#servicecategory) | Dimension | Mandatory | False | String | +| [Service Name](#servicename) | Dimension | Mandatory | False | String | +| [Service Provider Name](#serviceprovidername) | Dimension | Mandatory | False | String | +| [Service Subcategory](#servicesubcategory) | Dimension | Recommended | False | String | +| [SKU ID](#skuid) | Dimension | Conditional | True | String | +| [SKU Meter](#skumeter) | Dimension | Conditional | True | String | +| [SKU Price Details](#skupricedetails) | Dimension | Conditional | True | JSON | +| [SKU Price ID](#skupriceid) | Dimension | Conditional | True | String | +| [Sub Account ID](#subaccountid) | Dimension | Conditional | True | String | +| [Sub Account Name](#subaccountname) | Dimension | Conditional | True | String | +| [Sub Account Type](#subaccounttype) | Dimension | Conditional | True | String | +| [Tags](#tags) | Dimension | Conditional | True | JSON |
Relationships
-The Cost and Usage dataset can be joined to the Contract Commitment dataset through the use of the Contract Commitment ID field. +The Cost and Usage dataset can be joined to the Contract Commitment dataset through the use of the Contract Commitment ID. -| Dataset A | Dataset A Column | Dataset B | Dataset B Column | -| ------------------- | ---------------------- | ------------------- | ---------------------- | -| Cost and Usage | Contract Commitment ID | Contract Commitment | Contract Commitment ID | +* In the Cost and Usage dataset, Contract Commitment ID is a property within a JSON object array provided in Contract Applied column. +* In the Contract Commitment dataset, Contract Commitment ID is a column. + +| Dataset A | Dataset A Column | Dataset B | Dataset B Column | +| ------------------- | ----------------- | ------------------- | ---------------------- | +| Cost and Usage | Contract Applied | Contract Commitment | Contract Commitment ID |
Requirements
-The CostAndUsage dataset adheres to the following requirements: +CostAndUsage adheres to the following requirements: +* CostAndUsage MUST be present. * CostAndUsage MUST conform to [ColumnHandling](#columnhandling) requirements. * CostAndUsage MUST conform to [CorrectionHandling](#correctionhandling) requirements. * CostAndUsage MUST conform to [DeliveryHandling](#deliveryhandling) requirements. -* CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [NullHandling](#nullhandling) requirements. +* CostAndUsage MUST conform to [DiscountHandling](#discounthandling) requirements. * CostAndUsage MUST conform to [InvoiceHandling](#invoicehandling) requirements. -* CostAndUsage MUST conform to [ProviderCalculatedSplitCostAllocationHandling](#provider-calculatedsplitcostallocationhandling) requirements. +* CostAndUsage MUST conform to [DataGeneratorCalculatedSplitCostAllocationHandling](#datagenerator-calculatedsplitcostallocationhandling) requirements.
Dataset ID
@@ -102,7 +108,7 @@ Cost and Usage
Description
-Describes the cost and usage incurred through using or purchasing a provider's [*resources*](#glossary:resource) or [*services*](#glossary:service). +Describes the cost and usage incurred through using or purchasing a service provider's [*resources*](#glossary:resource) or [*services*](#glossary:service).
Introduced (version)
From 6cb7cfa142935ed116d43f1f4479bffddfd86fea Mon Sep 17 00:00:00 2001 From: ijurica Date: Mon, 17 Nov 2025 18:52:41 +0100 Subject: [PATCH 68/71] FOCUS #962: Left over - Merge remote-tracking branch 'origin/working_draft' into 962-correction-handling-attribute-shawn-refactor --- specification/glossary.md | 63 +++++++++++++++++++++++++-------------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index 6ccb3400f..398e0d333 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -6,15 +6,15 @@ A charge representing a modification to billing data to account for certain even Allocated Charge -The [charge](#glossary:charge) that was created as the result of an allocation operation. This is used in the context of [Provider-Calculated Split Cost Allocation](#providercalculatedsplitcosthandling) to identify the charges that were created from the [origin charge](#glossary:origin-charge) resulting from the application of Provider-Calculated Split Cost Allocation. +The [charge](#glossary:charge) that was created as the result of an allocation operation. This is used in the context of [Data Generator-Calculated Split Cost Allocation](#datagenerator-calculatedsplitcostallocation) to identify the charges that were created from the [origin charge](#glossary:origin-charge) resulting from the application of Data Generator-Calculated Split Cost Allocation. Allocated Method -The process or formula by which cost is being allocated from an [origin charge](#glossary:origin-charge) to produce [allocated charges](#glossary:allocated-charge). This is used in the context of [Provider-Calculated Split Cost Allocation](#providercalculatedsplitcosthandling) which requires documentation of the method to be provided for any and all allocated methods used. May also be colloquially referred to as allocation method. +The process or formula by which cost is being allocated from an [origin charge](#glossary:origin-charge) to produce [allocated charges](#glossary:allocated-charge). This is used in the context of [Data Generator-Calculated Split Cost Allocation](#datagenerator-calculatedsplitcostallocation) which requires documentation of the method to be provided for any and all allocated methods used. May also be colloquially referred to as allocation method. Amortization -The distribution of upfront costs over time to accurately reflect the consumption or benefit derived from the associated resources or services. Amortization is valuable when the commitment period (time duration of the cost) extends beyond the granularity of the source report. +The distribution of upfront costs over time to accurately reflect the consumption or benefit derived from the associated resources or services. Amortization is valuable when the commitment [*period*](#glossary:period) extends beyond the granularity of the source report. Availability Zone @@ -50,7 +50,7 @@ A row in a FOCUS-compatible cost and usage dataset. Charge Period -The time window for which a charge is effective, inclusive of the start date and exclusive of the end date. The charge period for continuous usage should match the time granularity of the dataset (e.g., 1 hour for hourly, 1 day for daily). The charge period for a non-usage charge with time boundaries should match the duration of eligibility. +The time window for which a charge is effective, inclusive of the start date and exclusive of the end date. The charge period for continuous usage should match the time granularity of the dataset (e.g., 1 hour for hourly, 1 day for daily). The charge period for a non-usage charge with time boundaries should match the period of eligibility. Closed Billing Period @@ -62,19 +62,19 @@ A company or organization that provides remote access to computing resources, in Commitment -A customer's agreement to consume a specific quantity of a service or resource over a defined period, usually also creating a financial commitment throughout the entirety of the commitment period. Some commitments also hold Providers to certain assurance levels of resource availability. +A customer's agreement to either spend a defined monetary amount or consume a specific quantity of resources or services over a specified [*period*](#glossary:period). Commitment Discount -A billing discount model that offers reduced rates on preselected SKUs in exchange for an obligated usage or spend amount over a predefined term. Commitment discount purchases, made upfront and/or with recurring monthly payments are amortized evenly across predefined charge periods (i.e., hourly), and unused amounts cannot be carried over to subsequent charge periods. Commitment discounts are publicly available to customers without special contract arrangements. +A billing discount model that offers reduced rates on preselected SKUs in exchange for an obligated usage or spend amount over a specified [*period*](#glossary:period). Commitment discount purchases, made upfront and/or with recurring monthly payments are amortized evenly across predefined charge periods (i.e., hourly), and unused amounts cannot be carried over to subsequent charge periods. Commitment discounts are publicly available to customers without special contract arrangements. Commitment Discount Flexibility -A feature of [*commitment discounts*](#glossary:commitment-discount) that may further transform the predetermined amount of usage purchased or consumed based on additional, provider-specific requirements. +A feature of [*commitment discounts*](#glossary:commitment-discount) that may further transform the predetermined amount of usage purchased or consumed based on additional, service-provider-specific requirements. Contract -A collection of agreed terms between a provider and a customer. +A collection of agreed terms between a service provider and a customer. Contract Commitment @@ -92,7 +92,19 @@ The term "Correction" (capitalized) refers specifically to an allowed value in t Credit -A financial incentive or allowance granted by a provider unrelated to other past/current/future charges. +A financial incentive or allowance granted by a service provider unrelated to other past/current/future charges. + +Dataset Artifact + +An abbreviated term for [*dataset instance artifact*](#glossary:dataset-instance-artifact). + +Dataset Instance + +A specific implementation of a [*FOCUS dataset*](#glossary:FOCUS-dataset) provided by a [data generator](#datagenerator). A Data Generator may provide multiple dataset instances of the same *FOCUS dataset*, each with different properties such as time granularity or differing custom column inclusions. For example, the same 'FOCUS Cost and Usage' *FOCUS dataset* may be provided at an hourly or daily time granularity by a Data Generator. Each would be a distinct Dataset Instance. + +Dataset Instance Artifact + +A physical representation of a specific [*dataset instance*](#glossary:dataset-instance) delivered by a [data generator](#datagenerator). Dataset Artifact @@ -112,7 +124,7 @@ A Date/Time Format value that is not contained within the ending bound of a time Finalized Tag -A tag with one tag value chosen from a set of possible tag values after being processed by a set of provider-defined or user-defined rules. +A tag with one tag value chosen from a set of possible tag values after being processed by a set of service-provider-defined or user-defined rules. FinOps Cost and Usage Specification (FOCUS) @@ -122,7 +134,7 @@ An open-source specification that defines requirements for billing data. A structured collection of columns that conforms to the BCP14 criteria established by FOCUS. All columns included must be defined in the FOCUS Columns section of the specification. -In addition to these standardized columns, data generators may include custom provider-specific columns (prefixed with `x_`) where additional context is needed beyond what is captured in the defined FOCUS columns. If custom provider-specific columns introduce record-splitting (i.e., a single original charge results in multiple rows), the data generator is responsible for ensuring that all cost and quantity metrics still meet the aggregation and consistency rules required by the specification. +In addition to these standardized columns, [data generators](#datagenerator) may include custom columns (prefixed with `x_`) where additional context is needed beyond what is captured in the defined FOCUS columns. If custom columns introduce record-splitting (i.e., a single original charge results in multiple rows), the data generator is responsible for ensuring that all cost and quantity metrics still meet the aggregation and consistency rules required by the specification. The collection of datasets are designed to provide billing insight, additional context, metadata, mapping, or enrichment information that enhances the interpretability or completeness. @@ -151,11 +163,12 @@ An invoice that has been formally generated and released by the designated invoi A [*charge*](#glossary:charge) associated with an [*issued invoice*](glossary:issued-invoice). JSON + A common acronym for JavaScript Object Notation, a data format codified in [ECMA-404](https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf) as a standard for human-readable, serializable data objects. This data format is used in FOCUS to communicate multiple pieces of information about a charge (tags, properties, etc.) in a single column. List Unit Price -The suggested provider-published unit price for a single [Pricing Unit](#pricingunit) of the associated [SKU](#glossary:sku), exclusive of any discounts. This price is denominated in the [Billing Currency](#glossary:billing-currency). +The suggested service-provider-published unit price for a single [Pricing Unit](#pricingunit) of the associated [SKU](#glossary:sku), exclusive of any discounts. This price is denominated in the [Billing Currency](#glossary:billing-currency). Managed Service Provider (MSP) @@ -171,11 +184,11 @@ A government-issued currency (e.g., US dollars, Euros). Negotiated Discount -A contractual agreement where a customer commits to specific spend or usage goals over a [*term*](#glossary:term) in exchange for discounted rates across varying SKUs. Unlike [*commitment discounts*](#glossary:commitment-discount), negotiated discounts are typically more customized to customer's accounts, can be utilized at varying frequencies, and may overlap with *commitment discounts*. +A contractual agreement where a customer commits to specific spend or usage goals over a specified [*period*](#glossary:period) in exchange for discounted rates across varying SKUs. Unlike [*commitment discounts*](#glossary:commitment-discount), negotiated discounts are typically more customized to customer's accounts, can be utilized at varying frequencies, and may overlap with *commitment discounts*. On-Demand -A term that describes a service that is available and provided immediately or as needed, without requiring a pre-scheduled appointment or prior arrangement. In cloud computing, virtual machines can be created and terminated as needed, i.e., on demand. +A service that is available and provided immediately or as needed, without requiring a pre-scheduled appointment or prior arrangement. In cloud computing, virtual machines can be created and terminated as needed, i.e., on demand. Open Billing Period @@ -183,12 +196,16 @@ A [*billing period*](glossary:billing-period) that has not yet been financially Origin Charge -The [charge](#glossary:charge) that existed prior to an operation. This is used in the context of Provider-Calculated Split Cost Allocation to identify the charge that existed prior to the application of [Provider-Calculated Split Cost Allocation](#providercalculatedsplitcosthandling) to produce [allocated charges](#glossary:allocated-charge). +The [charge](#glossary:charge) that existed prior to an operation. This is used in the context of [Data Generator-Calculated Split Cost Allocation](#datagenerator-calculatedsplitcostallocation) to identify the charge that existed prior to the application of Data Generator-Calculated Split Cost Allocation to produce [allocated charges](#glossary:allocated-charge). Pascal Case Pascal Case (PascalCase, also known as UpperCamelCase) is a format for identifiers which contain one or more words meaning the words are concatenated together with no delimiter and the first letter of each word is capitalized. +Period + +A time window, with a specifically defined start and end date/time. + Potato A long and often painful conversation had by the FOCUS contributors. Sometimes the name of a thing that we could not yet name. No starchy root vegetables were harmed during the production of this specification. We thank potato for its contribution in the creation of this specification. @@ -199,11 +216,11 @@ An individual who performs FinOps within an organization to maximize the busines Price List -A comprehensive list of prices offered by a provider. +A comprehensive list of prices offered by a service provider. -Provider +Service Provider -An entity that made internal or 3rd party resources and/or services available for purchase. +An entity that provides the [*resources*](#glossary:resource) or [*services*](#glossary:service) available for usage or purchase. Refund @@ -219,7 +236,7 @@ A row in a FOCUS-compatible cost and usage dataset. Service -An offering that can be purchased from a provider, and can include many types of usage or other charges; eg., a cloud database service may include compute, storage, and networking charges. +An offering that can be purchased from a service provider, and can include many types of usage or other charges; eg., a cloud database service may include compute, storage, and networking charges. SKU @@ -231,7 +248,7 @@ A pricing construct that encompasses SKU properties (e.g., functionality and tec Sub Account -A sub account is an optional provider-supported construct for organizing resources and/or services connected to a billing account. Sub accounts must be associated with a billing account as they do not receive invoices. +A sub account is an optional service-provider-supported construct for organizing resources and/or services connected to a billing account. Sub accounts must be associated with a billing account as they do not receive invoices. Tag @@ -239,12 +256,12 @@ A metadata label assigned to a resource to provide information about it or to ca Tag Source -A Resource or Provider-defined construct for grouping resources and/or other Provider-defined construct that a Tag can be assigned to. +A Resource or Service-Provider-defined construct for grouping resources and/or other Service-Provider-defined construct that a Tag can be assigned to. Term -A duration of a contractual agreement like with a [*commitment discount*](#glossary:commitment-discount) or [*negotiated discount*](#glossary:negotiated-discount). +An agreement specified on a [*contract*](#glossary:contract). Virtual Currency -A proprietary currency (e.g., credits, tokens) issued by providers and independent of government regulation. +A proprietary currency (e.g., credits, tokens) issued by service providers and independent of government regulation. From 2a43eb49b0342c017a95c1735c3c23a0465fe6f7 Mon Sep 17 00:00:00 2001 From: ijurica Date: Mon, 17 Nov 2025 19:41:21 +0100 Subject: [PATCH 69/71] FOCUS #962: Left over - Merge remote-tracking branch 'origin/working_draft' into 962-correction-handling-attribute-shawn-refactor --- specification/attributes/invoice_handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index fa2ee534f..ee42fa0b5 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -49,8 +49,8 @@ Defines how a *FOCUS dataset* should reflect details for the information present ## Requirements -* All costs that appear on any invoice issued to a [*BillingAccountId*](#billingaccountid) MUST be included in one or more FOCUS *dataset artifacts*. -* If cost or usage appears on a customer invoice but cannot be expressed using existing FOCUS columns, providers 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 Cost and Usage dataset artifacts. +* 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*. * *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. From 5325496597184ed92c436056d89f9b4ecda138f4 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 18 Nov 2025 11:46:27 +0100 Subject: [PATCH 70/71] FOCUS #962: invoice handling update - dataset artifact instead of dataset --- specification/attributes/invoice_handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index ee42fa0b5..5ee3dbb98 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -49,8 +49,8 @@ Defines how a *FOCUS dataset* should reflect details for the information present ## 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. From 9606ecc897206dc63d96cdcab962db93287c8e11 Mon Sep 17 00:00:00 2001 From: ijurica Date: Tue, 18 Nov 2025 13:04:11 +0100 Subject: [PATCH 71/71] FOCUS #962: editorial updates --- specification/attributes/invoice_handling.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/attributes/invoice_handling.md b/specification/attributes/invoice_handling.md index 5ee3dbb98..a8e1c4257 100644 --- a/specification/attributes/invoice_handling.md +++ b/specification/attributes/invoice_handling.md @@ -6,13 +6,13 @@ The Invoice Handling attribute defines how a [*FOCUS dataset*](#glossary:FOCUS-d 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. +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*. +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: +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) @@ -23,17 +23,17 @@ At the conclusion of this process, the total monetary value presented on an invo 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). +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. +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. +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. -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). +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