Updates to make attribute formatting consistent + make numeric format…

… content more concise
FinOps-Open-Cost-and-Usage-Spec · Nov 4, 2023 · 29fc5a7 · 29fc5a7
1 parent b638ec8
commit 29fc5a7
Show file tree

Hide file tree

Showing 5 changed files with 43 additions and 58 deletions.
diff --git a/specification/attributes/column_naming_convention.md b/specification/attributes/column_naming_convention.md
@@ -3,8 +3,7 @@
 Column IDs provided in cost data following a consistent naming convention reduces friction for FinOps practitioners
 that consume the data for analysis, reporting, and other use cases.
 
-All columns defined in FOCUS MUST follow the naming requirements listed below. Provider generated columns SHOULD adopt
-these same naming requirements over time.
+All columns defined in the FOCUS specification MUST follow the naming requirements listed below. Provider generated columns SHOULD adopt these same naming requirements over time.
 
 ## Attribute ID
 

diff --git a/specification/attributes/currency_code_format.md b/specification/attributes/currency_code_format.md
@@ -2,7 +2,7 @@
 
 Columns that contain currency information in cost data following a consistent format reduces friction for FinOps practitioners that consume the data for analysis, reporting, and other use cases.
 
-All currency related columns defined in the FOCUS schema MUST follow the currency formatting requirements listed below. Provider generated currency-related columns SHOULD adopt the same format requirements over time.
+All columns capturing a currency value, defined in the FOCUS specification, MUST follow the requirements listed below. Provider generated currency-related columns SHOULD adopt the same format requirements over time.
 
 ## Attribute ID
 

diff --git a/specification/attributes/datetime_format.md b/specification/attributes/datetime_format.md
@@ -2,7 +2,7 @@
 
 Columns that provide date and time information conforming to specified rules and formatting requirements ensure clarity, accuracy, and ease of interpretation for both humans and systems.
 
-All date/time related columns, defined in the FOCUS specification, MUST be represented in UTC and follow the ISO 8601 aligned formatting requirements listed below. Provider generated date/time related columns SHOULD also be represented in UTC and conform to the ISO 8601 standard.
+All columns capturing a date/time value, defined in the FOCUS specification, MUST follow the formatting requirements listed below. Provider generated date/time related columns SHOULD adopt the same format requirements over time.
 
 ## Attribute ID
 

diff --git a/specification/attributes/null_handling.md b/specification/attributes/null_handling.md
@@ -3,8 +3,7 @@
 Cost data rows that don't have a value that can be presented for a column must be handled in a consistent way to reduce
 friction for FinOps practitioners that consume the data for analysis, reporting, and other use cases.
 
-All columns defined in FOCUS MUST follow the null handling requirements listed below. Provider generated columns SHOULD
-adopt these same null handling requirements over time.
+All columns defined in the FOCUS specification MUST follow the null handling requirements listed below. Provider generated columns SHOULD adopt these same null handling requirements over time.
 
 ## Attribute ID
 

diff --git a/specification/attributes/numeric_format.md b/specification/attributes/numeric_format.md
@@ -1,41 +1,8 @@
 # Numeric Format
 
-Columns that provide numeric values conforming to specified rules and formatting requirements ensure clarity, accuracy, and ease of interpretation for humans and systems.
+Columns that provide numeric values conforming to specified rules and formatting requirements ensure clarity, accuracy, and ease of interpretation for humans and systems. The FOCUS specification does not require a specific level of precision for numeric values. The level of precision required for a given column is determined by the provider and should be part of a data definition published by the provider.
 
-This format requires that single numeric values be represented using an integer or decimal format without additional characters or qualifiers.  The following lists provide examples of values that meet the requirements and those that do not.
-
-* Values Meeting Numeric Requirements:
-  * -100.2
-  * -3
-  * 4
-  * 1.234
-
-* Values NOT Meeting Numeric Requirements
-  * 1 1/2 - contains fractional notation
-  * [3,5,8] - contains an array
-  * [4:5] - contains a range
-  * 5i + 4 - contains a complex number
-  * sqrt(2) - contains a mathematical symbol or operation
-  * 2.3^3 - contains an exponent
-  * 32 GiB - contains a unit of measure
-  * $32 - contains a currency symbol
-  * 3,432,342 - contains a comma
-  * +333 - contains a positive sign
-
-The FOCUS specification does not require a specific level of precision for numeric values.  The level of precision required for a given column is determined by the provider as a part of a data definition published by the provider.  The following table outlines the options for specifying the level of precision for a given column in a data definition document.
-
-* Integer number formats correspond to standard data types defined by ISO/IEC 9899:2018
-
-* Decimal formats correspond to ISO/IEC/IEEE 60559:2011 and IEEE 754-2008 definitions.
-
-| Precision      | Qualifier            | Definition          | Range / Significant Digits          |
-| :--------------| :------------------- | :------------------ | :-------------------- |
-| Integer        | Short                | 16-bit signed short int ISO/IEC 9899:2018 | -32,767 to +32,767 |
-| Integer        | Long                 | 32-bit signed long int ISO/IEC 9899:2018 | -2,147,483,647 to +2,147,483,647 |
-| Integer        | Extended             | 64-bit signed two's complement integer *or higher* | -(2^63 - 1) to (2^63 - 1) |
-| Decimal         | Single               | 32-bit binary format IEEE 754-2008 floating-point (decimal32) | 9 |
-| Decimal          | Double               | 64-bit binary format IEEE 754-2008 floating-point (decimal64) | 16 |
-| Decimal          | Extended      | 128-bit binary format IEEE 754-2008 floating-point (decimal128) or higher | 36+ |
+All columns capturing a numeric value, defined in the FOCUS specification, MUST follow the formatting requirements listed below. Provider generated date/time related columns SHOULD adopt the same format requirements over time.
 
 ## Attribute ID
 
