FinOps Foundation Schema Metadata API

openapi: 3.2.0
info:
  title: FinOps Foundation FOCUS Cost and Usage Schema Metadata API
  description: An API modeled on the FinOps Open Cost and Usage Specification (FOCUS) v1.3, which defines a standard schema for cloud, SaaS, and other technology billing data.
  version: 1.3.0
  contact:
    name: FinOps Foundation
    url: https://www.finops.org/
  license:
    name: Community Specification License 1.0
    url: https://github.com/FinOps-Open-Cost-and-Usage-Spec/FOCUS_Spec/blob/main/LICENSE
  x-focus-version: '1.3'
servers:
- url: https://api.example.com/focus/v1
  description: Example FOCUS-compliant API server
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Schema Metadata
  description: Endpoints for retrieving metadata about the FOCUS dataset schema, including column definitions, data types, and version information.
paths:
  /schema:
    get:
      operationId: getSchemaMetadata
      summary: FinOps Foundation Get FOCUS schema metadata
      description: Retrieves metadata about the FOCUS dataset schema, including column definitions, data types, FOCUS version, and data generator version information.
      tags:
      - Schema Metadata
      responses:
        '200':
          description: FOCUS schema metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaMetadata'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ColumnDefinition:
      type: object
      properties:
        columnName:
          type: string
          description: The name of the column.
        dataType:
          type: string
          enum:
          - String
          - Number
          - DateTime
          - JSON
          description: The data type of the column.
        requirement:
          type: string
          enum:
          - Must
          - Recommended
          - Optional
          description: The requirement level of the column per the FOCUS specification.
        nullable:
          type: boolean
          description: Whether the column can contain null values.
        description:
          type: string
          description: A description of the column and its purpose.
        category:
          type: string
          enum:
          - Dimension
          - Metric
          description: Whether this column is a dimension or a metric.
      required:
      - columnName
      - dataType
      - requirement
      - nullable
    SchemaMetadata:
      type: object
      description: Metadata about the FOCUS dataset schema, supporting communication of important attributes about the data including column names, data types, FOCUS version, and data generator version.
      properties:
        focusVersion:
          type: string
          description: The version of the FOCUS specification the data conforms to.
          example: '1.3'
        dataGeneratorName:
          type: string
          description: The name of the data generator producing the FOCUS data.
        dataGeneratorVersion:
          type: string
          description: The version of the data generator.
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ColumnDefinition'
          description: List of column definitions in the FOCUS dataset.
        datasets:
          type: array
          items:
            type: string
          description: The datasets available from this data generator.
          example:
          - CostAndUsage
          - ContractCommitment
      required:
      - focusVersion
      - columns
    Error:
      type: object
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.
        details:
          type: string
          nullable: true
          description: Additional details about the error.
      required:
      - code
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication for FOCUS API access.
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication for FOCUS API access.
externalDocs:
  description: FOCUS Specification v1.3
  url: https://focus.finops.org/focus-specification/v1-3/