diff --git a/EDITORIAL_GUIDELINES.md b/EDITORIAL_GUIDELINES.md index 189a612da..947acde16 100644 --- a/EDITORIAL_GUIDELINES.md +++ b/EDITORIAL_GUIDELINES.md @@ -136,7 +136,7 @@ These guidelines can be modified through a Pull Request (PR), which the members > > The **[Pricing Quantity](#pricing-quantity)** represents the volume of a given [SKU](#glossary:sku) associated with a [resource](#glossary:resource) or [service](#glossary:service) used or purchased, based on the **[Pricing Unit](#pricing-unit)**. Distinct from **[Consumed Quantity](#consumed-quantity)** (complementary to **[Consumed Unit](#consumed-unit)**), it focuses on pricing and cost, not resource and service consumption. > -> * The PricingQuantity column MUST be present in the billing data. +> * The PricingQuantity column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). > * This column MUST be of type Decimal and MUST conform to Numeric Format requirements. > * The value MAY be negative in cases where ChargeClass is "Correction". > diff --git a/specification/appendix/examples/metadata_examples/metadata_examples.mdpp b/specification/appendix/examples/metadata_examples/metadata_examples.mdpp index eae6ee5f2..971e1df8b 100644 --- a/specification/appendix/examples/metadata_examples/metadata_examples.mdpp +++ b/specification/appendix/examples/metadata_examples/metadata_examples.mdpp @@ -1,6 +1,6 @@ # Metadata Examples -The following sections contain examples of metadata provided by a hypothetical FOCUS data provider called ACME to supply the required reference between the FOCUS dataset and the schema metadata. Provider implementations will vary on how the metadata is disseminated; however, the provider's chosen metadata delivery approach should be able to support the structure represented in this example. +The following sections contain examples of metadata provided by a hypothetical FOCUS data provider called ACME to supply the required reference between the [*FOCUS dataset*](#glossary:FOCUS-dataset) and the schema metadata. Provider implementations will vary on how the metadata is disseminated; however, the provider's chosen metadata delivery approach should be able to support the structure represented in this example. In this example, the provider supports delivery of FOCUS data via file export to a data storage system. It uses JSON as the format for providing the metadata. The provider delivers data every 12 hours into a path structure described below: diff --git a/specification/appendix/examples/metadata_examples/provider_version_changed_example.md b/specification/appendix/examples/metadata_examples/provider_version_changed_example.md index ed912bacf..3284c5eed 100644 --- a/specification/appendix/examples/metadata_examples/provider_version_changed_example.md +++ b/specification/appendix/examples/metadata_examples/provider_version_changed_example.md @@ -2,7 +2,7 @@ ## Scenario -ACME specifies the optional metadata property [Provider Version](#providerversion) in their [Schema](#schema) object. They made a change to the FOCUS dataset they produce that does not adopt a new FOCUS Version, nor make a change the included columns but does impact values in the data. This example illustrates that Provider Version changes are independent of column changes, however provider version changes may include column changes. +ACME specifies the optional metadata property [Provider Version](#providerversion) in their [Schema](#schema) object. They made a change to the [*FOCUS dataset*](#glossary:FOCUS-dataset) they produce that does not adopt a new FOCUS Version, nor make a change the included columns but does impact values in the data. This example illustrates that Provider Version changes are independent of column changes, however provider version changes may include column changes. The provider creates a new schema object to represent the new schema. The provider includes both the FOCUS Version and Provider Version in the schema object. diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp index 36fe447e9..595ceebba 100644 --- a/specification/attributes/attributes.mdpp +++ b/specification/attributes/attributes.mdpp @@ -1,6 +1,6 @@ # Attributes -Attributes are requirements that apply across a FOCUS dataset instead of an individual column level. Requirements on data content can include naming +Attributes are requirements that apply across a [*FOCUS dataset*](#glossary:FOCUS-dataset) instead of an individual column level. Requirements on data content can include naming conventions, data types, formatting standardizations, etc. Attributes may introduce high-level requirements for data granularity, recency, frequency, etc. Requirements defined in attributes are necessary for servicing [FinOps capabilities][FODOFC] accurately using a standard set of instructions regardless of the origin of the data. diff --git a/specification/attributes/column_naming_and_ordering.md b/specification/attributes/column_naming_and_ordering.md index d21360e03..410c61894 100644 --- a/specification/attributes/column_naming_and_ordering.md +++ b/specification/attributes/column_naming_and_ordering.md @@ -14,7 +14,7 @@ Column Naming and Ordering ## Description -Naming and ordering convention for columns appearing in a FOCUS dataset. +Naming and ordering convention for columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Requirements diff --git a/specification/attributes/currency_code_format.md b/specification/attributes/currency_code_format.md index 68c5b2a68..a0f53f449 100644 --- a/specification/attributes/currency_code_format.md +++ b/specification/attributes/currency_code_format.md @@ -14,7 +14,7 @@ Currency Code Format ## Description -Formatting for currency columns appearing in a FOCUS dataset. +Formatting for currency columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Requirements diff --git a/specification/attributes/datetime_format.md b/specification/attributes/datetime_format.md index d04b6e032..b6b013df7 100644 --- a/specification/attributes/datetime_format.md +++ b/specification/attributes/datetime_format.md @@ -14,7 +14,7 @@ Date/Time Format ## Description -Rules and formatting requirements for date/time-related columns appearing in a FOCUS dataset. +Rules and formatting requirements for date/time-related columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Requirements diff --git a/specification/attributes/key_value_format.md b/specification/attributes/key_value_format.md index 136d81447..9ae056915 100644 --- a/specification/attributes/key_value_format.md +++ b/specification/attributes/key_value_format.md @@ -14,7 +14,7 @@ Key-Value Format ## Description -Rules and formatting requirements for columns appearing in a FOCUS dataset that convey data as key-value pairs. +Rules and formatting requirements for columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset) that convey data as key-value pairs. ## Requirements diff --git a/specification/attributes/numeric_format.md b/specification/attributes/numeric_format.md index 992a60c56..cf9980562 100644 --- a/specification/attributes/numeric_format.md +++ b/specification/attributes/numeric_format.md @@ -14,7 +14,7 @@ Numeric Format ## Description -Rules and formatting requirements for numeric columns appearing in a FOCUS dataset. +Rules and formatting requirements for numeric columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Requirements diff --git a/specification/attributes/string_handling.md b/specification/attributes/string_handling.md index 108fb8f08..7beb1e014 100644 --- a/specification/attributes/string_handling.md +++ b/specification/attributes/string_handling.md @@ -14,7 +14,7 @@ String Handling ## Description -Requirements for string-capturing columns appearing in a FOCUS dataset. +Requirements for string-capturing columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Requirements diff --git a/specification/attributes/unit_format.md b/specification/attributes/unit_format.md index 7fa10a32c..929dc9cbb 100644 --- a/specification/attributes/unit_format.md +++ b/specification/attributes/unit_format.md @@ -1,6 +1,6 @@ # Unit Format -Billing data frequently captures data measured in units related to data size, count, time, and other [*dimensions*](#glossary:dimension). The Unit Format attribute provides a standard for expressing units of measure in columns appearing in a FOCUS dataset. +Billing data frequently captures data measured in units related to data size, count, time, and other [*dimensions*](#glossary:dimension). The Unit Format attribute provides a standard for expressing units of measure in columns appearing in a [*FOCUS dataset*](#glossary:FOCUS-dataset). All columns defined in FOCUS specifying Unit Format as a value format MUST follow the requirements listed below. @@ -14,7 +14,7 @@ Unit Format ## Description -Indicates standards for expressing measurement units in columns appearing in a FOCUS dataset. +Indicates standards for expressing measurement units in columns appearing in a *FOCUS dataset*. ## Requirements diff --git a/specification/columns/billedcost.md b/specification/columns/billedcost.md index 5daaa0285..eb54c5ec3 100644 --- a/specification/columns/billedcost.md +++ b/specification/columns/billedcost.md @@ -2,7 +2,7 @@ The [*billed cost*](#glossary:billed-cost) represents a charge serving as the basis for invoicing, inclusive of the impacts of all reduced rates and discounts while excluding the [*amortization*](#glossary:amortization) of relevant purchases (one-time or recurring) paid to cover future eligible charges. This cost is denominated in the [Billing Currency](#billingcurrency). The Billed Cost is commonly used to perform FinOps capabilities that require cash-basis accounting such as cost allocation, budgeting, and invoice reconciliation. -The BilledCost column MUST be present in a FOCUS dataset and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [NumericFormat](#numericformat), and be denominated in the BillingCurrency. The sum of the BilledCost for [*rows*](#glossary:row) in a given [*billing period*](#glossary:billing-period) MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). +The BilledCost column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [Numeric Format](#numericformat), and be denominated in the BillingCurrency. The sum of the BilledCost for [*rows*](#glossary:row) in a given [*billing period*](#glossary:billing-period) MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). ## Column ID diff --git a/specification/columns/billingaccountid.md b/specification/columns/billingaccountid.md index e2b3a1a74..b66ccd0e0 100644 --- a/specification/columns/billingaccountid.md +++ b/specification/columns/billingaccountid.md @@ -2,7 +2,7 @@ A Billing Account ID is a provider-assigned identifier for a [*billing account*](#glossary:billing-account). *Billing accounts* are commonly used for scenarios like grouping based on organizational constructs, invoice reconciliation and cost allocation strategies. -The BillingAccountId column MUST be present in a FOCUS dataset. This column MUST be of type String and MUST NOT contain null values. BillingAccountId MUST be a globally unique identifier within a provider. +The BillingAccountId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST NOT contain null values. BillingAccountId MUST be a globally unique identifier within a provider. See [Appendix: Grouping constructs for resources or services](#groupingconstructsforresourcesorservices) for details and examples of the different grouping constructs supported by FOCUS. diff --git a/specification/columns/billingaccountname.md b/specification/columns/billingaccountname.md index b5ced23e6..cdfb8fe9b 100644 --- a/specification/columns/billingaccountname.md +++ b/specification/columns/billingaccountname.md @@ -2,7 +2,7 @@ A Billing Account Name is a display name assigned to a [*billing account*](#glossary:billing-account). *Billing accounts* are commonly used for scenarios like grouping based on organizational constructs, invoice reconciliation and cost allocation strategies. -The BillingAccountName column MUST be present in a FOCUS dataset and MUST NOT be null when the provider supports assigning a display name for the *billing account*. This column MUST be of type String. BillingAccountName MUST be unique within a customer when a customer has more than one *billing account*. +The BillingAccountName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null when the provider supports assigning a display name for the *billing account*. This column MUST be of type String. BillingAccountName MUST be unique within a customer when a customer has more than one *billing account*. See [Appendix: Grouping constructs for resources or services](#groupingconstructsforresourcesorservices) for details and examples of the different grouping constructs supported by FOCUS. diff --git a/specification/columns/billingcurrency.md b/specification/columns/billingcurrency.md index e60e127de..8dfd03818 100644 --- a/specification/columns/billingcurrency.md +++ b/specification/columns/billingcurrency.md @@ -2,7 +2,7 @@ [*Billing currency*](#glossary:billing-currency) is an identifier that represents the currency that a charge for [*resources*](#glossary:resource) or [*services*](#glossary:service) was billed in. Billing Currency is commonly used in scenarios where costs need to be grouped or aggregated. -The BillingCurrency column MUST be present in a FOCUS dataset. BillingCurrency MUST match the currency used in the invoice generated by the invoice issuer. This column MUST be of type String and MUST NOT contain null values. BillingCurrency MUST conform to [CurrencyCodeFormat](#currencycodeformat) requirements. +The BillingCurrency column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). BillingCurrency MUST match the currency used in the invoice generated by the invoice issuer. This column MUST be of type String and MUST NOT contain null values. BillingCurrency MUST conform to [Currency Code Format](#currencycodeformat) requirements. ## Column ID diff --git a/specification/columns/billingperiodend.md b/specification/columns/billingperiodend.md index fcd2cbaf2..f0303f384 100644 --- a/specification/columns/billingperiodend.md +++ b/specification/columns/billingperiodend.md @@ -2,7 +2,7 @@ Billing Period End represents the [*exclusive*](#glossary:exclusivebound) end date and time of a [*billing period*](#glossary:billing-period). For example, a time period where [BillingPeriodStart](#glossary:billingperiodstart) is '2024-01-01T00:00:00Z' and BillingPeriodEnd is '2024-02-01T00:00:00Z' includes charges for January, since BillingPeriodStart is [*inclusive*](#glossary:inclusivebound), but does not include charges for February since BillingPeriodEnd is *exclusive*. -The BillingPeriodEnd column MUST be present in a FOCUS dataset. This column MUST be of type [DateTimeFormat](#date/timeformat), MUST be an *exclusive* value, and MUST NOT contain null values. The sum of the [BilledCost](#billedcost) column for [*rows*](#glossary:row) in a given *billing period* MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). +The BillingPeriodEnd column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type [Date/Time Format](#date/timeformat), MUST be an *exclusive* value, and MUST NOT contain null values. The sum of the [BilledCost](#billedcost) column for [*rows*](#glossary:row) in a given *billing period* MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). ## Column ID diff --git a/specification/columns/billingperiodstart.md b/specification/columns/billingperiodstart.md index 54b198c31..9289a10ea 100644 --- a/specification/columns/billingperiodstart.md +++ b/specification/columns/billingperiodstart.md @@ -2,7 +2,7 @@ Billing Period Start represents the [*inclusive*](#glossary:inclusivebound) start date and time of a [*billing period*](#glossary:billing-period). For example, a time period where BillingPeriodStart is '2024-01-01T00:00:00Z' and [BillingPeriodEnd](#billingperiodend) is '2024-02-01T00:00:00Z' includes charges for January, since BillingPeriodStart is inclusive, but does not include charges for February since BillingPeriodEnd is [*exclusive*](#glossary:exclusivebound). -The BillingPeriodStart column MUST be present in a FOCUS dataset, MUST be of type [DateTimeFormat](#date/timeformat), MUST be an *inclusive* value, and MUST NOT contain null values. The sum of the [BilledCost](#billedcost) metric for [*rows*](#glossary:row) in a given *billing period* MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). +The BillingPeriodStart column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset), MUST be of type [Date/Time Format](#date/timeformat), MUST be an *inclusive* value, and MUST NOT contain null values. The sum of the [BilledCost](#billedcost) metric for [*rows*](#glossary:row) in a given *billing period* MUST match the sum of the invoices received for that *billing period* for a [*billing account*](#glossary:billing-account). ## Column ID diff --git a/specification/columns/capacityreservationid.md b/specification/columns/capacityreservationid.md index ddc836936..bd87afd80 100644 --- a/specification/columns/capacityreservationid.md +++ b/specification/columns/capacityreservationid.md @@ -4,7 +4,7 @@ A Capacity Reservation ID is the identifier assigned to a [*capacity reservation The CapacityReservationId column adheres to the following requirements: -* CapacityReservationId MUST be present in the billing data when the provider supports *capacity reservations* and MUST be of type String. +* CapacityReservationId MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *capacity reservations* and MUST be of type String. * CapacityReservationId SHOULD NOT be null when a charge is related to a capacity reservation. * CapacityReservationId MUST NOT be null when a charge represents the unused portion of a *capacity reservation*. * CapacityReservationId MUST be null when a charge is not related to a *capacity reservation*. diff --git a/specification/columns/capacityreservationstatus.md b/specification/columns/capacityreservationstatus.md index 24b449c29..afc139b2e 100644 --- a/specification/columns/capacityreservationstatus.md +++ b/specification/columns/capacityreservationstatus.md @@ -4,7 +4,7 @@ Capacity Reservation Status indicates whether the charge represents either the c The CapacityReservationStatus column adheres to the following requirements: -* CapacityReservationStatus MUST be present in a FOCUS dataset when the provider supports *capacity reservations* and MUST be of type String. +* CapacityReservationStatus MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *capacity reservations* and MUST be of type String. * CapacityReservationStatus MUST be null when CapacityReservationId is null. * CapacityReservationStatus MUST NOT be null when CapacityReservationId is not null and [ChargeCategory](#chargecategory) is "Usage". * CapacityReservationStatus MUST be one of the allowed values. diff --git a/specification/columns/chargecategory.md b/specification/columns/chargecategory.md index 41f183c26..e3e672ad9 100644 --- a/specification/columns/chargecategory.md +++ b/specification/columns/chargecategory.md @@ -2,7 +2,7 @@ Charge Category represents the highest-level classification of a charge based on the nature of how it is billed. Charge Category is commonly used to identify and distinguish between types of charges that may require different handling. -The ChargeCategory column MUST be present in a FOCUS dataset and MUST NOT be null. This column is of type String and MUST be one of the allowed values. +The ChargeCategory column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column is of type String and MUST be one of the allowed values. ## Column ID diff --git a/specification/columns/chargeclass.md b/specification/columns/chargeclass.md index 41866810e..85569d6aa 100644 --- a/specification/columns/chargeclass.md +++ b/specification/columns/chargeclass.md @@ -2,7 +2,7 @@ Charge Class indicates whether the row represents a correction to a previously invoiced [*billing period*](#glossary:billing-period). Charge Class is commonly used to differentiate corrections from regularly incurred charges. -The ChargeClass column MUST be present in the FOCUS dataset. This column MUST be of type String and MUST be "Correction" when the row represents a correction to a previously invoiced *billing period*. ChargeClass MUST be null when it is not a correction or when it is a correction within the current *billing period*. +The ChargeClass column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST be "Correction" when the row represents a correction to a previously invoiced *billing period*. ChargeClass MUST be null when it is not a correction or when it is a correction within the current *billing period*. ## Column ID diff --git a/specification/columns/chargedescription.md b/specification/columns/chargedescription.md index 0f875c6e4..e0b280f2e 100644 --- a/specification/columns/chargedescription.md +++ b/specification/columns/chargedescription.md @@ -2,7 +2,7 @@ A Charge Description provides a high-level context of a [*row*](#glossary:row) without requiring additional discovery. This column is a self-contained summary of the charge's purpose and price. It typically covers a select group of corresponding details across a billing dataset or provides information not otherwise available. -The ChargeDescription column MUST be present in a FOCUS dataset, MUST be of type String, and SHOULD NOT be null. Providers SHOULD specify the length of this column in their publicly available documentation. +The ChargeDescription column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset), MUST be of type String, and SHOULD NOT be null. Providers SHOULD specify the length of this column in their publicly available documentation. ## Column ID diff --git a/specification/columns/chargefrequency.md b/specification/columns/chargefrequency.md index 45d94183c..3f5c1d825 100644 --- a/specification/columns/chargefrequency.md +++ b/specification/columns/chargefrequency.md @@ -2,7 +2,7 @@ Charge Frequency indicates how often a charge will occur. Along with the [charge period](#glossary:chargeperiod) related columns, the Charge Frequency is commonly used to understand recurrence periods (e.g., monthly, yearly), forecast upcoming charges, and differentiate between one-time and recurring fees for purchases. -The ChargeFrequency column is RECOMMENDED be present in a FOCUS dataset and MUST NOT be null. This column is of type String and MUST be one of the allowed values. When [ChargeCategory](#chargecategory) is "Purchase", ChargeFrequency MUST NOT be "Usage-Based". +The ChargeFrequency column is RECOMMENDED be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column is of type String and MUST be one of the allowed values. When [ChargeCategory](#chargecategory) is "Purchase", ChargeFrequency MUST NOT be "Usage-Based". ## Column ID diff --git a/specification/columns/chargeperiodend.md b/specification/columns/chargeperiodend.md index c7e5060e8..d0eccd134 100644 --- a/specification/columns/chargeperiodend.md +++ b/specification/columns/chargeperiodend.md @@ -2,7 +2,7 @@ Charge Period End represents the [*exclusive*](#glossary:exclusivebound) end date and time of a [*charge period*](#glossary:chargeperiod). For example, a time period where [ChargePeriodStart](#chargeperiodstart) is '2024-01-01T00:00:00Z' and ChargePeriodEnd is '2024-01-02T00:00:00Z' includes charges for January 1, since ChargePeriodStart is [*inclusive*](#glossary:inclusivebound), but does not include charges for January 2 since ChargePeriodEnd is *exclusive*. -ChargePeriodEnd MUST be present in a FOCUS dataset, MUST be of type Date/Time, MUST be an *exclusive* value, and MUST NOT contain null values. ChargePeriodEnd MUST match the ending date and time boundary of the effective period of the charge. +ChargePeriodEnd MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset), MUST be of type Date/Time, MUST be an *exclusive* value, and MUST NOT contain null values. ChargePeriodEnd MUST match the ending date and time boundary of the effective period of the charge. ## Column ID diff --git a/specification/columns/chargeperiodstart.md b/specification/columns/chargeperiodstart.md index fe701b161..2d4d4700a 100644 --- a/specification/columns/chargeperiodstart.md +++ b/specification/columns/chargeperiodstart.md @@ -2,7 +2,7 @@ Charge Period Start represents the [*inclusive*](#glossary:inclusivebound) start date and time within a [*charge period*](#glossary:chargeperiod). For example, a time period where ChargePeriodStart is '2024-01-01T00:00:00Z' and [ChargePeriodEnd](#chargeperiodend) is '2024-01-02T00:00:00Z' includes charges for January 1, since ChargePeriodStart is *inclusive*, but does not include charges for January 2 since ChargePeriodEnd is [*exclusive*](#glossary:exclusivebound). -ChargePeriodStart MUST be present in a FOCUS dataset, MUST be of type Date/Time, MUST be an *inclusive* value, and MUST NOT contain null values. ChargePeriodStart MUST match the beginning date and time boundary of the effective period of the charge. +ChargePeriodStart MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset), MUST be of type Date/Time, MUST be an *inclusive* value, and MUST NOT contain null values. ChargePeriodStart MUST match the beginning date and time boundary of the effective period of the charge. ## Column ID diff --git a/specification/columns/commitmentdiscountcategory.md b/specification/columns/commitmentdiscountcategory.md index 357642cfc..44c111b02 100644 --- a/specification/columns/commitmentdiscountcategory.md +++ b/specification/columns/commitmentdiscountcategory.md @@ -2,7 +2,7 @@ Commitment Discount Category indicates whether the [*commitment discount*](#glossary:commitment-discount) identified in the CommitmentDiscountId column is based on usage quantity or cost (aka "spend"). The CommitmentDiscountCategory column is only applicable to *commitment discounts* and not [*negotiated discounts*](#glossary:negotiated-discount). -The CommitmentDiscountCategory column MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null. The CommitmentDiscountCategory MUST be one of the allowed values. +The CommitmentDiscountCategory column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null. The CommitmentDiscountCategory MUST be one of the allowed values. ## Column ID diff --git a/specification/columns/commitmentdiscountid.md b/specification/columns/commitmentdiscountid.md index 94eb9d435..958b13744 100644 --- a/specification/columns/commitmentdiscountid.md +++ b/specification/columns/commitmentdiscountid.md @@ -2,7 +2,7 @@ A Commitment Discount ID is the identifier assigned to a [*commitment discount*](#glossary:commitment-discount) by the provider. Commitment Discount ID is commonly used for scenarios like chargeback for *commitments* and savings per *commitment discount*. The CommitmentDiscountId column is only applicable to *commitment discounts* and not [*negotiated discounts*](#glossary:negotiated-discount). -The CommitmentDiscountId column MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. This column MUST be of type String and MUST NOT contain null values when a charge is related to a *commitment discount*. When a charge is not associated with a *commitment discount*, the column MUST be null. CommitmentDiscountId MUST ensure global uniqueness within the provider and SHOULD be a fully-qualified identifier. +The CommitmentDiscountId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. This column MUST be of type String and MUST NOT contain null values when a charge is related to a *commitment discount*. When a charge is not associated with a *commitment discount*, the column MUST be null. CommitmentDiscountId MUST ensure global uniqueness within the provider and SHOULD be a fully-qualified identifier. ## Column ID diff --git a/specification/columns/commitmentdiscountname.md b/specification/columns/commitmentdiscountname.md index 66c8b1a84..72d2907ec 100644 --- a/specification/columns/commitmentdiscountname.md +++ b/specification/columns/commitmentdiscountname.md @@ -2,7 +2,7 @@ A Commitment Discount Name is the display name assigned to a [*commitment discount*](#glossary:commitment-discount). The CommitmentDiscountName column is only applicable to *commitment discounts* and not [*negotiated discounts*](#glossary:negotiated-discount). -The CommitmentDiscountName column MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. This column MUST be of type String. The CommitmentDiscountName value MUST be null if the charge is not related to a *commitment discount* and MAY be null if a display name cannot be assigned to a *commitment discount*. CommitmentDiscountName MUST NOT be null if a display name can be assigned to a *commitment discount*. +The CommitmentDiscountName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. This column MUST be of type String. The CommitmentDiscountName value MUST be null if the charge is not related to a *commitment discount* and MAY be null if a display name cannot be assigned to a *commitment discount*. CommitmentDiscountName MUST NOT be null if a display name can be assigned to a *commitment discount*. ## Column ID diff --git a/specification/columns/commitmentdiscountquantity.md b/specification/columns/commitmentdiscountquantity.md index 464bc2dfe..650e2f50d 100644 --- a/specification/columns/commitmentdiscountquantity.md +++ b/specification/columns/commitmentdiscountquantity.md @@ -6,9 +6,9 @@ When [CommitmentDiscountCategory](#commitmentdiscountcategory) is "Usage" (usage The CommitmentDiscountQuantity column adheres to the following requirements: -* CommitmentDiscountQuantity MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. -* CommitmentDiscountQuantity MUST be of type Decimal and MUST conform to [NumericFormat](#numericformat) requirements. -* CommitmentDiscountQuantity MAY be null or any valid decimal value if [CommitmentDiscountId](#commitmentdiscountid) is not null and [ChargeClass](#chargeclass) is "Correction". +* CommitmentDiscountQuantity MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. +* CommitmentDiscountQuantity MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements. +* CommitmentDiscountQuantity MAY be null or any valid decimal value if [*CommitmentDiscountId*](#commitmentdiscountid) is not null and [*ChargeClass*](#chargeclass) is "Correction". In cases where the ChargeCategory is "Purchase", CommitmentDiscountId is not null, and ChargeClass is not "Correction", the following applies: diff --git a/specification/columns/commitmentdiscountstatus.md b/specification/columns/commitmentdiscountstatus.md index edc382186..2c5facecb 100644 --- a/specification/columns/commitmentdiscountstatus.md +++ b/specification/columns/commitmentdiscountstatus.md @@ -2,7 +2,7 @@ Commitment Discount Status indicates whether the charge corresponds with the consumption of a [*commitment discount*](#glossary:commitment-discount) identified in the CommitmentDiscountId column or the unused portion of the committed amount. The CommitmetnDiscountStatus column is only applicable to *commitment discounts* and not [*negotiated discounts*](#glossary:negotiated-discount). -The CommitmentDiscountStatus column MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null and [Charge Category](#chargecategory) is "Usage". CommitmentDiscountStatus MUST be one of the allowed values. +The CommitmentDiscountStatus column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null and [Charge Category](#chargecategory) is "Usage". CommitmentDiscountStatus MUST be one of the allowed values. ## Column ID diff --git a/specification/columns/commitmentdiscounttype.md b/specification/columns/commitmentdiscounttype.md index 23cae2212..a88f1cf96 100644 --- a/specification/columns/commitmentdiscounttype.md +++ b/specification/columns/commitmentdiscounttype.md @@ -2,7 +2,7 @@ Commitment Discount Type is a provider-assigned name to identify the type of [*commitment discount*](#glossary:commitment-discount) applied to the [*row*](#glossary:row). The CommitmentDiscountType column is only applicable to *commitment discounts* and not [*negotiated discounts*](#glossary:negotiated-discount). -The CommitmentDiscountType column MUST be present in a FOCUS dataset when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null. +The CommitmentDiscountType column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports *commitment discounts*. This column MUST be of type String, MUST be null when [CommitmentDiscountId](#commitmentdiscountid) is null, and MUST NOT be null when CommitmentDiscountId is not null. ## Column ID diff --git a/specification/columns/commitmentdiscountunit.md b/specification/columns/commitmentdiscountunit.md index e64a03a5c..596f4df77 100644 --- a/specification/columns/commitmentdiscountunit.md +++ b/specification/columns/commitmentdiscountunit.md @@ -4,7 +4,7 @@ Commitment Discount Unit represents the provider-specified measurement unit indi The CommitmentDiscountUnit column adheres to the following requirements: -* CommitmentDiscountUnit MUST be present in a FOCUS dataset when the provider supports [*commitment discounts*](#glossary:commitment-discount). +* CommitmentDiscountUnit MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports [*commitment discounts*](#glossary:commitment-discount). * CommitmentDiscountUnit MUST be of type String, and the units of measure used in CommitmentDiscountUnit SHOULD adhere to the values and format requirements specified in the [UnitFormat](#unitformat) attribute. * The CommitmentDiscountUnit MUST be the same across all *rows* where CommitmentDiscountQuantity has the same [CommitmentDiscountId](#commitmentdiscountid). * CommitmentDiscountUnit MAY be null if CommitmentDiscountId is not null and [ChargeClass](#chargeclass) is "Correction". diff --git a/specification/columns/consumedquantity.md b/specification/columns/consumedquantity.md index c4ffb19a3..234f63b7e 100644 --- a/specification/columns/consumedquantity.md +++ b/specification/columns/consumedquantity.md @@ -4,8 +4,8 @@ The Consumed Quantity represents the volume of a metered SKU associated with a [ The ConsumedQuantity column adheres to the following requirements: -* ConsumedQuantity MUST be present in a FOCUS dataset when the provider supports the measurement of usage. -* ConsumedQuantity MUST be of type Decimal and MUST conform to [NumericFormat](#numericformat) requirements. +* ConsumedQuantity MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports the measurement of usage. +* ConsumedQuantity MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements. * ConsumedQuantity MUST NOT be null and MUST be a valid positive decimal value if [ChargeCategory](#chargecategory) is "Usage", [CommitmentDiscountStatus](#commitmentdiscountstatus) is not "Unused", and [ChargeClass](#chargeclass) is not "Correction". * ConsumedQuantity MAY be null or any valid decimal value if ChargeCategory is "Usage", CommitmentDiscountStatus is not "Unused", and ChargeClass is "Correction". * ConsumedQuantity MUST be null in all other cases. diff --git a/specification/columns/consumedunit.md b/specification/columns/consumedunit.md index 36d2760f6..a9f7b78bc 100644 --- a/specification/columns/consumedunit.md +++ b/specification/columns/consumedunit.md @@ -4,7 +4,7 @@ The Consumed Unit represents a provider-specified measurement unit indicating ho The ConsumedUnit column adheres to the following requirements: -* ConsumedUnit MUST be present in the billing data when the provider supports the measurement of usage. +* ConsumedUnit MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports the measurement of usage. * ConsumedUnit MUST be of type String, and the units of measure used in ConsumedUnit SHOULD adhere to the values and format requirements specified in the [UnitFormat](#unitformat) attribute. * ConsumedUnit MUST NOT be null if [ChargeCategory](#chargecategory) is "Usage", [CommitmentDiscountStatus](#commitmentdiscountstatus) is not "Unused", and [ChargeClass](#chargeclass) is not "Correction". * ConsumedUnit MAY be null if ChargeCategory is "Usage", CommitmentDiscountStatus is not "Unused", and ChargeClass is "Correction". diff --git a/specification/columns/contractedcost.md b/specification/columns/contractedcost.md index 8dda88594..96a678312 100644 --- a/specification/columns/contractedcost.md +++ b/specification/columns/contractedcost.md @@ -2,7 +2,7 @@ Contracted Cost represents the cost calculated by multiplying [*contracted unit price*](#glossary:contracted-unit-price) and the corresponding [Pricing Quantity](#pricingquantity). Contracted Cost is denominated in the [Billing Currency](#billingcurrency) and is commonly used for calculating savings based on negotiation activities, by comparing it with [List Cost](#listcost). If [*negotiated discounts*](#glossary:negotiated-discount) are not applicable, the Contracted Cost defaults to the List Cost. -The ContractedCost column MUST be present in a FOCUS dataset and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [NumericFormat](#numericformat) requirements, and be denominated in the BillingCurrency. When [ContractedUnitPrice](#contractedunitprice) is present and not null, multiplying the ContractedUnitPrice by PricingQuantity MUST produce the ContractedCost, except in cases of [ChargeClass](#chargeclass) "Correction", which may address PricingQuantity or any cost discrepancies independently. +The ContractedCost column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [Numeric Format](#numericformat) requirements, and be denominated in the BillingCurrency. When [ContractedUnitPrice](#contractedunitprice) is present and not null, multiplying the ContractedUnitPrice by PricingQuantity MUST produce the ContractedCost, except in cases of [ChargeClass](#chargeclass) "Correction", which may address PricingQuantity or any cost discrepancies independently. In cases where the ContractedUnitPrice is present and null, the following applies: diff --git a/specification/columns/contractedunitprice.md b/specification/columns/contractedunitprice.md index 796f84842..36d21392b 100644 --- a/specification/columns/contractedunitprice.md +++ b/specification/columns/contractedunitprice.md @@ -2,7 +2,7 @@ The Contracted Unit Price represents the agreed-upon unit price for a single [Pricing Unit](#pricingunit) of the associated SKU, inclusive of [*negotiated discounts*](#glossary:negotiated-discount), if present, while excluding negotiated [*commitment discounts*](#glossary:commitment-discount) or any other discounts. This price is denominated in the [Billing Currency](#billingcurrency). The Contracted Unit Price is commonly used for calculating savings based on negotiation activities. If negotiated discounts are not applicable, the Contracted Unit Price defaults to the [List Unit Price](#listunitprice). -The ContractedUnitPrice column MUST be present in a FOCUS dataset when the provider supports negotiated pricing concepts. This column MUST be a Decimal within the range of non-negative decimal values, MUST conform to [NumericFormat](#numericformat) requirements, and be denominated in the BillingCurrency. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When ContractedUnitPrice is present and not null, multiplying ContractedUnitPrice by [PricingQuantity](#pricingquantity) MUST equal [ContractedCost](#contractedcost), except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. +The ContractedUnitPrice column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports negotiated pricing concepts. This column MUST be a Decimal within the range of non-negative decimal values, MUST conform to [Numeric Format](#numericformat) requirements, and be denominated in the BillingCurrency. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When ContractedUnitPrice is present and not null, multiplying ContractedUnitPrice by [PricingQuantity](#pricingquantity) MUST equal [ContractedCost](#contractedcost), except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. ## Column ID diff --git a/specification/columns/effectivecost.md b/specification/columns/effectivecost.md index d9758c1f6..f54dec19d 100644 --- a/specification/columns/effectivecost.md +++ b/specification/columns/effectivecost.md @@ -7,7 +7,7 @@ This column resolves two challenges that are faced by practitioners: 1. Practitioners need to *amortize* relevant purchases, such as upfront fees, throughout the *commitment* and distribute them to the appropriate reporting groups (e.g. [*tags*](#glossary:tag), [*resources*](#glossary:resource)). 2. Many [*commitment discount*](#glossary:commitment-discount) constructs include a recurring expense for the *commitment* for every [*billing period*](#glossary:billing-period) and must distribute this cost to the *resources* using the *commitment*. This forces reconciliation between the initial *commitment* [*row*](#glossary:row) per period and the actual usage *rows*. -The EffectiveCost column MUST be present in a FOCUS dataset and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [NumericFormat](#numericformat) requirements, and be denominated in the BillingCurrency. EffectiveCost MUST be 0 when ChargeCategory is "Purchase" and the purchase is intended to cover future eligible charges. The aggregated EffectiveCost for a billing period may not match the charge received on the invoice for the same *billing period*. +The EffectiveCost column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [Numeric Format](#numericformat) requirements, and be denominated in the BillingCurrency. EffectiveCost MUST be 0 when ChargeCategory is "Purchase" and the purchase is intended to cover future eligible charges. The aggregated EffectiveCost for a billing period may not match the charge received on the invoice for the same *billing period*. In cases where the [ChargeCategory](#chargecategory) is not "Usage" or "Purchase", the following applies: diff --git a/specification/columns/invoiceissuer.md b/specification/columns/invoiceissuer.md index 7a1b76edf..dfe03ed11 100644 --- a/specification/columns/invoiceissuer.md +++ b/specification/columns/invoiceissuer.md @@ -3,7 +3,7 @@ An Invoice Issuer is an entity responsible for invoicing for the [*resources*](#glossary:resource) or [*services*](#glossary:service) consumed. It is commonly used for cost analysis and reporting scenarios. -The InvoiceIssuer column MUST be present in a FOCUS dataset. This column MUST be of type String and MUST NOT contain null values. +The InvoiceIssuer column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST NOT contain null values. See [Appendix: Origination of cost data](#originationofcostdata) section for examples of [Provider](#provider), [Publisher](#publisher) and Invoice Issuer values that can be used for various purchasing scenarios. diff --git a/specification/columns/listcost.md b/specification/columns/listcost.md index ce644df93..c2e6d3dd9 100644 --- a/specification/columns/listcost.md +++ b/specification/columns/listcost.md @@ -2,7 +2,7 @@ List Cost represents the cost calculated by multiplying the [*list unit price*](#glossary:list-unit-price) and the corresponding [Pricing Quantity](#pricingquantity). List Cost is denominated in the [Billing Currency](#billingcurrency) and is commonly used for calculating savings based on various rate optimization activities, by comparing it with [Contracted Cost](#contractedcost), [Billed Cost](#billedcost) and [Effective Cost](#effectivecost). -The ListCost column MUST be present in a FOCUS dataset and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [NumericFormat](#numericformat) requirements, and be denominated in the BillingCurrency. When [ListUnitPrice](#listunitprice) is present and not null, multiplying the ListUnitPrice by PricingQuantity MUST produce the ListCost, except in cases of [ChargeClass](#chargeclass) "Correction", which may address PricingQuantity or any cost discrepancies independently. +The ListCost column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column MUST be of type Decimal, MUST conform to [Numeric Format](#numericformat) requirements, and be denominated in the BillingCurrency. When [ListUnitPrice](#listunitprice) is present and not null, multiplying the ListUnitPrice by PricingQuantity MUST produce the ListCost, except in cases of [ChargeClass](#chargeclass) "Correction", which may address PricingQuantity or any cost discrepancies independently. In cases where the ListUnitPrice is present and is null, the following applies: diff --git a/specification/columns/listunitprice.md b/specification/columns/listunitprice.md index 86ffd1d78..d35d73b32 100644 --- a/specification/columns/listunitprice.md +++ b/specification/columns/listunitprice.md @@ -2,7 +2,7 @@ The List Unit Price represents the suggested provider-published unit price for a single [Pricing Unit](#pricingunit) of the associated SKU, exclusive of any discounts. This price is denominated in the [Billing Currency](#billingcurrency). The List Unit Price is commonly used for calculating savings based on various rate optimization activities. -The ListUnitPrice column MUST be present in a FOCUS dataset when the provider publishes unit prices exclusive of discounts. This column MUST be a Decimal within the range of non-negative decimal values, MUST conform to [NumericFormat](#numericformat) requirements, and be denominated in the BillingCurrency. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When ListUnitPrice is present and is not null, multiplying ListUnitPrice by [PricingQuantity](#pricingquantity) MUST equal [ListCost](#listcost), except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. +The ListUnitPrice column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider publishes unit prices exclusive of discounts. This column MUST be a Decimal within the range of non-negative decimal values, MUST conform to [Numeric Format](#numericformat) requirements, and be denominated in the BillingCurrency. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When ListUnitPrice is present and is not null, multiplying ListUnitPrice by [PricingQuantity](#pricingquantity) MUST equal [ListCost](#listcost), except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. ## Column ID diff --git a/specification/columns/pricingcategory.md b/specification/columns/pricingcategory.md index ae0369498..504c807e9 100644 --- a/specification/columns/pricingcategory.md +++ b/specification/columns/pricingcategory.md @@ -4,7 +4,7 @@ Pricing Category describes the pricing model used for a charge at the time of us The PricingCategory column adheres to the following requirements: -* PricingCategory MUST be present in a FOCUS dataset when the provider supports more than one pricing category across all SKUs and MUST be of type String. +* PricingCategory MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports more than one pricing category across all SKUs and MUST be of type String. * PricingCategory MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. * PricingCategory MUST be one of the allowed values. * PricingCategory MUST be "Standard" when pricing is predetermined at the agreed upon rate for the [billing account](#glossary:billing-account). diff --git a/specification/columns/pricingquantity.md b/specification/columns/pricingquantity.md index 940a1d5be..2a10fb652 100644 --- a/specification/columns/pricingquantity.md +++ b/specification/columns/pricingquantity.md @@ -2,7 +2,7 @@ The Pricing Quantity represents the volume of a given SKU associated with a [*resource*](#glossary:resource) or [*service*](#glossary:service) used or purchased, based on the [Pricing Unit](#pricingunit). Distinct from [Consumed Quantity](#consumedquantity) (complementary to [Consumed Unit](#consumedunit)), it focuses on pricing and cost, not *resource* and *service* consumption. -The PricingQuantity column MUST be present in a FOCUS dataset. This column MUST be of type Decimal and MUST conform to [NumericFormat](#numericformat) requirements. The value MAY be negative in cases where [ChargeClass](#chargeclass) is "Correction". This column MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When unit prices are not null, multiplying PricingQuantity by a unit price MUST produce a result equal to the corresponding cost metric, except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. +The PricingQuantity column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type Decimal and MUST conform to [Numeric Format](#numericformat) requirements. The value MAY be negative in cases where [ChargeClass](#chargeclass) is "Correction". This column MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. When unit prices are not null, multiplying PricingQuantity by a unit price MUST produce a result equal to the corresponding cost metric, except in cases of ChargeClass "Correction", which may address PricingQuantity or any cost discrepancies independently. ## Column ID diff --git a/specification/columns/provider.md b/specification/columns/provider.md index e17f43e90..a88b07b69 100644 --- a/specification/columns/provider.md +++ b/specification/columns/provider.md @@ -2,7 +2,7 @@ A Provider is an entity that makes the [*resources*](#glossary:resource) or [*services*](#glossary:service) available for purchase. It is commonly used for cost analysis and reporting scenarios. -The Provider column MUST be present in a FOCUS dataset. This column MUST be of type String and MUST NOT contain null values. +The Provider column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST NOT contain null values. See [Appendix: Origination of cost data](#originationofcostdata) section for examples of Provider, Publisher and Invoice Issuer values that can be used for various purchasing scenarios. diff --git a/specification/columns/publisher.md b/specification/columns/publisher.md index a9f5fd16c..14a407167 100644 --- a/specification/columns/publisher.md +++ b/specification/columns/publisher.md @@ -2,7 +2,7 @@ A Publisher is an entity that produces the [*resources*](#glossary:resource) or [*services*](#glossary:service) that were purchased. It is commonly used for cost analysis and reporting scenarios. -The Publisher column MUST be present in a FOCUS dataset. This column MUST be of type String and MUST NOT contain null values. +The Publisher column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST NOT contain null values. See [Appendix: Origination of cost data](#originationofcostdata) section for examples of [Provider](#provider), Publisher and [Invoice Issuer](#invoiceissuer) values that can be used for various purchasing scenarios. diff --git a/specification/columns/regionid.md b/specification/columns/regionid.md index 873d036df..b1cada0e4 100644 --- a/specification/columns/regionid.md +++ b/specification/columns/regionid.md @@ -2,7 +2,7 @@ A Region ID is a provider-assigned identifier for an isolated geographic area where a [*resource*](#glossary:resource) is provisioned or a [*service*](#glossary:service) is provided. The region is commonly used for scenarios like analyzing cost and unit prices based on where *resources* are deployed. -The RegionId column MUST be present in a FOCUS dataset when the provider supports deploying resources or services within a *region* and MUST be of type String. RegionId MUST NOT be null when a *resource* or *service* is operated in or managed from a distinct region by the Provider and MAY contain null values when a *resource* or *service* is not restricted to an isolated geographic area. +The RegionId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports deploying resources or services within a *region* and MUST be of type String. RegionId MUST NOT be null when a *resource* or *service* is operated in or managed from a distinct region by the Provider and MAY contain null values when a *resource* or *service* is not restricted to an isolated geographic area. ## Column ID diff --git a/specification/columns/regionname.md b/specification/columns/regionname.md index 934ca0b91..ee3092e51 100644 --- a/specification/columns/regionname.md +++ b/specification/columns/regionname.md @@ -2,7 +2,7 @@ Region Name is a provider-assigned display name for an isolated geographic area where a [*resource*](#glossary:resource) is provisioned or a [*service*](#glossary:service) is provided. Region Name is commonly used for scenarios like analyzing cost and unit prices based on where *resources* are deployed. -The RegionName column MUST be present in a FOCUS dataset when the provider supports deploying resources or services within a *region* and MUST be of type String. RegionName MUST NOT be null when a *resource* or *service* is operated in or managed from a distinct region by the Provider and MAY contain null values when a *resource* or *service* is not restricted to an isolated geographic area. +The RegionName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports deploying resources or services within a *region* and MUST be of type String. RegionName MUST NOT be null when a *resource* or *service* is operated in or managed from a distinct region by the Provider and MAY contain null values when a *resource* or *service* is not restricted to an isolated geographic area. ## Column ID diff --git a/specification/columns/resourceid.md b/specification/columns/resourceid.md index e48d24d08..f494aa480 100644 --- a/specification/columns/resourceid.md +++ b/specification/columns/resourceid.md @@ -2,7 +2,7 @@ A Resource ID is an identifier assigned to a [*resource*](#glossary:resource) by the provider. The Resource ID is commonly used for cost reporting, analysis, and allocation scenarios. -The ResourceId column MUST be present in a FOCUS dataset when the provider supports billing based on provisioned resources. This column MUST be of type String. The ResourceId value MAY be a nullable column as some cost data [*rows*](#glossary:row) may not be associated with a *resource*. ResourceId MUST appear in the cost data if an identifier is assigned to a *resource* by the provider. ResourceId SHOULD be a fully-qualified identifier that ensures global uniqueness within the provider. +The ResourceId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports billing based on provisioned resources. This column MUST be of type String. The ResourceId value MAY be a nullable column as some cost data [*rows*](#glossary:row) may not be associated with a *resource*. ResourceId MUST appear in the cost data if an identifier is assigned to a *resource* by the provider. ResourceId SHOULD be a fully-qualified identifier that ensures global uniqueness within the provider. ## Column ID diff --git a/specification/columns/resourcename.md b/specification/columns/resourcename.md index 524311b0c..71fa7a938 100644 --- a/specification/columns/resourcename.md +++ b/specification/columns/resourcename.md @@ -2,7 +2,7 @@ The Resource Name is a display name assigned to a [*resource*](#glossary:resource). It is commonly used for cost analysis, reporting, and allocation scenarios. -The ResourceName column MUST be present in a FOCUS dataset when the provider supports billing based on provisioned resources. This column MUST be of type String. The ResourceName value MAY be a nullable column as some cost data [*rows*](#glossary:row) may not be associated with a *resource* or because a display name cannot be assigned to a *resource*. ResourceName MUST NOT be null if a display name can be assigned to a *resource*. *Resources* not provisioned interactively or only have a system-generated [ResourceId](#resourceid) MUST NOT duplicate the same value as the ResourceName. +The ResourceName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports billing based on provisioned resources. This column MUST be of type String. The ResourceName value MAY be a nullable column as some cost data [*rows*](#glossary:row) may not be associated with a *resource* or because a display name cannot be assigned to a *resource*. ResourceName MUST NOT be null if a display name can be assigned to a *resource*. *Resources* not provisioned interactively or only have a system-generated [ResourceId](#resourceid) MUST NOT duplicate the same value as the ResourceName. ## Column ID diff --git a/specification/columns/resourcetype.md b/specification/columns/resourcetype.md index 96480f78a..d05622c87 100644 --- a/specification/columns/resourcetype.md +++ b/specification/columns/resourcetype.md @@ -2,7 +2,7 @@ Resource Type describes the kind of [*resource*](#glossary:resource) the charge applies to. A Resource Type is commonly used for scenarios like identifying cost changes in groups of similar *resources* and may include values like Virtual Machine, Data Warehouse, and Load Balancer. -The ResourceType column MUST be present in a FOCUS dataset when the provider supports billing based on provisioned resources and supports assigning a type for resources. This column MUST be of type String and MUST NOT be null when a corresponding [ResourceId](#resourceid) is not null. When a corresponding ResourceId value is null, the ResourceType column value MUST also be null. +The ResourceType column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports billing based on provisioned resources and supports assigning a type for resources. This column MUST be of type String and MUST NOT be null when a corresponding [ResourceId](#resourceid) is not null. When a corresponding ResourceId value is null, the ResourceType column value MUST also be null. ## Column ID diff --git a/specification/columns/servicecategory.md b/specification/columns/servicecategory.md index c8d474fbb..77a83c41e 100644 --- a/specification/columns/servicecategory.md +++ b/specification/columns/servicecategory.md @@ -2,7 +2,7 @@ The Service Category is the highest-level classification of a [*service*](#glossary:service) based on the core function of the *service*. Each *service* should have one and only one category that best aligns with its primary purpose. The Service Category is commonly used for scenarios like analyzing costs across providers and tracking the migration of workloads across fundamentally different architectures. -The ServiceCategory column MUST be present in a FOCUS dataset and MUST NOT be null. This column is of type String and MUST be one of the allowed values. +The ServiceCategory column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. This column is of type String and MUST be one of the allowed values. ## Column ID diff --git a/specification/columns/servicename.md b/specification/columns/servicename.md index db1fc0cda..a5086cba1 100644 --- a/specification/columns/servicename.md +++ b/specification/columns/servicename.md @@ -4,7 +4,7 @@ A [*service*](#glossary:service) represents an offering that can be purchased fr The Service Name is a display name for the offering that was purchased. The Service Name is commonly used for scenarios like analyzing aggregate cost trends over time and filtering data to investigate anomalies. -The ServiceName column MUST be present in a FOCUS dataset. This column MUST be of type String and MUST NOT contain null values. +The ServiceName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset). This column MUST be of type String and MUST NOT contain null values. ## Column ID diff --git a/specification/columns/servicesubcategory.md b/specification/columns/servicesubcategory.md index f235967fb..8452e588b 100644 --- a/specification/columns/servicesubcategory.md +++ b/specification/columns/servicesubcategory.md @@ -4,7 +4,7 @@ The Service Subcategory is a secondary classification of the [Service Category]( The ServiceSubcategory column adheres to the following requirements: -* ServiceSubcategory is RECOMMENDED to be present in a FOCUS dataset and MUST NOT be null. +* ServiceSubcategory is RECOMMENDED to be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) and MUST NOT be null. * ServiceSubcategory is of type String and MUST be one of the allowed values. * Each ServiceSubcategory value MUST have one and only one parent ServiceCategory as specified in the allowed values below. * Though a given *service* can have multiple purposes, each *service* SHOULD have one and only one ServiceSubcategory that best aligns with its primary purpose. diff --git a/specification/columns/skuid.md b/specification/columns/skuid.md index 7ab6ce38d..584a54416 100644 --- a/specification/columns/skuid.md +++ b/specification/columns/skuid.md @@ -2,7 +2,7 @@ A SKU ID is a unique identifier that defines a provider-supported construct for organizing properties that are common across one or more [*SKU Prices*](#glossary:sku-price). SKU ID can be referenced on a catalog or [*price list*](#glossary:price-list) published by a provider to look up detailed information about the SKU. The composition of the properties associated with the SKU ID may differ across providers. Some providers may not support the [*SKU*](#glossary:sku) construct and instead associate all such properties directly with the *SKU Price*. SKU ID is commonly used for analyzing cost based on *SKU*-related properties above the pricing constructs. -The SkuId column MUST be present in a FOCUS dataset when the provider publishes a SKU list. This column MUST be of type String. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. SkuId MUST equal SkuPriceId when a provider does not support an overarching SKU ID construct. +The SkuId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider publishes a SKU list. This column MUST be of type String. It MUST NOT be null when [ChargeClass](#chargeclass) is not "Correction" and [ChargeCategory](#chargecategory) is "Usage" or "Purchase", MUST be null when ChargeCategory is "Tax", and MAY be null for all other combinations of ChargeClass and ChargeCategory. SkuId MUST equal SkuPriceId when a provider does not support an overarching SKU ID construct. ## Column ID diff --git a/specification/columns/skumeter.md b/specification/columns/skumeter.md index 6b642abe2..bdd892b9a 100644 --- a/specification/columns/skumeter.md +++ b/specification/columns/skumeter.md @@ -2,11 +2,11 @@ The SKU Meter describes the functionality being metered or measured by a particular SKU in a charge. -Providers often have billing models in which multiple SKUs exist for a given service to describe and bill for different functionalities for that service. For example, an object storage service may have separate SKUs for functionalities such as object storage, API requests, data transfer, encryption, and object management. This field helps practitioners understand which functionalities are being metered by the different SKUs that appear in a FOCUS dataset. +Providers often have billing models in which multiple SKUs exist for a given service to describe and bill for different functionalities for that service. For example, an object storage service may have separate SKUs for functionalities such as object storage, API requests, data transfer, encryption, and object management. This field helps practitioners understand which functionalities are being metered by the different SKUs that appear in a [*FOCUS dataset*](#glossary:FOCUS-dataset). The SkuMeter column adheres to the following requirements: -* SkuMeter MUST be present in the billing data when when the provider includes a [SkuId](#skuid). +* SkuMeter MUST be present in a *FOCUS dataset* when when the provider includes a [SkuId](#skuid). * SkuMeter MUST be of type String. * SkuMeter MUST be null when SkuId is null. * SkuMeter SHOULD NOT be null when SkuId is not null. diff --git a/specification/columns/subaccountid.md b/specification/columns/subaccountid.md index f0bfd2a4a..7ca7ccd62 100644 --- a/specification/columns/subaccountid.md +++ b/specification/columns/subaccountid.md @@ -2,7 +2,7 @@ A Sub Account ID is a provider-assigned identifier assigned to a [*sub account*](#glossary:sub-account). Sub Account ID is commonly used for scenarios like grouping based on organizational constructs, access management needs, and cost allocation strategies. -The SubAccountId column MUST be present in a FOCUS dataset when the provider supports a *sub account* construct. This column MUST be of type String. If a charge does not apply to a *sub account*, the SubAccountId column MUST be null. +The SubAccountId column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports a *sub account* construct. This column MUST be of type String. If a charge does not apply to a *sub account*, the SubAccountId column MUST be null. See [Appendix: Grouping constructs for resources or services](#groupingconstructsforresourcesorservices) for details and examples of the different grouping constructs supported by FOCUS. diff --git a/specification/columns/subaccountname.md b/specification/columns/subaccountname.md index 0f837ecec..b64f56fd6 100644 --- a/specification/columns/subaccountname.md +++ b/specification/columns/subaccountname.md @@ -2,7 +2,7 @@ A Sub Account Name is a display name assigned to a [*sub account*](#glossary:sub-account). Sub account Name is commonly used for scenarios like grouping based on organizational constructs, access management needs, and cost allocation strategies. -The SubAccountName column MUST be present in a FOCUS dataset when the provider supports a *sub account* construct. This column MUST be of type String. If a charge does not apply to a *sub account*, the SubAccountName column MUST be null. +The SubAccountName column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports a *sub account* construct. This column MUST be of type String. If a charge does not apply to a *sub account*, the SubAccountName column MUST be null. See [Appendix: Grouping constructs for resources or services](#groupingconstructsforresourcesorservices) for details and examples of the different grouping constructs supported by FOCUS. diff --git a/specification/columns/tags.md b/specification/columns/tags.md index 4a9c8039e..d273fa195 100644 --- a/specification/columns/tags.md +++ b/specification/columns/tags.md @@ -6,7 +6,7 @@ A tag becomes [*finalized*](#glossary:finalized-tag) when a single value is sele The Tags column adheres to the following requirements: -* The Tags column MUST be present in a FOCUS dataset when the provider supports setting user or provider-defined tags. +* The Tags column MUST be present in a [*FOCUS dataset*](#glossary:FOCUS-dataset) when the provider supports setting user or provider-defined tags. * The Tags column MUST contain user-defined and provider-defined tags. * The Tags column MUST only contain finalized tags. * The Tags column MUST be in [KeyValueFormat](#key-valueformat). diff --git a/specification/metadata/data_generator/datagenerator.md b/specification/metadata/data_generator/datagenerator.md index abc636b46..64ed31dca 100644 --- a/specification/metadata/data_generator/datagenerator.md +++ b/specification/metadata/data_generator/datagenerator.md @@ -2,7 +2,7 @@ Human-readable name of the entity that is generating the data. -The DataGenerator MUST be provided in the metadata. DataGenerator MUST be of type String and MUST NOT be null. The DataGenerator SHOULD be easily associated with the provider who generated the FOCUS dataset. +The DataGenerator MUST be provided in the metadata. DataGenerator MUST be of type String and MUST NOT be null. The DataGenerator SHOULD be easily associated with the provider who generated the [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Metadata ID diff --git a/specification/metadata/metadata.mdpp b/specification/metadata/metadata.mdpp index 46a776168..128078fe5 100644 --- a/specification/metadata/metadata.mdpp +++ b/specification/metadata/metadata.mdpp @@ -1,6 +1,6 @@ # Metadata -The FOCUS specification defines a metadata structure to be supplied by data providers to facilitate practitioners' use of FOCUS data. This metadata includes general information about the data generator and the schema of the FOCUS dataset. +The FOCUS specification defines a metadata structure to be supplied by data providers to facilitate practitioners' use of FOCUS data. This metadata includes general information about the data generator and the schema of the [*FOCUS dataset*](#glossary:FOCUS-dataset). FOCUS Metadata SHOULD be provided in a format that is accessible programmatically, such as a file, website, API, or table. Providers SHOULD provide documentation on their implementation of the FOCUS metadata. diff --git a/specification/metadata/schema/column_definition/column_definition.mdpp b/specification/metadata/schema/column_definition/column_definition.mdpp index 18a2f8490..71ef1132e 100644 --- a/specification/metadata/schema/column_definition/column_definition.mdpp +++ b/specification/metadata/schema/column_definition/column_definition.mdpp @@ -1,6 +1,6 @@ # Column Definition -The FOCUS metadata schema column definition provides a list of the columns present in the FOCUS dataset along with metadata about the columns. +The FOCUS metadata schema column definition provides a list of the columns present in the [*FOCUS dataset*](#glossary:FOCUS-dataset) along with metadata about the columns. ## Requirements diff --git a/specification/metadata/schema/column_definition/columnname.md b/specification/metadata/schema/column_definition/columnname.md index bd6b40f96..0762433e9 100644 --- a/specification/metadata/schema/column_definition/columnname.md +++ b/specification/metadata/schema/column_definition/columnname.md @@ -1,6 +1,6 @@ # Column Name -The name of the column provided in the FOCUS dataset. +The name of the column provided in the [*FOCUS dataset*](#glossary:FOCUS-dataset). The ColumnName MUST be provided in the FOCUS Metadata schema. ColumnName MUST be of type String and MUST NOT contain null values. diff --git a/specification/metadata/schema/column_definition/datatype.md b/specification/metadata/schema/column_definition/datatype.md index 8a33adbca..bbd6b2eea 100644 --- a/specification/metadata/schema/column_definition/datatype.md +++ b/specification/metadata/schema/column_definition/datatype.md @@ -1,6 +1,6 @@ # Data Type -The data type of the column provided in the FOCUS dataset. +The data type of the column provided in the [*FOCUS dataset*](#glossary:FOCUS-dataset). The DataType MUST be provided in the FOCUS Metadata schema. DataType MUST be of type String and MUST NOT contain null values. diff --git a/specification/metadata/schema/column_definition/providertagprefixes.md b/specification/metadata/schema/column_definition/providertagprefixes.md index ca8ddb4b6..5fdfc278b 100644 --- a/specification/metadata/schema/column_definition/providertagprefixes.md +++ b/specification/metadata/schema/column_definition/providertagprefixes.md @@ -2,7 +2,7 @@ The Provider Tag Prefixes defines the list of prefixes used in the tag name of provider-defined [tags](#tags). This metadata is useful for the consumer to identify which tags are provider-defined vs user-defined. -The ProviderTagPrefixes MUST be provided when ColumnName is equal to Tags. The ProviderTagPrefix MUST be of type Array of Strings. The ProviderTagPrefixes SHOULD be easily associated with the provider who generated the FOCUS dataset. +The ProviderTagPrefixes MUST be provided when ColumnName is equal to Tags. The ProviderTagPrefix MUST be of type Array of Strings. The ProviderTagPrefixes SHOULD be easily associated with the provider who generated the [*FOCUS dataset*](#glossary:FOCUS-dataset). ## Metadata ID diff --git a/specification/metadata/schema/column_definition/stringencoding.md b/specification/metadata/schema/column_definition/stringencoding.md index 49f7fba22..ae790dee1 100644 --- a/specification/metadata/schema/column_definition/stringencoding.md +++ b/specification/metadata/schema/column_definition/stringencoding.md @@ -1,6 +1,6 @@ # String Encoding -The string encoding scheme of the column provided in the FOCUS dataset. +The string encoding scheme of the column provided in the [*FOCUS dataset*](#glossary:FOCUS-dataset). StringEncoding SHOULD be provided in the FOCUS Metadata schema when it is required to know this information in order to successfully read the data. StringEncoding MUST be of type String and MUST NOT contain null values. diff --git a/specification/metadata/schema/focusversion.md b/specification/metadata/schema/focusversion.md index 323b54428..0950e42a5 100644 --- a/specification/metadata/schema/focusversion.md +++ b/specification/metadata/schema/focusversion.md @@ -2,7 +2,7 @@ The version of FOCUS utilized for building the dataset. -The FocusVersion MUST be provided in the metadata. FocusVersion MUST be of type String and MUST NOT contain null values. FocusVersion MUST match one of the published versions of the FOCUS specification. FocusVersion MUST match the version of the FOCUS specification that the FOCUS dataset conforms to. +The FocusVersion MUST be provided in the metadata. FocusVersion MUST be of type String and MUST NOT contain null values. FocusVersion MUST match one of the published versions of the FOCUS specification. FocusVersion MUST match the version of the FOCUS specification that the [*FOCUS dataset*](#glossary:FOCUS-dataset) conforms to. ## Metadata ID diff --git a/specification/metadata/schema/providerversion.md b/specification/metadata/schema/providerversion.md index bcf3ebe6d..0b0c8450c 100644 --- a/specification/metadata/schema/providerversion.md +++ b/specification/metadata/schema/providerversion.md @@ -1,6 +1,6 @@ # Provider Version -The ProviderVersion MAY be supplied to declare the version of logic by which the FOCUS dataset was generated and is separate from FOCUS Version. ProviderVersion allows for the provider to specify changes that may not result in a structural change in the data. It is suggested that the provider version use a versioning approach such as [SemVer](https://semver.org) version. +The ProviderVersion MAY be supplied to declare the version of logic by which the [*FOCUS dataset*](#glossary:FOCUS-dataset) was generated and is separate from FOCUS Version. ProviderVersion allows for the provider to specify changes that may not result in a structural change in the data. It is suggested that the provider version use a versioning approach such as [SemVer](https://semver.org) version. ProviderVersion MUST be of type String and MUST NOT contain null values. If FocusVersion is changed a new ProviderVersion MUST be also changed. The provider MUST document what changes are present in the ProviderVersion. diff --git a/specification/metadata/schema/schema.mdpp b/specification/metadata/schema/schema.mdpp index 50825a4fe..8f40cc61b 100644 --- a/specification/metadata/schema/schema.mdpp +++ b/specification/metadata/schema/schema.mdpp @@ -8,7 +8,7 @@ The schema metadata object and its contents provides information about the struc FOCUS data artifacts, whether they are data files, data streams, or data tables, MUST provide a clear reference to the schema of the data. This reference MUST be retrievable without inspection of the contents of the FOCUS data within the data artifact. For some delivery mechanisms such as database tables, the provider may rely on the schema functionality of the providing system. -It is recommended that the schema reference be provided as an external reference rather than included in full as metadata accompanying the data artifact. This allows for easier understanding of when changes to the schema of the FOCUS datasets occurs. +It is recommended that the schema reference be provided as an external reference rather than included in full as metadata accompanying the data artifact. This allows for easier understanding of when changes to the schema of the [*FOCUS datasets*](#glossary:FOCUS-dataset) occurs. ### Schema Metadata Creation