Merge pull request #282 from FinOps-Open-Cost-and-Usage-Spec/working_…

…draft FOCUS v1.0 - preview payload
FinOps-Open-Cost-and-Usage-Spec · Nov 16, 2023 · 8ed6828 · 8ed6828
2 parents 5de5ced + 9e818ba
commit 8ed6828
Show file tree

Hide file tree

Showing 127 changed files with 3,265 additions and 796 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 The Open Cloud Bill working group will develop a common, source-neutral schema of
 billing, cost, usage, and observability data mapped to a variety of cloud service provider and SaaS product
-sources, with metadata, dimensions, metrics, and measures for the source and common schema fields. As per the [Working Group Chater]() **Link TBC**
+sources, with metadata, dimensions, metrics, and measures for the source and common schema fields. As per the [Working Group Charter]() **Link TBC**
 
 ## Notation Conventions and Compliance
 
@@ -56,15 +56,13 @@ Most people will not need any development environment, it is mostly needed by th
 5. Install pandoc and required filter library
 
 	`brew install pandoc`
-	
+
 	`brew install --cask wkhtmltopdf`
-6. If your machine does not have git/make etc, you might fun the following: Install developer command line tools for MacOS 
+6. If your machine does not have git/make etc, you might fun the following: Install developer command line tools for MacOS
 
 	`xcode-select --install`
 
 ### Assembling the specification locally
 
 1. Move into the `specification` folder
 2. Use make to generate the spec `make`
-
-[specification]: specification/specification-overview.md
diff --git a/spec-design-guidelines.md b/spec-design-guidelines.md
@@ -22,4 +22,4 @@ The specification content:
 * must be written with an overall model before digging into the details. Each section will start with an overview of the feature and description
 * should be written in order, so when read top to bottom any referenced content has already been covered in a previous section
 
