Merge branch 'working_draft' into 547-consistency-review-correction-h…

…andling

CHANGELOG.md

@@ -5,13 +5,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 <!--
-## v1.1
+## v1.2
 
-[All unreleased changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/1.0-cr...working_draft)
+[All unreleased changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/1.1...working_draft)
 
 <br>
 -->
 
+## v1.1
+
+<sup>Announced November 2024</sup>
+
+**Added:**
+
+- `CapacityReservationId` column
+- `CapacityReservationStatus` column
+- `CommitmentDiscountQuantity` column
+- `CommitmentDiscountUnit` column
+- `ServiceSubcategory` column
+- `SkuMeter` column
+- `SkuPriceDetails` column
+- `ProviderVersion` metadata schema property
+
+**Changed:**
+
+- `CommitmentDiscountId` column updates:
+ - Must be globally unique within the provider.
+ - Should be a fully-qualified identifier.
+- `ConsumedQuantity` column updates:
+ - Must be null when `CommitmentDiscountStatus` is "Unused".
+- `ConsumedUnit` column updates:
+ - Must be null when `ChargeClass` is not "Correction" and `ChargeCategory` is not "Usage".
+ - Must be null when `ChargeClass` is not "Correction" and `ChargeCategory` is "Usage" and `CommitmentDiscountStatus` is "Unused".
+ - May be null when `ChargeCategory` is "Usage" and `ChargeClass` is "Correction".
+- `EffectiveCost` column updates:
+ - When `CommitmentDiscountStatus` is "Unused", must be the difference between the used commitment discount amount and the portion of the total commitment discount purchase applicable for the charge period.
+- `PricingCategory` column updates:
+ - Must not be "Committed" when the charge is for a commitment discount purchase.
+- `SkuPriceId` column updates:
+ - `SkuId` can be used if the provider does not have a `SkuPriceId` but other requirements must be met.
+- Metadata updates:
+ - Must be provided in the defined metadata schema.
+ - Must be an object.
+ - Must not be null.
+ - Must include a reference to the schema of the data.
+ - Schema reference must not be in the FOCUS dataset itself.
+ - Must be an accurate and complete representation of the provided FOCUS dataset.
+ - Metadata implementation should be publicly documented.
+- `SchemaId` metadata schema property updates:
+ - Recommended to be a globally unique identifier (GUID) instead of a universally unique identifier (UUID) or SemVer version.
+
+[All 1.1 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0...v1.1-cr)
+
+<br>
+
 ## v1.0
 
 <sup>Announced June 20, 2024</sup>
@@ -25,6 +72,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `ContractedUnitPrice` column
 - `RegionId` column
 - `RegionName` column
+- `DataGenerator` metadata property
+- `CreationDate` metadata schema property
+- `FocusVersion` metadata schema property
+- `SchemaId` metadata schema property
+- `ColumnName` metadata column definition property
+- `DataType` metadata column definition property
+- `NumberScale` metadata column definition property
+- `NumberPrecision` metadata column definition property
+- `ProviderTagPrefix` metadata column definition property
+- `StringEncoding` metadata column definition property
+- `StringMaxLength` metadata column definition property
 
 **Changed:**
 
@@ -104,7 +162,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - `ChargeSubcategory` column - See `ChargeCategory` and `ChargeClass` columns
 
-[All 1.0 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0-preview-cr...1.0-cr)
+[All 1.0 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v1.0-preview...v1.0)
 
 <br>
 
@@ -147,14 +205,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `AmortizedCost` column renamed to `EffectiveCost`
 - `ChargeType` column renamed to `ChargeCategory`
 
-[All 1.0-preview changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v0.5-cr...v1.0-preview-cr)
+[All 1.0-preview changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/v0.5...v1.0-preview)
 
 <br>
 
 ## v0.5
+
 <sup>Announced June 24, 2023</sup>
 
 **Added:**
+
 - `Column naming convention` attribute
 - `Currency code format` attribute
 - `Date/time format` attribute
@@ -181,7 +241,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `SubAccountId` column
 - `SubAccountName` column
 
-[All 0.5 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/7106bbe...v0.5-cr)
+[All 0.5 changes](https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/compare/7106bbe...v0.5)
 
 <br>
 
@@ -199,6 +259,8 @@ This table maps the evolution of the specification, showcasing column introducti
 | BillingCurrency | 0.5 | |
 | BillingPeriodEnd | 0.5 | |
 | BillingPeriodStart | 0.5 | |