@@ -53,30 +20,50 @@ Rules and formatting requirements for numeric columns appearing in billing data.
 
 All columns capturing a numeric value, defined in the FOCUS specification, MUST be a real number represented as an integer or a decimal value, meeting the following requirements:
 
-* Columns with a Numeric format MUST contain a single numeric value.
+* Columns with a Numeric value format MUST contain a single numeric value.
 * Numeric values MUST be expressed as integer or decimal values. Fractional notation MUST NOT be used.
 * Numeric values MUST NOT be expressed with mathematical symbols, operators, or exponent values.
 * Numeric values MUST NOT contain qualifiers or additional characters (e.g., currency symbols, units of measure, etc.).
 * Numeric values MUST NOT contain commas or punctuation marks except for a single decimal point if required to express a decimal value.
 * Numeric values MUST NOT include a character to represent a sign for a positive value. A negative sign (-) MUST indicate a negative value.
 * Numeric values MUST NOT be used to represent binary values (e.g., 0 or 1).
+* Columns with a Numeric value format MUST present one of the following values as the Data type in the column definition.
+  | Value Format  | Data Type | Type Description |
+  |:--------------|:----------|:-----------------|
+  | Numeric value | Numeric   | Specifies any numeric value compliant with this attribute definition. This type is used when the column definition does not specify a more specific numeric type. |
+  | Numeric value | Integer   | Specifies a numeric value represented by a whole number or by zero. Integer number formats correspond to standard data types defined by ISO/IEC 9899:2018 |
+  | Numeric value | Decimal   | Specifies a numeric value represented by a decimal number. Decimal formats correspond to ISO/IEC/IEEE 60559:2011 and IEEE 754-2008 definitions. |
+* Providers SHOULD define one of the following precision values for every column with a numeric data type in a data definition document that providers publish.
+  | Data Type | Precision | Definition                                                                | Range / Significant Digits       |
+  |:----------|:----------|:--------------------------------------------------------------------------|:---------------------------------|
+  | Integer   | Short     | 16-bit signed short int ISO/IEC 9899:2018                                 | -32,767 to +32,767               |
+  | Integer   | Long      | 32-bit signed long int ISO/IEC 9899:2018                                  | -2,147,483,647 to +2,147,483,647 |
+  | Integer   | Extended  | 64-bit signed two's complement integer *or higher*                        | -(2^63 - 1) to (2^63 - 1)        |
+  | Decimal   | Single    | 32-bit binary format IEEE 754-2008 floating-point (decimal32)             | 9                                |
+  | Decimal   | Double    | 64-bit binary format IEEE 754-2008 floating-point (decimal64)             | 16                               |
+  | Decimal   | Extended  | 128-bit binary format IEEE 754-2008 floating-point (decimal128) or higher | 36+                              |
+
+### Examples
+
+This format requires that single numeric values be represented using an integer or decimal format without additional characters or qualifiers. The following lists provide examples of values that meet the requirements and those that do not.
 
-Numeric data types are defined in each column specification.  The following table outlines valid values for the "Data type" constraint in a column definition.  One of the following three data types MUST be present in the "Data type" constraint for a column definition with a "Value format" of "Numeric value."
-
-| Data Type       |                 |
-| :-------------- | :-------------- |
-| Numeric         | General Numeric Type  | Specifies any numeric value compliant with this attribute definition.  This type is used when the column definition does not specify a more specific numeric type. |
-| Integer         | Integer               | Specifies a numeric value represented by a whole number or by zero. |
-| Decimal         | Decimal               | Specifies a numeric value represented by a decimal number |
-
-The Numeric Data type is specified in the column definition as the "Data type" constraint, as shown in the following example table.  All columns listing a numeric data type MUST list "Numeric value" as the value format.
-
-|    Constraint   |      Value      |
-|:----------------|:----------------|
-| Column required | True            |
-| Data type       | Decimal         |
-| Allows nulls    | False           |
-| Value format    | Numeric value   |
+* Values Meeting Numeric Requirements:
+  * -100.2
+  * -3
+  * 4
+  * 1.234
+
+* Values NOT Meeting Numeric Requirements
+  * 1 1/2 - contains fractional notation
+  * [3,5,8] - contains an array
+  * [4:5] - contains a range
+  * 5i + 4 - contains a complex number
+  * sqrt(2) - contains a mathematical symbol or operation
+  * 2.3^3 - contains an exponent
+  * 32 GiB - contains a unit of measure
+  * $32 - contains a currency symbol
+  * 3,432,342 - contains a comma
+  * +333 - contains a positive sign
 
 ## Exceptions