-Some of these items have been formed based on this W3C video on [Best Pracitices for Editing W3C Specifications](https://www.youtube.com/watch?v=FdB8mqlf1l8)
+Some of these items have been formed based on this W3C video on [Best Practices for Editing W3C Specifications](https://www.youtube.com/watch?v=FdB8mqlf1l8)
diff --git a/spec-development-workflow.md b/spec-development-workflow.md
@@ -1,9 +1,9 @@
 # FOCUS specification formatting + submission process
 
 
-## Finalizing content in the google doc
+## Finalizing content in the Google doc
 
-Start with the google doc worksheet that has been created based on discussions in the working sessions. Once the working session(s) related to the task complete, the content may require cleanup and/or enhancement to capture the discussions and decisions that were made during the working sessions. 
+Start with the Google doc worksheet that has been created based on discussions in the working sessions. Once the working session(s) related to the task complete, the content may require cleanup and/or enhancement to capture the discussions and decisions that were made during the working sessions.
 
 Follow the following steps:
 
@@ -12,18 +12,18 @@ Follow the following steps:
    * Make sure example mappings and scenarios are populated
    * Make sure formatting and writing is consistent with previous tasks
 2. Reach out to the squad working on the task for final edits/comments. Incorporate any changes based on comments
-3. If naming changes, update document name, github issue and related fields, agenda and other places where the task may be referenced.
+3. If naming changes, update document name, GitHub issue and related fields, agenda and other places where the task may be referenced.
 
 ### Converting spec content to Markdown
 
 The content in the worksheets will be broken into two documents in the FOCUS_Spec repository. First section is the 'Spec content' and will go into the specification folder within the folder. The second section will go under the supporting_content folder.
 
 Tools to use for converting to markdown:
 - [Clipboard-To-Markdown](https://euangoddard.github.io/clipboard2markdown/) is useful for converting content other than the tables within your content.
-- [Tables Generator](https://www.tablesgenerator.com/markdown_tables#) is useful for converting tables in your content.
+- [Tables Generator](https://www.tablesgenerator.com/markdown_tables) is useful for converting tables in your content.
 
 As you convert, be aware of the following conversion errors:
-- Content that has special characters e.g. phrase '<not specified>' or placeholders in content like '//container.googleapis.com/projects/<project_id>/locations/\<location>/clusters/\<cluster>' may not convert correctly without escaping. Find these inconsistencies after conversion and escape the special characters when necessary. 
+- Content that has special characters e.g. phrase '<not specified>' or placeholders in content like '//container.googleapis.com/projects/<project_id>/locations/\<location>/clusters/\<cluster>' may not convert correctly without escaping. Find these inconsistencies after conversion and escape the special characters when necessary.
 - Multi-line content within table cells also don't convert correctly. You'll have to put `<br>` tags to ensure the multi-line content renders correctly in markdown.
 - Ensure HTML or anchor links are set up correctly after the conversion
 
@@ -32,19 +32,19 @@ Markdown linter will catch some issues that might happen during conversion. Comm
 - New lines may not get added at the end of documents (and at times before and after headings). These are needed for the linter to pass
 - Trailing spaces in your content will fail the build.
 
-VSCode and other IDEs may highlight these. If not, it's a good idea to run the build process locally before you push the changes to git. 
+VSCode and other IDEs may highlight these. If not, it's a good idea to run the build process locally before you push the changes to git.
 
 ### Local make process
 
-Steps for setting up and building locally are listed here: <https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec#focus-specification-development-environment> 
+Steps for setting up and building locally are listed here: <https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec#focus-specification-development-environment>
 
 Git workflow
 ------------
 
 This is one way to the git workflow. You may have other preferred approaches. Unless specified below as being required, each contributor has the chance to follow their own process.
 
-1.  Go to the github issue you're working on and assign it to yourself under the Assignees section
-2.  Create a topic branch by clicking on the 'Create a branch' link under the Development section
+1. Go to the GitHub issue you're working on and assign it to yourself under the Assignees section
+2. Create a topic branch by clicking on the 'Create a branch' link under the Development section
 3. Name your branch - by default, it's selecting the issue title. It doesn’t need to be as long as the title (e.g. 10-create-a-service-name-dimension -> 10-service-name-dimension)
 4. Checkout to your preferred workspace and make the edits.
 5. Build the specification locally to ensure there are no issues highlighted by the linter

diff --git a/specification/Makefile b/specification/Makefile
@@ -6,7 +6,7 @@ STYLE="working_draft"
 endif
 PDF_MARGINS=--variable margin-top=15 --variable margin-bottom=25 --variable margin-left=0 --variable margin-right=10
 PDF_FOOTER=--pdf-engine-opt="--footer-right" --pdf-engine-opt="[page] of [topage]" --pdf-engine-opt="--footer-font-name" --pdf-engine-opt="Palatino" --pdf-engine-opt="--footer-font-size" --pdf-engine-opt="8"
-SPEC_SOURCE_FILES=$(filter-out spec.md, $(wildcard *.md*)) $(wildcard dimensions/*.md*) $(wildcard attributes/*.md*) $(wildcard metrics/*.md*) $(wildcard appendix/*.md*)
+SPEC_SOURCE_FILES=$(filter-out spec.md, $(wildcard *.md*)) $(wildcard columns/*.md*) $(wildcard attributes/*.md*) $(wildcard appendix/*.md*)
 SPEC_SOURCE_MDFILES=$(filter-out %.mdpp, $(SPEC_SOURCE_FILES))
 export TOCDEPTH=2
 all: spec.md spec.pdf spec.html
@@ -23,8 +23,7 @@ ifneq ("$(wildcard versions/${STYLE}.md)","")
 else
 	cp versions/working_draft.md version.md
 endif
-	./validate_includes.py dimensions
-	./validate_includes.py metrics
+	./validate_includes.py columns
 	./validate_includes.py attributes
 	./validate_includes.py appendix
 	PYTHONPATH=../vendored/ $(MARKDOWNPP) spec.mdpp -o $@

diff --git a/specification/appendix/grouping_constructs_for_resources_and_or_services.md b/specification/appendix/grouping_constructs_for_resources_and_or_services.md
@@ -1,10 +1,10 @@
-# Grouping constructs for resources and/or services
+# Grouping constructs for resources or services
 
-Providers natively support various constructs for grouping resources and/or services. These grouping constructs are often used to mimic organizational structures, technical architectures, cost attribution/allocation and access management boundaries, or other customer-specific structures based on requirements.
+Providers natively support various constructs for grouping resources or services. These grouping constructs are often used to mimic organizational structures, technical architectures, cost attribution/allocation and access management boundaries, or other customer-specific structures based on requirements.
 
-Providers may support multiple levels of resource and/or service grouping mechanisms. FOCUS supports two distinct levels of groupings that are commonly needed for FinOps capabilities like chargeback, invoice reconciliation and cost allocation.
+Providers may support multiple levels of resource or service grouping mechanisms. FOCUS supports two distinct levels of groupings that are commonly needed for FinOps capabilities like chargeback, invoice reconciliation and cost allocation.
 
-* Billing account: A mandatory container for resources and/or services that are billed together in an invoice. Billing accounts are commonly used for scenarios like grouping based on organizational constructs, invoice reconciliation and cost allocation strategies.
+* Billing account: A mandatory container for resources or services that are billed together in an invoice. Billing accounts are commonly used for scenarios like grouping based on organizational constructs, invoice reconciliation and cost allocation strategies.
 * Sub account: An optional provider-supported construct for organizing resources and services connected to a billing account. Sub accounts are commonly used for scenarios like grouping based on organizational constructs, access management needs and cost allocation strategies. Sub accounts must be associated with a billing account as they do not receive invoices.
 
 The table below highlights key properties of the two grouping constructs supported by FOCUS.

diff --git a/specification/appendix/origination_of_cost_data.md b/specification/appendix/origination_of_cost_data.md
@@ -2,24 +2,24 @@
 
 Cost data presented in the billing datasets originates from various sources depending on the purchasing mechanism. There are at least 3 different pieces of information that are important for understanding where cost originated from.
 
-* Provider: The entity that made the resources and/or services available for purchase.
-* Publisher: The entity that produced the resources and/or services that were purchased.
-* Invoice Issuer: The entity responsible for invoicing for the resources and/or services consumed.
+* Provider: The entity that made the resources or services available for purchase.
+* Publisher: The entity that produced the resources or services that were purchased.
+* Invoice Issuer: The entity responsible for invoicing for the resources or services consumed.
 
-The value for each of these may be different depending on the various purchasing scenarios for resources and/or services. Use cases for purchasing direct, via a Managed Service Provider (MSP), via a cloud marketplace, and from internal service offerings were considered. The table below presents a few scenarios to show how the value for each dimension may change based on the purchasing scenario.
+The value for each of these may be different depending on the various purchasing scenarios for resources or services. Use cases for purchasing direct, via a Managed Service Provider (MSP), via a cloud marketplace, and from internal service offerings were considered. The table below presents a few scenarios to show how the value for each dimension may change based on the purchasing scenario.
 
 | #   | Scenario                                                                                                                                      | Provider                 | Publisher                                                                                                              | Invoice Issuer                                              |
 |:----|:----------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------|:-----------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------|
 | 1.1 | Purchasing cloud services directly from cloud provider                                                                                        | Cloud service provider   | Cloud service provider                                                                                                 | Cloud service provider                                     |
 | 1.2 | Purchasing cloud services from the cloud provider where the cloud region is operated by a 3rd party                                           | Cloud service provider   | Cloud service provider                                                                                                 | Entity operating the region for the cloud service provider |
 | 2.1 | Purchasing cloud services via MSP                                                                                                             | Managed Service Provider | Cloud service provider                                                                                                 | Managed Service Provider                                   |
-| 2.2 | Purchasing cloud-agnostic resources and/or services built/sold by an MSP                                                                      | Managed Service Provider | Managed Service Provider                                                                                               | Managed Service Provider                                   |
+| 2.2 | Purchasing cloud-agnostic resources or services built/sold by an MSP                                                                      | Managed Service Provider | Managed Service Provider                                                                                               | Managed Service Provider                                   |
 | 2.3 | Purchasing labor services from managed service provider                                                                                       | Managed Service Provider | Managed Service Provider                                                                                               | Managed Service Provider                                   |
-| 3.1 | Purchasing a cloud marketplace offering that runs on the cloud provider                                                                       | Cloud service provider   | Company building the software and/or services (Cloud service provider OR third-party software and/or services company) | Cloud service provider                                     |
+| 3.1 | Purchasing a cloud marketplace offering that runs on the cloud provider                                                                       | Cloud service provider   | Company building the software or services (Cloud service provider OR third-party software or services company) | Cloud service provider                                     |
 | 3.2 | Purchasing a cloud marketplace offering that is not running directly on your cloud infrastructure (e.g,. SaaS product, Professional Services) | Cloud service provider   | Company producing the SaaS or services product                                                                         | Cloud service provider                                     |
 | 3.3 | Purchasing a SaaS product that is not directly running on your cloud infrastructure from a 3rd party reseller managed cloud marketplace       | Cloud service provider   | SaaS provider                                                                                                          | Reseller                                                   |
 | 4.1 | Purchasing SaaS software directly from provider                                                                                               | SaaS provider            | SaaS provider                                                                                                          | SaaS provider                                              |
 | 4.2 | Purchasing SaaS software that additionally runs on your cloud resources (in addition to #4.1)                                                 | Cloud service provider   | Cloud service provider                                                                                                 | Cloud service provider                                     |
-| 5.1 | Purchasing internal infrastructure and/or services offerings running on-premise                                                               | Internal product name    | Internal product name                                                                                                  | Internal product name                                      |
-| 5.2 | Purchasing internal infrastructure and/or services offerings running on cloud                                                                 | Internal product name    | Internal product name                                                                                                  | Internal product name                                      |
+| 5.1 | Purchasing internal infrastructure or services offerings running on-premise                                                               | Internal product name    | Internal product name                                                                                                  | Internal product name                                      |
+| 5.2 | Purchasing internal infrastructure or services offerings running on cloud                                                                 | Internal product name    | Internal product name                                                                                                  | Internal product name                                      |
 | 5.3 | Associated software license cost for use on an on-premise infrastructure platform (Where license cost is presented separately in cost data)   | Internal product name    | Company producing the software                                                                                         | Internal product name                                      |
diff --git a/specification/attributes/attributes.mdpp b/specification/attributes/attributes.mdpp
@@ -8,4 +8,8 @@ for data granularity, recency, frequency, etc. Requirements defined in attribute
 !INCLUDE "column_naming_convention.md",1
 !INCLUDE "currency_code_format.md",1
 !INCLUDE "datetime_format.md",1
+!INCLUDE "discount_handling.md",1
+!INCLUDE "key_value_format.md",1
 !INCLUDE "null_handling.md",1
+!INCLUDE "numeric_format.md",1
+!INCLUDE "unit_format.md",1