3.1.2 Allocated Method Details

Allocated Method Details provides information about how resources are allocated when usage records are split to support cost allocation requirements.

Allocated Method Details consists of a valid JSON object which contains an array consisting of key-value objects describing the one or more factors that determined the split cost allocation. Each object consists of FOCUS-defined keys but can be extended to provide additional details about the allocation.

The FOCUS-defined properties are:

• Allocated Ratio: The ratio of a charge that this allocation represents.
• Usage Unit: Unit being measured used to calculate this allocation.
• Usage Quantity: The quantity of units used denominated by the defined usage unit.

In addition to these, a data generator may include one or more custom properties, also denoted as key-value pairs.

3.1.2.1.1 Column Requirements

The AllocatedMethodDetails column adheres to the following requirements:

• AllocatedMethodDetails SHOULD be present in a Cost and Usage FOCUS dataset when the data generator supports Data Generator-Calculated Split Cost Allocation.
• AllocatedMethodDetails MUST be of type String.
• AllocatedMethodDetails MUST conform to StringHandling requirements.
• AllocatedMethodDetails MUST conform to JsonObjectFormat requirements.
• AllocatedMethodDetails nullability is defined as follows:
  • AllocatedMethodDetails MUST be null when a charge is not related to a data generator-calculated split cost allocation.
  • AllocatedMethodDetails SHOULD NOT be null when a charge is related to a data generator-calculated split cost allocation.

3.1.2.1.2 Object Schema Requirements

Allocated Method Details consists of a valid JSON object which contains an array of key-value objects describing the one or more factors (allocation properties) that determined the split cost allocation. Each object consists of FOCUS-defined keys but can be extended to provide additional details about the allocation.

When AllocatedMethodDetails is not null, the JsonObjectFormat for AllocatedMethodDetails adheres to the following requirements:

• AllocatedMethodDetails MUST have a top-level key "Elements" which contains an array.
• Each item in "Elements" MUST be an object.
  • Objects inside "Elements" MUST conform to KeyValueFormat requirements.
    • FOCUS-defined allocation properties adhere to the following additional requirements:
      • Allocation property key MUST match the spelling and casing specified for the FOCUS-defined property.
      • Allocation property value MUST be of the type specified for that property.
      • Allocation properties MUST adhere to additional normative requirements specific to that property.
    • Data generator-defined allocation properties MAY be included in "Elements".
      • Allocation property keys MUST begin with the string "x_" unless it is a FOCUS-defined allocation property.
• AllocatedMethodDetails root object MAY contain additional data generator-defined items, in addition to "Elements".

3.1.2.1.3 Content Requirements

The following keys are used for allocation properties to facilitate querying data across allocations and across data generators. Focus-defined keys will appear in the list below and data generator-defined keys will be prefixed with "x_" to make them easy to identify as well as prevent collisions.

Allocated Ratio

Allocated Ratio communicates the percentage of the Origin Charge that this Allocated Charge derived from the corresponding Allocated Method Id and Usage Unit property.

The "AllocatedRatio" property adheres to the following requirements:

• "AllocatedRatio" MUST be included inside each "Elements" object.
• Values for "AllocatedRatio" MUST be a decimal value compatible with NumericFormat representing the allocated charge's percentage of the origin charge.
• Values for all "AllocatedRatio" properties across all allocated charges related to a single origin charge MUST sum up to 1 (100%).

Usage Unit

Usage Unit communicates the aspect of the documented Allocation Method Id being used to calculate the Allocated Ratio property and what is being measured by Usage Quantity property.

The "UsageUnit" property adheres to the following requirements:

• "UsageUnit" MUST be included inside an "Elements" object if "UsageQuantity" allocation property is included in that "Elements" object, otherwise "UsageUnit" MAY be included in each "Elements" object.
• Values for "UsageUnit" MUST capture the unit or component of data generator's documented AllocationMethod that was used to determine the "AllocatedRatio" value.
• Values for "UsageUnit" SHOULD conform to UnitFormat requirements.

Usage Quantity