+| CapacityReservationId | 1.1 | |
+| CapacityReservationStatus | 1.1 | |
 | ChargeType | 0.5 | Renamed to ChargeCategory in v1.0-preview |
 | ChargeCategory | 1.0-preview | Renamed from ChargeType in v1.0-preview |
 | ChargeClass | 1.0 | |
@@ -212,6 +274,8 @@ This table maps the evolution of the specification, showcasing column introducti
 | CommitmentDiscountName | 1.0-preview | |
 | CommitmentDiscountStatus | 1.0 | |
 | CommitmentDiscountType | 1.0-preview | |
+| CommitmentDiscountQuantity | 1.1 | |
+| CommitmentDiscountUnit | 1.1 | |
 | ConsumedQuantity | 1.0 | Renamed from UsageQuantity in v1.0 |
 | ConsumedUnit | 1.0 | Renamed from UsageUnit in v1.0 |
 | ContractedCost | 1.0 | |
@@ -233,7 +297,10 @@ This table maps the evolution of the specification, showcasing column introducti
 | ResourceType | 1.0-preview | |
 | ServiceCategory | 0.5 | |
 | ServiceName | 0.5 | |
+| ServiceSubcategory | 1.1 | |
 | SkuId | 1.0-preview | |
+| SkuMeter | 1.1 | |
+| SkuPriceDetails | 1.1 | |
 | SkuPriceId | 1.0-preview | |
 | SubAccountId | 0.5 | |
 | SubAccountName | 0.5 | |

specification/Makefile

@@ -25,7 +25,13 @@ else
 endif
  ./validate_includes.py columns
  ./validate_includes.py attributes
+ ./validate_includes.py metadata
+ ./validate_includes.py metadata/data_generator
+ ./validate_includes.py metadata/schema
+ ./validate_includes.py metadata/schema/column_definition
  ./validate_includes.py appendix
+ ./validate_includes.py appendix/examples
+ ./validate_includes.py appendix/examples/metadata_examples
  PYTHONPATH=../vendored/ $(MARKDOWNPP) spec.mdpp -o $@
  $(PYMARKDOWNLNT) --config markdownlnt.cfg scan $(SPEC_SOURCE_MDFILES)
  $(PYMARKDOWNLNT) --config markdownlnt.cfg scan $@

specification/appendix/commitment_discounts.md

@@ -1,8 +1,8 @@
 # Commitment Discounts
 
