Editorial updates on column IDs and Display Names (#582)

These changes won't affect the content in Release V1.1. They are actually editorial guidelines according to the working group agreement. --------- Co-authored-by: ijurica <[email protected]>
FinOps-Open-Cost-and-Usage-Spec · Oct 17, 2024 · fbb9ddf · fbb9ddf
1 parent c7abe9c
commit fbb9ddf
Showing 1 changed file with 46 additions and 27 deletions.
diff --git a/EDITORIAL_GUIDELINES.md b/EDITORIAL_GUIDELINES.md
@@ -3,7 +3,6 @@ The "Editorial Style Guidelines" section ensures consistency and clarity across
 
 These guidelines can be modified through a Pull Request (PR), which the members must review and agree upon. This process ensures that any changes are thoughtfully considered and maintains the overall integrity of our editorial standards.
 
-
 <table>
     <tr>
         <th>Component</th>
@@ -12,27 +11,26 @@ These guidelines can be modified through a Pull Request (PR), which the members
         <th>Editorial Guidelines</th>
     </tr>
     <tr>
-        <td><strong>Column &amp; Attribute Names</strong>:</td>
+        <td><strong>Column &amp; Attribute Names:</strong></td>
         <td>
             <strong>Column Names</strong>:<br>
-            - <strong>Pricing Quantity</strong><br>
-            - <strong>Pricing Unit</strong><br>
-            - <strong>Provider</strong> <br><br>
+            - Pricing Quantity<br>
+            - Pricing Unit<br>
+            - Provider <br><br>
             <strong>Attribute Names</strong>:<br>
-            - <strong>Currency Code Format</strong><br>
-            - <strong>Date/Time Format</strong>
+            - Currency Code Format<br>
+            - Date/Time Format
         </td>
         <td>
-            <strong>Column Names</strong>:<br>
-            &nbsp;&nbsp; **Pricing Quantity**<br>
-            &nbsp;&nbsp; **Pricing Unit**<br>
-            &nbsp;&nbsp; **Provider**<br><br>
+            <strong>Column Names:</strong><br>
+            &nbsp;&nbsp; Pricing Quantity<br>
+            &nbsp;&nbsp; Pricing Unit<br>
+            &nbsp;&nbsp; Provider<br><br>
             <strong>Attribute Names</strong>:<br>
-            &nbsp;&nbsp; **Currency Code Format**<br>
-            &nbsp;&nbsp; **Date/Time Format**<br>
+            &nbsp;&nbsp; Currency Code Format<br>
+            &nbsp;&nbsp; Date/Time Format<br>
         </td>
         <td>
-            - Bold <br>
             - Use the display name in the non-normative section.<br>
             - The first occurrence in a section is linked to the section.
         </td>
@@ -41,28 +39,44 @@ These guidelines can be modified through a Pull Request (PR), which the members
         <td><strong>Column &amp; Attribute IDs:</strong></td>
         <td>
            <strong>Columns IDs</strong>:<br>
-            - PricingQuantity</strong><br> 
-            - PricingUnit</strong><br> 
-            - ProviderName</strong> <br><br>
+            - PricingQuantity<br> 
+            - PricingUnit<br> 
+            - ProviderName<br><br>
           <strong>Attributes IDs</strong>:<br>
             - CurrencyCodeFormat <br> 
             - DateTimeFormat <br>
         </td>
         <td>
-          <strong>Columns IDs:</strong>:<br>
+          <strong>Columns IDs:</strong><br>
           &nbsp;&nbsp; PricingQuantity <br>
-          &nbsp;&nbsp; PricingUnit</strong><br>
-          &nbsp;&nbsp; ProviderName</strong> <br><br>
+          &nbsp;&nbsp; PricingUnit<br>
+          &nbsp;&nbsp; ProviderName <br><br>
           <strong>Attributes IDs:</strong> </br>
           &nbsp;&nbsp; CurrencyCodeFormat </br>
           &nbsp;&nbsp; DateTimeFormat <br>
         </td>
         <td>
-           - Use PascalCamel case (the first letter of every word, is capitalized)
+           - Use PascalCamel case (the first letter of every word, is capitalized)<br>
            - Normal text without bold or italics.<br>
            - The first occurrence in a section is linked to the section.
         </td>
     </tr>
+    <tr>
+        <td><strong>Column Values:</strong></td>
+        <td>
+            - "Usage"<br>
+            - "Tax"<br>
+            - "TB"<br>
+        </td>
+        <td>
+            This column:<br>
+            &nbsp;&nbsp; * MUST be null when ChargeCategory is "Tax" ...
+        </td>
+        <td>
+            - Enclosed in double quotation marks<br>
+            - Normal text without bold or italics
+        </td>
+    </tr>
     <tr>
         <td><strong>Normative Keywords &amp; Statements</strong></td>
         <td>
@@ -130,21 +144,26 @@ These guidelines can be modified through a Pull Request (PR), which the members
 
 * **Normative Requirements as a Bullet List**: Normative statements (those using Normative Keywords) should be written as bullet points instead of lengthy sentences. 
 
+* **Column IDs:** They SHOULD be used in normative text sections, such as when specifying mandatory rules, schema definitions, or other implementation-related content. These Column IDs should be formatted without spaces and should match the exact naming conventions used in the schema (e.g., CommitmentDiscountID). 
+
+* **Display Names:** They SHOULD be used in introductory or explanatory sections where natural language context is more appropriate. In these sections, display names should follow normal text conventions, including spaces between words (e.g., Commitment Discount ID).
+
+
 ### Example
 
 > **2.28. Pricing Quantity**
 >
-> 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 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*](#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". 
+>  * 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 is not "Correction" and ChargeCategory is "Usage" or "Purchase", 
+>  * 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.
+>  * 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.
 >
 > **2.28.1. Column ID**
 >
@@ -156,7 +175,7 @@ These guidelines can be modified through a Pull Request (PR), which the members
 >
 > **2.28.3. Description**
 >
-> The volume of a given SKU associated with a resource or service used or purchased, based on the Pricing Unit. 
+> The volume of a given SKU associated with a *resource* or *service* used or purchased, based on the Pricing Unit. 
 >
 > **2.28.4. Content Constraints Constraint**
 >