openapi: 3.1.0
info:
  title: FinOps Foundation FOCUS Cost and Usage Contract Commitments 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. FOCUS normalizes billing datasets across providers to reduce complexity for FinOps practitioners. This specification models the Cost and Usage dataset and the Contract Commitment dataset defined by the FOCUS standard, enabling programmatic access to FOCUS-compliant billing data. The FOCUS specification is maintained by the FinOps Foundation under the Linux Foundation.
  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
    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
    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
  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/