-A [*commitment discount*](glossary:commitment-discount) is a billing discount model that offers reduced rates on preselected [SKUs](#glossary:sku) in exchange for an obligated usage or spend amount over a predefined [*term*](glossary:term). *Commitment discounts* typically consist of purchase and usage records within cost and usage datasets.
+A [*commitment discount*](glossary:commitment-discount) is a billing discount model that offers reduced rates on preselected [*SKUs*](#glossary:sku) in exchange for an obligated usage or spend amount over a predefined [*term*](glossary:term). *Commitment discounts* typically consist of purchase and usage records within cost and usage datasets.
 
-Usage-based *commitment discounts* obligate a customer to a predetermined amount of usage over a preselected *term*. In some cases, usage-based *commitment discounts* also feature [*commitment flexibility*](glossary:commitment-flexibility) which may expand the types of *resources* that a *commitment discount* can cover. It is important to note when mixing *commitment discounts* with and without *commitment flexibility*, the `CommitmentDiscountUnit` should reflect this difference.
+Usage-based *commitment discounts* obligate a customer to a predetermined amount of usage over a preselected *term*. In some cases, usage-based *commitment discounts* also feature [*commitment discount flexibility*](glossary:commitment-discount-flexibility) which may expand the types of *resources* that a *commitment discount* can cover. It is important to note when mixing *commitment discounts* with and without *commitment discount flexibility*, the `CommitmentDiscountUnit` should reflect this difference.
 
 Spend-based commitment discounts obligate a customer to a predetermined amount of spend over a preselected *term*. In the usage examples below, each [*row*](glossary:row) measures the monetary amount of the hourly commit consumed by the *commitment discount*, so the `CommitmentDiscountUnit` chosen is "USD", or the [*billing currency*](glossary:billing-currency).
 
@@ -14,16 +14,16 @@ While customers are bound to the *term* of a *commitment discounts*, providers o
 * *No Upfront* - The *commitment discounts* is paid on a repeated basis, typically over each [*billing period*](glossary:billing-period) of the *term*.
 * *Partial Upfront* - Some of the *commitment discounts* is paid before the *term* begins, and the rest is paid repeatedly over the *term*.
 
-For example, if a customer buys a 1-year, spend-based *commitment discount* with a $1.00 hourly commit and pays with the partial option, the *commitment discount's* payment consists of a one-time purchase in the beginning of the *term* *and* monthly recurring purchases with the following totals:
+For example, if a customer buys a 1-year, spend-based *commitment discount* with a $1.00 hourly commit and pays with the partial option, the *commitment discount's* payment consists of a one-time purchase in the beginning of the *term* *and* monthly recurring purchases with the following totals:
 
-1. *One-Time* - $4,380 (`24 hours * 365 days * $1.00 * 0.5`)
-2. *Recurring* - $182.50 (`24 hours * 365 days * $1.00 / 12 months`)
+1. *One-Time* - $4,380 (`24 hours * 365 days * $1.00 * 0.5`)
+2. *Recurring* - $182.50 (`24 hours * 365 days * $1.00 / 12 months`)
 
 ## Usage
 
 Commitment discounts follow a "use-it-or-lose-it" model where the [*amortization*](glossary:amortization) of a *commitment discount's* purchase applies evenly to eligible *resources* over each [*charge period*](glossary:charge-period) of the *term*.
 
-For example, if a customer buys a spend-based *commitment discount* with a $1.00 hourly commit in January (31 days), only $1.00 is eligible for consumption for each hourly *charge period*. If a customer has eligible *resources* running during this *charge period*, an amount of up to $1.00 will be allocated to these *resources*. Conversely, if a customer does have eligible *resources* running that fully take advantage of this $1.00 during this *charge period*, then some or all of this amount will go to waste.
+For example, if a customer buys a spend-based *commitment discount* with a $1.00 hourly commit in January (31 days), only $1.00 is eligible for consumption for each hourly *charge period*. If a customer has eligible *resources* running during this *charge period*, an amount of up to $1.00 will be allocated to these *resources*. Conversely, if a customer does have eligible *resources* running that fully take advantage of this $1.00 during this *charge period*, then some or all of this amount will go to waste.
 
 ## Commitment Discounts in FOCUS
 
@@ -35,11 +35,11 @@ All *commitment discount* purchases appear with a positive `BilledCost`, `Pricin
 
 Recurring purchases are allocated across all corresponding *charge periods* of the *term* when `ChargeCategory` is "Purchase", `ChargeFrequency` is "Recurring", and `CommitmentDiscountQuantity` and `CommitmentDiscountUnit` are reflected only for that *charge period*.
 
-Using the same *commitment discount* example as above with a one-year, spend-based *commitment discount* with a $1.00 hourly commit purchased on Jan 1, 2023, various purchase options are available:
+Using the same *commitment discount* example as above with a one-year, spend-based *commitment discount* with a $1.00 hourly commit purchased on Jan 1, 2023, various purchase options are available:
 
 #### Scenario #1: All Upfront
 
-The entire *commitment discount* is billed _once_ during the first *charge period* of the *term* for $8,670 (derived as `24 hours * 365 days * $1.00`).
+The entire *commitment discount* is billed _once_ during the first *charge period* of the *term* for $8,670 (derived as `24 hours * 365 days * $1.00`).
 
 ```json
 [
@@ -63,7 +63,7 @@ The entire *commitment discount* is billed _once_ during the first *charge perio
 
 #### Scenario #2: No Upfront
 
-The *commitment discount* is billed across all 8,760 (`24 hours * 365 days`) *charge periods* of the *term* with $1.00 allocated to each *charge period* over the *term*.
+The *commitment discount* is billed across all 8,760 (`24 hours * 365 days`) *charge periods* of the *term* with $1.00 allocated to each *charge period* over the *term*.
 
 ```json
 [
@@ -89,7 +89,7 @@ The *commitment discount* is billed across all 8,760 (`24 hours * 365 days`) *ch
 
 #### Scenario #3: Partial Upfront
 
-With a 50/50 split, half of the commitment is billed _once_ during the first *charge period* of the *term* for $4,380 (derived as `24 hours * 182.5 days * $1.00`), and the other half is billed across each *charge period* over the term, derived as (`$1.00 * 8,760 hours * 0.5`). Amortized costs incur half of the amount (i.e. $0.50) from the one-time purchase and the other half from the recurring purchase.
+With a 50/50 split, half of the commitment is billed _once_ during the first *charge period* of the *term* for $4,380 (derived as `24 hours * 182.5 days * $1.00`), and the other half is billed across each *charge period* over the term, derived as (`$1.00 * 8,760 hours * 0.5`). Amortized costs incur half of the amount (i.e. $0.50) from the one-time purchase and the other half from the recurring purchase.
 
 ```json
 [
@@ -130,16 +130,16 @@ With a 50/50 split, half of the commitment is billed _once_ during the first *ch
 
 ### Usage *Rows*
 
-*Amortization* of *commitment discounts* occur similarly regardless of how *commitment discount* purchases are made. The same usage-based or spend-based amount is applied evenly across all *charge periods* and potentially allocated to eligible *resources*. Continuing with the same *commitment discount* example, a one-year, spend-based *commitment discount* with a $1.00 hourly commit and 1 *resource* (for simplicity) yields 4 types of scenarios that can occur during a *charge period*:
+*Amortization* of *commitment discounts* occur similarly regardless of how *commitment discount* purchases are made. The same usage-based or spend-based amount is applied evenly across all *charge periods* and potentially allocated to eligible *resources*. Continuing with the same *commitment discount* example, a one-year, spend-based *commitment discount* with a $1.00 hourly commit and 1 *resource* (for simplicity) yields 4 types of scenarios that can occur during a *charge period*:
 
 * Scenario #1: An eligible *resource* fully consumes the allocated amount (100% utilization)
 * Scenario #2: No eligible *resource* consumes the allocated amount (0% utilization)
 * Scenario #3: An eligible *resource* partially consumes the allocated amount (75% utilization)
-* Scenario #4: An eligible *resource* fully consumes the $1.00 hourly commit with an overage (100% utilization + overage)
+* Scenario #4: An eligible *resource* fully consumes the $1.00 hourly commit with an overage (100% utilization + overage)
 
 #### Scenario #1: An eligible *resource* fully consumes the allocated amount (100% utilization)
 
-In this scenario, one eligible *resource* runs for the full hour and consumes $1.00, so one *row* allocated to the *resource* is produced.
+In this scenario, one eligible *resource* runs for the full hour and consumes $1.00, so one *row* allocated to the *resource* is produced.
 
 ```json
 [
@@ -166,7 +166,7 @@ In this scenario, one eligible *resource* runs for the full hour and consumes $1
 
 #### Scenario #2: No eligible *resource* consumes the allocated amount (0% utilization)
 
-In this situation, the full eligible, $1.00 amount remained unutilized and results in 1 unused *row*. In this scenario, it is important to note that while `CommitmentDiscountQuantity` is not because $1 was still drawn down by the *commitment discount* even though, no *resource* was allocated, so `ConsumedQuantity` and `ConsumedUnit` are null.
+In this situation, the full eligible, $1.00 amount remained unutilized and results in 1 unused *row*. In this scenario, it is important to note that while `CommitmentDiscountQuantity` is not because $1 was still drawn down by the *commitment discount* even though, no *resource* was allocated, so `ConsumedQuantity` and `ConsumedUnit` are null.
 
 ```json
 [
@@ -193,7 +193,7 @@ In this situation, the full eligible, $1.00 amount remained unutilized and resul
 
 #### Scenario #3: An eligible *resource* partially consumes the allocated amount (75% utilization)
 
-In this scenario, one eligible *resource* runs for the full hour and consumes $0.75 of the $1.00 allocation. One *row* shows $0.75 to a *resource*, and the other *row* shows that $0.25 was unused.
+In this scenario, one eligible *resource* runs for the full hour and consumes $0.75 of the $1.00 allocation. One *row* shows $0.75 to a *resource*, and the other *row* shows that $0.25 was unused.
 
 ```json
 [
@@ -236,9 +236,9 @@ In this scenario, one eligible *resource* runs for the full hour and consumes $0
 ]
 ```
 
-#### Scenario #4: An eligible *resource* fully consumes the $1.00 hourly commit with an overage (100% utilization + overage)
+#### Scenario #4: An eligible *resource* fully consumes the $1.00 hourly commit with an overage (100% utilization + overage)
 
-In this scenario, one eligible *resource* runs for the full hour and is charged $1.50. One *row* shows that $1.00 was *amortized* from the *commitment discount*, and the other shows that $0.50 was charged as standard, on-demand spend.
+In this scenario, one eligible *resource* runs for the full hour and is charged $1.50. One *row* shows that $1.00 was *amortized* from the *commitment discount*, and the other shows that $0.50 was charged as standard, on-demand spend.
 
 ```json
 [

specification/appendix/examples/examples.mdpp

@@ -2,4 +2,4 @@
 
 *This section is non-normative.*
 
-!INCLUDE "metadata/metadata_examples.mdpp",1
+!INCLUDE "metadata_examples/metadata_examples.mdpp",1