Usage Quantity communicates the volume that was consumed or used, denominated in the Usage Unit property value.

The "UsageQuantity" property adheres to the following requirements:

• "UsageQuantity" MAY be included inside an "Elements" object when that "Elements" object contains a "UsageUnit" allocation property.
• Values for "UsageQuantity" MUST be compatible with NumericFormat.
• Values for "UsageQuantity" SHOULD capture the quantity or volume of the "UsageUnit" measured by the data generator that was used to determine the "AllocatedRatio" value.

3.1.2.2.1 Array of Objects

The parent array is called Elements and contains one or more objects which communicate information about how an allocated record was calculated.

3.1.2.2.2 Object Entries

The Elements array contains one or more objects, each of which contains the following entries:

3.1.2.2.3 Example

{
  "Elements" : [ {
    "AllocatedRatio" : 0.05,
    "UsageUnit" : "CPU",
    "UsageQuantity" : 0.5
  }, {
    "AllocatedRatio" : 0.1,
    "UsageUnit" : "Memory",
    "UsageQuantity" : 4
  } ]
}

3.1.2.2.4 JSON Type Definition

{
  "properties": {
    "Elements": {
      "elements": {
        "properties": {
          "AllocatedRatio": { "type": "float64" }
        },
        "optionalProperties": {
          "UsageUnit": { "type": "string" },
          "UsageQuantity": { "type": "float64" }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

NOTE: The above JSON Type Definition (JTD) is an approximation of the expected contents of this column, but it should not be considered normative because it cannot accurately describe the normative requirements (above) for AllocatedMethodDetails. Where there are discrepancies, deference will be given to the normative requirements. For example, NumericFormat allows for multiple numeric data types and precisions, but JTD requires both to be specified; other numeric data types and precisions allowable under NumericFormat are considered valid.

The JSON samples in the scenarios below each represent a single allocated record out of the multiple records derived from an origin record for that scenario. The sum AllocatedRatio will add up to 1 (100%) across all allocated records for an origin record, with the AllocatedRatio (or sum of AllocatedRatio) representing the allocated record's portion of the overall origin record.

3.1.2.3.1 Scenario 1: Single "UsageUnit" value used for allocation

When only a single "UsageUnit" is used to calculate the allocation.

{
  "Elements" : [ {
    "AllocatedRatio" : 0.1,
    "UsageUnit" : "Hours",
    "UsageQuantity" : 300
    }
  ]
}

3.1.2.3.2 Scenario 2: Multiple "UsageUnit" values used for allocation

When multiple "UsageUnit" values are used to calculate the allocation, another object is added to the "Elements" collection.

{
  "Elements": [
    {
      "AllocatedRatio": 0.05,
      "UsageUnit": "CPU",
      "UsageQuantity": 0.5
    },
    {
      "AllocatedRatio": 0.1,
      "UsageUnit": "Memory",
      "UsageQuantity": 4
    }
  ]
}

3.1.2.3.3 Scenario 3: Data generator omits keys that are not required

This data generator does not wish to supply the "UsageUnit" or "UsageQuantity" keys but still provides cost allocation with some additional allocation method details. In this case, "UsageUnit" and "UsageQuantity" are omitted, and only the "AllocatedRatio" is supplied.

{
  "Elements" : [ {
    "AllocatedRatio" : 0.45
    }
  ]
}

3.1.2.3.4 Scenario 4: Additional non-FOCUS specified properties

A data generator can add additional properties if they feel more context is helpful or necessary to the practitioner. In this scenario, the data generator is supplying additional context that shows only 0.5 of a unit was used. However, since 1 unit was requested by the service this allocation represents, the allocation is being charged at 1 regardless.

{
  "Elements": [
    {
      "AllocatedRatio": 0.6,
      "UsageUnit": "vCPU",
      "UsageQuantity": 1,
      "x_ReservedVCPU": 1,
      "x_UsedVCPU": 0.5,
      "x_AllocatedVCPU": 1
    }
  ]
}

A set of properties describing how resources are allocated in data generator-defined split cost allocation.