The "Editorial Style Guidelines" section ensures consistency and clarity across all documentation. Adhering to these guidelines is crucial for maintaining a unified style, which enhances readability and reduces misinterpretation. By following the specified standards—whether in formatting, linking, or structuring information—we ensure that all documents are professional, clear, and aligned with our editorial principles. Consistent application of these guidelines contributes to high-quality, user-friendly documentation.
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.
| Component | Display (PDF, HTML) | Markdown (examples) | Editorial Guidelines |
|---|---|---|---|
| Column & Attribute Names: |
Column Names: - Pricing Quantity - Pricing Unit - Provider Attribute Names: - Currency Code Format - Date/Time Format |
Column Names: Pricing Quantity Pricing Unit Provider Attribute Names: Currency Code Format Date/Time Format |
- Use the display name in the non-normative section. - The first occurrence in a section is linked to the section. |
| Column & Attribute IDs: |
Columns IDs: - PricingQuantity - PricingUnit - ProviderName Attributes IDs: - CurrencyCodeFormat - DateTimeFormat |
Columns IDs: PricingQuantity PricingUnit ProviderName Attributes IDs: CurrencyCodeFormat DateTimeFormat |
- Use PascalCamel case (the first letter of every word, is capitalized) - Normal text without bold or italics. - The first occurrence in a section is linked to the section. |
| Column Values: |
- "Usage" - "Tax" - "TB" |
This column: * MUST be null when ChargeCategory is "Tax" ... |
- Enclosed in double quotation marks - Normal text without bold or italics |
| Normative Keywords & Statements | MUST, MAY, MUST NOT and normative statements |
This column: * MUST NOT be null when ChargeClass is ... * MUST be null when ChargeCategory is ... * MAY be null for all other combinations of ... |
- All uppercase, without bold. - Bullet list format. |
| Glossary | SKU, resource, service |
[*SKU*](#glossary:sku) [*resource*](#glossary:resource) [*service*](#glossary:service) |
- Blue font + italic - The first occurrence in a section is linked to the glossary. |
| Important Text |  |
> Important Consideration | - It is added as a note. |
| Key-Value Format | JSON Script |
**Example**:
```json
{
"key1": "value1",
"key2": true,
"key3": 123
}
```
|
- Monospace font |
| Tables |  |
 |
- Tables: Simple tables can be created using markdown, but for more complex tables, it is RECOMMENDED to use HTML elements. See the example below. |
Editorial Notes
-
Linking Only the First Time: To prevent excessive linking within sections, Column Name, Column ID, Attributes Names, Attributes IDs, and Glossary will only be linked to their corresponding section or glossary the first time they appear in a section.
-
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).
2.28. Pricing Quantity
The Pricing Quantity represents the volume of a given SKU associated with a resource or service used or purchased, based on the Pricing Unit. Distinct from Consumed Quantity (complementary to Consumed Unit), 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 Numeric Format requirements
- The value MAY be negative in cases where ChargeClass is "Correction".
This column:
- MUST NOT be null when ChargeClass is not "Correction" and 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.
2.28.1. Column ID
PricingQuantity
2.28.2. Display Name
Pricing Quantity
2.28.3. Description
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
2.28.5. Introduced (version)
1.0-preview
This is an example of a complex table with merged rows and columns, along with an additional header row.
| Heading 1 | Heading 2 | Heading 3 | |
|---|---|---|---|
| Cell 1,1 and Cell 1,2 Merged | Cell 1,3 | Cell 1,4 | |
| Heading 4 | Heading 5 | Heading 6 | Heading 7 |
| Cell 2,1 & Cell 2,2 | Cell 3,3 & Cell 4,3 |
Cell 3,4 | |
| Cell 4,1 | Cell 4,2 | Cell 4,4 | |
This is how it is written in HTML:
<table border="1" cellpadding="8" cellspacing="0">
<tr>
<th colspan="2"><b>Heading 1</b></th>
<th><b>Heading 2</b></th>
<th><b>Heading 3</b></th>
</tr>
<tr>
<td colspan="2">Cell 1,1 and Cell 1,2 Merged</td>
<td>Cell 1,3</td>
<td>Cell 1,4</td>
</tr>
<tr>
<td><b>Heading 4</b></td>
<td><b>Heading 5</b></td>
<td><b>Heading 6</b></td>
<td><b>Heading 7</b></td>
</tr>
<tr>
<td colspan="2">Cell 2,1 & Cell 2,2</td>
<td rowspan="2">Cell 3,3 </br>& </br> Cell 4,3</td>
<td>Cell 3,4</td>
</tr>
<tr>
<td>Cell 4,1</td>
<td>Cell 4,2</td>
<td>Cell 4,4</td>
</tr>
</table>