FOCUS Cost and Usage Record

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/finops-foundation/refs/heads/main/json-schema/finops-foundation-cost-and-usage-record-schema.json",
  "title": "FOCUS Cost and Usage Record",
  "description": "A single cost and usage record conforming to the FinOps Open Cost and Usage Specification (FOCUS) v1.3. Contains dimensions (qualitative values for categorization and filtering) and metrics (quantitative values for measurement).",
  "type": "object",
  "properties": {
    "AvailabilityZone": {
      "type": ["string", "null"],
      "description": "A provider-assigned identifier for a physically separated and isolated area within a region that provides high availability and fault tolerance."
    },
    "BilledCost": {
      "type": "number",
      "description": "A charge serving as the basis for invoicing, inclusive of the impacts of all reduced rates and discounts while excluding the amortization of relevant purchases."
    },
    "BillingAccountId": {
      "type": "string",
      "description": "The unique identifier for a billing account."
    },
    "BillingAccountName": {
      "type": ["string", "null"],
      "description": "The display name assigned to a billing account."
    },
    "BillingCurrency": {
      "type": "string",
      "description": "The currency that a charge was billed in. Represented as a three-letter ISO 4217 currency code.",
      "pattern": "^[A-Z]{3}$"
    },
    "BillingPeriodEnd": {
      "type": "string",
      "format": "date-time",
      "description": "The exclusive end date and time of the billing period."
    },
    "BillingPeriodStart": {
      "type": "string",
      "format": "date-time",
      "description": "The inclusive start date and time of the billing period."
    },
    "CapacityReservationId": {
      "type": ["string", "null"],
      "description": "The identifier assigned to a capacity reservation by the provider. Introduced in FOCUS v1.3."
    },
    "ChargeCategory": {
      "type": "string",
      "enum": ["Usage", "Purchase", "Tax", "Credit", "Adjustment"],
      "description": "The highest-level classification of a charge based on the nature of how it is billed."
    },
    "ChargeClass": {
      "type": ["string", "null"],
      "enum": ["Correction", null],
      "description": "Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period."
    },
    "ChargeDescription": {
      "type": ["string", "null"],
      "description": "A self-contained summary of the charge's purpose and price."
    },
    "ChargeFrequency": {
      "type": "string",
      "enum": ["One-Time", "Recurring", "Usage-Based"],
      "description": "Indicates how often a charge will occur."
    },
    "ChargePeriodEnd": {
      "type": "string",
      "format": "date-time",
      "description": "The exclusive end date and time of a charge period."
    },
    "ChargePeriodStart": {
      "type": "string",
      "format": "date-time",
      "description": "The inclusive start date and time of a charge period."
    },
    "CommitmentDiscountCategory": {
      "type": ["string", "null"],
      "enum": ["Spend", "Usage", null],
      "description": "Indicates whether the commitment discount is based on usage quantity or cost."
    },
    "CommitmentDiscountId": {
      "type": ["string", "null"],
      "description": "The identifier assigned to a commitment discount by the provider."
    },
    "CommitmentDiscountName": {
      "type": ["string", "null"],
      "description": "The display name assigned to a commitment discount."
    },
    "CommitmentDiscountQuantity": {
      "type": ["number", "null"],
      "description": "The amount of a commitment discount purchased or accounted for in commitment discount-related rows."
    },
    "CommitmentDiscountStatus": {
      "type": ["string", "null"],
      "enum": ["Used", "Unused", null],
      "description": "Indicates whether the charge corresponds to the consumption of a commitment discount or the unused portion."
    },
    "CommitmentDiscountType": {
      "type": ["string", "null"],
      "description": "A provider-assigned label describing the type of commitment discount (e.g., Reserved Instance, Savings Plan)."
    },
    "CommitmentDiscountUnit": {
      "type": ["string", "null"],
      "description": "The provider-specified measurement unit for the commitment discount quantity."
    },
    "ConsumedQuantity": {
      "type": ["number", "null"],
      "description": "The volume of a given resource or service used, based on the consumed unit."
    },
    "ConsumedUnit": {
      "type": ["string", "null"],
      "description": "The provider-specified measurement unit indicating how a resource or service was consumed."
    },
    "ContractedCost": {
      "type": "number",
      "description": "The cost calculated by multiplying contracted unit price and the corresponding pricing quantity."
    },
    "ContractedUnitPrice": {
      "type": ["number", "null"],
      "description": "The agreed-upon unit price for a single pricing unit of the associated resource or service."
    },
    "EffectiveCost": {
      "type": "number",
      "description": "The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant prepaid purchases."
    },
    "InvoiceIssuerName": {
      "type": "string",
      "description": "The name of the entity responsible for invoicing for the resources or services consumed."
    },
    "ListCost": {
      "type": "number",
      "description": "The cost calculated by multiplying list unit price and the corresponding pricing quantity."
    },
    "ListUnitPrice": {
      "type": ["number", "null"],
      "description": "The suggested provider-published unit price for a single pricing unit of the associated resource or service."
    },
    "PricingCategory": {
      "type": ["string", "null"],
      "enum": ["On-Demand", "Commitment-Based", "Dynamic", "Other", null],
      "description": "Describes the pricing model used for a charge at the time of use or purchase."
    },
    "PricingQuantity": {
      "type": ["number", "null"],
      "description": "The volume of a given resource or service used or purchased, based on the pricing unit."
    },
    "PricingUnit": {
      "type": ["string", "null"],
      "description": "The provider-specified measurement unit for determining unit prices and pricing quantities."
    },
    "ProviderName": {
      "type": "string",
      "description": "The name of the entity that made the resource or service available for purchase."
    },
    "PublisherName": {
      "type": ["string", "null"],
      "description": "The name of the entity that produced the resource or service that was purchased."
    },
    "Region": {
      "type": ["string", "null"],
      "description": "An isolated geographic area where a resource is provisioned in or a service is provided from."
    },
    "ResourceId": {
      "type": ["string", "null"],
      "description": "The unique identifier assigned to a resource by the provider."
    },
    "ResourceName": {
      "type": ["string", "null"],
      "description": "The display name assigned to a resource."
    },
    "ResourceType": {
      "type": ["string", "null"],
      "description": "The type of resource the charge applies to."
    },
    "ServiceCategory": {
      "type": "string",
      "description": "The highest-level classification of a service based on the core function of the service (e.g., Compute, Storage, Networking, Database)."
    },
    "ServiceName": {
      "type": "string",
      "description": "The display name of the service that was purchased."
    },
    "ServiceSubcategory": {
      "type": ["string", "null"],
      "description": "A secondary classification of a service, providing further detail beyond ServiceCategory."
    },
    "SkuId": {
      "type": ["string", "null"],
      "description": "The unique identifier for the SKU that was used or purchased."
    },
    "SkuPriceId": {
      "type": ["string", "null"],
      "description": "The unique identifier for the SKU inclusive of all pricing variations such as tiering and discounts."
    },
    "SubAccountId": {
      "type": ["string", "null"],
      "description": "The identifier assigned to a grouping of resources or services, often used to manage access and/or cost."
    },
    "SubAccountName": {
      "type": ["string", "null"],
      "description": "The display name assigned to a sub account."
    },
    "Tags": {
      "type": ["object", "null"],
      "additionalProperties": {
        "type": "string"
      },
      "description": "A set of key-value pairs applied to a resource. Tags are commonly used for cost allocation, access control, and automation."
    },
    "x_SplitCostAllocationMethod": {
      "type": ["string", "null"],
      "description": "The method used by the data generator for split cost allocation across workloads. Introduced in FOCUS v1.3."
    },
    "x_SplitCostAllocationPercentage": {
      "type": ["number", "null"],
      "description": "The percentage of the cost allocated to this record via split cost allocation. Introduced in FOCUS v1.3."
    }
  },
  "required": [
    "BilledCost",
    "BillingAccountId",
    "BillingCurrency",
    "BillingPeriodEnd",
    "BillingPeriodStart",
    "ChargeCategory",
    "ChargeFrequency",
    "ChargePeriodEnd",
    "ChargePeriodStart",
    "ContractedCost",
    "EffectiveCost",
    "InvoiceIssuerName",
    "ListCost",
    "ProviderName",
    "ServiceCategory",
    "ServiceName"
  ],
  "additionalProperties": true
}