Improvements To Metadata

specification/appendix/appendix.mdpp

@@ -4,3 +4,4 @@
 
 !INCLUDE "grouping_constructs_for_resources_and_or_services.md",1
 !INCLUDE "origination_of_cost_data.md",1
+!INCLUDE "examples/examples.mdpp",1

specification/appendix/examples/examples.mdpp

@@ -0,0 +1,5 @@
+# Examples
+
+*This section is non-normative.*
+
+!INCLUDE "metadata_examples/metadata_examples.mdpp",1

specification/appendix/examples/metadata_examples/adding_new_columns_example.md

@@ -0,0 +1,79 @@
+# Adding New Columns
+
+## Scenario
+
+ACME has decided add additional columns to their FOCUS data export. The new columns are x_awesome_column1, x_awesome_column2, and x_awesome_column3. The provider creates a new schema object to represent the new schema, this schema object has a unique SchemaId. The subsequent data exports that use the new schema include the new schema's id as a reference to their corresponding schema object.
+
+### Supplied Metadata
+
+#### Location for the new schema object:
+
+`/FOCUS/metadata/schemas/schema-23456-abcde-23456-abcde-23456.json`
+
+#### Content for the new schema object:
+
+```json
+ {
+  "SchemaId": "23456-abcde-23456-abcde-23456",
+  "FocusVersion": "1.0",
+  "name": "New Columns",
+  "CreationDate": "2024-02-02T12:01:03.083z",
+  "ColumnDefinition": [
+          {
+                "ColumnName": "BillingAccountId",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "BillingAccountName",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+               "ColumnName": "ChargePeriodStart",
+               "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "ChargePeriodEnd",
+                "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "BilledCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "EffectiveCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "Tags",
+                "DataType": "JSON",
+                "ProviderTagPrefixes": ["awecorp", "ac"]
+          },
+          {
+                "ColumnName": "x_awesome_column1",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "x_awesome_column2",
+                "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "x_awesome_column3",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          }
+      ]
+}
+```
+
+For an example of how ACME ensures the schema metadata reference requirement is met see: [Schema Metadata to FOCUS Data Reference](../schema_metadata_reference_example.md)

specification/appendix/examples/metadata_examples/changing_column_metadata_example.md

@@ -0,0 +1,73 @@
+# Changing a Column's Metadata Example
+
+## Scenario
+
+ACME has decided to change the datatype of column x_awesome_column1 from a string to a number. ACME creates a new schema object with the modification to x_awesome_column2.
+
+### Supplied Metadata
+
+#### Location for the new schema object:
+
+`/FOCUS/metadata/schemas/schema-67891-abcde-67891-abcde-67891.json`
+
+#### Content for the new schema object:
+
+```json
+ {
+  "SchemaId": "67891-abcde-67891-abcde-67891",
+  "FocusVersion": "1.0",
+  "name": "New Columns",
+  "CreationDate": "2024-06-02T12:01:03.083z",
+  "ColumnDefinition": [
+    {
+      "ColumnName": "BillingAccountId",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "BillingAccountName",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+               "ColumnName": "ChargePeriodStart",
+               "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "ChargePeriodEnd",
+                "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "BilledCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "EffectiveCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "Tags",
+                "DataType": "JSON",
+                "ProviderTagPrefixes": ["acme", "ac"]
+          },
+          {
+                "ColumnName": "x_awesome_column1",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "x_awesome_column2",
+                "DataType": "DATETIME"
+          }
+      ]
+}
+```
+
+For an example of how ACME ensures the schema metadata reference requirement is met see: [Schema Metadata to FOCUS Data Reference](schema_metadata_reference_example.md)

specification/appendix/examples/metadata_examples/correcting_schema_errors_example.md

@@ -0,0 +1,73 @@
+# Provider has an error in their schema metadata
+
+## Scenario
+
+ACME has discovered that while their export includes the column x_awesome_column3, the schema metadata does not include this column. In this case, the provider fixes the metadata in existing the schema object and does not need to create a new schema object.  Reference metadata remains the same.
+
+### Supplied Metadata
+
+#### Location of the schema object:
+
+`/FOCUS/metadata/schemas/schema-34567-abcde-34567-abcde-34567.json`
+
+#### Content of the schema object:
+
+```json
+ {
+  "SchemaId": "34567-abcde-34567-abcde-34567",
+  "FocusVersion": "1.0",
+  "name": "New Columns",
+  "CreationDate": "2024-03-02T12:01:03.083z",
+  "ColumnDefinition": [
+    {
+      "ColumnName": "BillingAccountId",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "BillingAccountName",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+               "ColumnName": "ChargePeriodStart",
+               "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "ChargePeriodEnd",
+                "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "BilledCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "EffectiveCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "Tags",
+                "DataType": "JSON",
+                "ProviderTagPrefixes": ["acme", "ac"]
+          },
+          {
+                "ColumnName": "x_awesome_column1",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "x_awesome_column2",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          }
+      ]
+}
+```

specification/appendix/examples/metadata_examples/data_generator_example.md

@@ -0,0 +1,19 @@
+# Data Generator Metadata
+
+## Scenario
+
+Our provider's name is ACME, and they provide a metadata file that includes the name of the entity that is generating the data.
+
+### Supplied Metadata
+
+#### Location of Data Generator Metadata File:
+
+`/FOCUS/metadata/data_generator.json`
+
+#### Content of Data Generator Metadata File:
+
+```json
+{
+    "DataGenerator": "ACME"
+}
+```

specification/appendix/examples/metadata_examples/focus_version_changed_example.md

@@ -0,0 +1,73 @@
+# Provider has an error in their schema metadata
+
+## Scenario
+
+ACME's previous exports used Focus Version 1.0. They are now going to adopt Focus Version 1.1.  It is required that they create a new schema metadata object when using a new FOCUS version regardless of schema changes. In this example, the FOCUS new version adoption doesn't include columns changes. This is to illustrate that FOCUS Version changes are independent of column changes, however, this scenario is unlikely.
+
+### Supplied Metadata
+
+#### Location of the new schema object:
+
+`/FOCUS/metadata/schemas/schema-45678-abcde-45678-abcde-45678.json`
+
+#### Content of the schema object:
+
+```json
+ {
+  "SchemaId": "45678-abcde-45678-abcde-45678",
+  "FocusVersion": "1.1",
+  "name": "Focus Version 1.1 Schema",
+  "CreationDate": "2024-04-02T12:01:03.083z",
+  "ColumnDefinition": [
+    {
+      "ColumnName": "BillingAccountId",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "BillingAccountName",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+               "ColumnName": "ChargePeriodStart",
+               "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "ChargePeriodEnd",
+                "DataType": "DATETIME"
+          },
+          {
+                "ColumnName": "BilledCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "EffectiveCost",
+                "DataType": "DECIMAL",
+                "NumericPrecision": 20,
+                "NumberScale": 10
+          },
+          {
+                "ColumnName": "Tags",
+                "DataType": "JSON",
+                "ProviderTagPrefixes": ["acme", "ac"]
+          },
+          {
+                "ColumnName": "x_awesome_column1",
+                "DataType": "STRING",
+                "StringMaxLength": 64,
+                "StringEncoding": "UTF-8"
+          },
+          {
+                "ColumnName": "x_awesome_column2",
+                "DataType": "DATETIME"
+          }
+      ]
+}
+```
+
+For an example of how ACME ensures the schema metadata reference requirement is met see: [Schema Metadata to FOCUS Data Reference](schema_metadata_reference_example.md)