openapi: 3.1.0
info:
  title: "Moody's Data Buffet API"
  version: 1.0.0
  description: >-
    The Moody's Analytics Data Buffet API provides programmatic access to
    international and subnational economic, demographic, and financial time
    series data and forecasts. It enables retrieval of individual series or
    baskets of data, supports frequency conversion, mathematical
    transformations, date range filtering, and vintage/versioning selection.
    Code samples are available in C#, Java, Python, and R.
  contact:
    name: "Moody's Analytics"
    url: https://www.economy.com/products/tools/data-buffet
  license:
    name: "Moody's Analytics Terms of Use"
    url: https://www.moodys.com/web/en/us/about/legal/terms-of-use.html
externalDocs:
  description: "Moody's Data Buffet API Documentation"
  url: https://api.economy.com/data/v1/swagger

servers:
- url: https://api.economy.com/data/v1
  description: "Moody's Analytics Data Buffet production server"

tags:
- name: Baskets
  description: Operations for creating and managing collections of series requests
- name: Health
  description: Service health monitoring

- name: Orders
  description: Operations for managing data generation orders from baskets
- name: Reference
  description: Operations for retrieving frequency, vintage, and file type metadata
- name: Search
  description: Operations for searching available datasets and series
- name: Series
  description: Operations for retrieving individual and multi-series time series data
security:
- oauth2: []

paths:
  /oauth2/token:
    post:
      operationId: getAccessToken
      summary: Moody's Obtain an Access Token
      description: >-
        Authenticates using OAuth2 client credentials and returns a bearer
        access token for subsequent API requests.
      tags:
      - Reference
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              - client_id
              - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  description: The OAuth2 grant type. Must be client_credentials.
                client_id:
                  type: string
                  description: The API client ID issued by Moody's Analytics.
                client_secret:
                  type: string
                  description: The API client secret issued by Moody's Analytics.
      responses:
        "200":
          description: Successfully obtained access token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessToken"
        "400":
          description: Invalid grant type or missing credentials
        "401":
          description: Invalid client credentials

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /series:
    get:
      operationId: getSeries
      summary: Moody's Retrieve a Single Time Series
      description: >-
        Returns data for a single economic, demographic, or financial time
        series identified by its mnemonic. Supports frequency conversion,
        mathematical transformations, date range filtering, and vintage
        selection.
      tags:
      - Series
      parameters:
      - $ref: "#/components/parameters/mnemonic"
      - $ref: "#/components/parameters/freq"
      - $ref: "#/components/parameters/trans"
      - $ref: "#/components/parameters/startDate"
      - $ref: "#/components/parameters/endDate"
      - $ref: "#/components/parameters/vintage"
      responses:
        "200":
          description: Successfully retrieved time series data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeriesResponse"
        "400":
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Series mnemonic not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /multi-series:
    post:
      operationId: getMultiSeries
      summary: Moody's Retrieve Multiple Time Series
      description: >-
        Returns data for up to 25 time series in a single request. Each
        series can have individual frequency, transformation, date range,
        and vintage parameters. Useful for efficiently fetching related
        economic indicators together.
      tags:
      - Series
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultiSeriesRequest"
      responses:
        "200":
          description: Successfully retrieved multiple time series
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MultiSeriesResponse"
        "400":
          description: Invalid request or exceeded 25 series limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /baskets:
    get:
      operationId: listBaskets
      summary: Moody's List All Baskets
      description: >-
        Returns a list of all data baskets owned by the authenticated user.
        A basket is a saved collection of series requests that can be
        executed as an order.
      tags:
      - Baskets
      responses:
        "200":
          description: Successfully retrieved basket list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Basket"
        "401":
          description: Unauthorized - invalid or expired token
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createBasket
      summary: Moody's Create a New Basket
      description: >-
        Creates a new data basket with a collection of series requests.
        Baskets can be saved and reused to generate orders for bulk data
        retrieval.
      tags:
      - Baskets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BasketCreate"
      responses:
        "201":
          description: Successfully created basket
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Basket"
        "400":
          description: Invalid basket definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /baskets/{basketId}:
    get:
      operationId: getBasket
      summary: Moody's Retrieve a Specific Basket
      description: >-
        Returns the details of a specific basket including its series
        requests and configuration.
      tags:
      - Baskets
      parameters:
      - $ref: "#/components/parameters/basketId"
      responses:
        "200":
          description: Successfully retrieved basket
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Basket"
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Basket not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateBasket
      summary: Moody's Update an Existing Basket
      description: >-
        Updates the series requests and configuration of an existing basket.
      tags:
      - Baskets
      parameters:
      - $ref: "#/components/parameters/basketId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BasketCreate"
      responses:
        "200":
          description: Successfully updated basket
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Basket"
        "400":
          description: Invalid basket definition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Basket not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteBasket
      summary: Moody's Delete a Basket
      description: >-
        Permanently deletes a basket and its associated series requests.
      tags:
      - Baskets
      parameters:
      - $ref: "#/components/parameters/basketId"
      responses:
        "204":
          description: Successfully deleted basket
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Basket not found

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders:
    get:
      operationId: listOrders
      summary: Moody's List All Orders
      description: >-
        Returns a list of all data generation orders for the authenticated
        user. Orders are created from baskets and produce output files in
        the requested format.
      tags:
      - Orders
      responses:
        "200":
          description: Successfully retrieved order list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Order"
        "401":
          description: Unauthorized - invalid or expired token
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createOrder
      summary: Moody's Create a New Order
      description: >-
        Creates a new data generation order from a basket. The order will
        be processed asynchronously and produce output in the specified
        file format.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrderCreate"
      responses:
        "201":
          description: Successfully created order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          description: Invalid order request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Moody's Retrieve a Specific Order
      description: >-
        Returns the status and details of a specific order, including
        processing status and download URL when complete.
      tags:
      - Orders
      parameters:
      - $ref: "#/components/parameters/orderId"
      responses:
        "200":
          description: Successfully retrieved order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Order not found

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderId}/download:
    get:
      operationId: downloadOrder
      summary: Moody's Download Order Output
      description: >-
        Downloads the output file for a completed order. The file format
        is determined by the fileType specified when creating the order.
      tags:
      - Orders
      parameters:
      - $ref: "#/components/parameters/orderId"
      responses:
        "200":
          description: Successfully downloaded order output
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Order not found or not yet complete

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /search:
    get:
      operationId: searchSeries
      summary: Moody's Search for Available Series
      description: >-
        Searches the Data Buffet repository for available series matching
        the specified criteria. Supports filtering by keyword, geography,
        source, and category.
      tags:
      - Search
      parameters:
      - name: query
        in: query
        description: >-
          Search query string to match against series names, descriptions,
          mnemonics, and metadata.
        required: true
        schema:
          type: string
      - name: geography
        in: query
        description: >-
          Filter results by geographic area code (e.g., US for United
          States, GB for United Kingdom, CN for China).
        required: false
        schema:
          type: string
      - name: source
        in: query
        description: >-
          Filter results by data source identifier (e.g., BLS, BEA, IMF,
          Eurostat).
        required: false
        schema:
          type: string
      - name: category
        in: query
        description: >-
          Filter results by data category (e.g., GDP, Employment,
          Inflation, Housing).
        required: false
        schema:
          type: string
      - name: offset
        in: query
        description: The number of results to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        "200":
          description: Successfully retrieved search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResults"
        "400":
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /frequencies:
    get:
      operationId: listFrequencies
      summary: Moody's List Available Data Frequencies
      description: >-
        Returns a list of all supported data frequencies (e.g., annual,
        quarterly, monthly, weekly, daily) that can be used for frequency
        conversion when retrieving series.
      tags:
      - Reference
      responses:
        "200":
          description: Successfully retrieved frequency list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FrequencyInfo"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vintages:
    get:
      operationId: listVintages
      summary: Moody's List Available Vintages for a Series
      description: >-
        Returns a list of available data vintages (historical revisions)
        for a specific series. Vintages enable access to previous versions
        of data as originally published.
      tags:
      - Reference
      parameters:
      - $ref: "#/components/parameters/mnemonic"
      responses:
        "200":
          description: Successfully retrieved vintage list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Vintage"
        "400":
          description: Invalid mnemonic
        "401":
          description: Unauthorized - invalid or expired token
        "404":
          description: Series mnemonic not found

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /filetypes:
    get:
      operationId: listFileTypes
      summary: Moody's List Supported Output File Types
      description: >-
        Returns a list of supported output file types for order data
        generation (e.g., CSV, Excel, XML, JSON).
      tags:
      - Reference
      responses:
        "200":
          description: Successfully retrieved file type list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileType"
        "401":
          description: Unauthorized - invalid or expired token

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /health:
    get:
      operationId: checkHealth
      summary: Moody's Check Service Health
      description: >-
        Returns the current health status of the Data Buffet API service.
      tags:
      - Health
      security: []
      responses:
        "200":
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
        "503":
          description: Service is unavailable

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth2 client credentials flow for authenticating API requests.
        Obtain client_id and client_secret from your Moody's Analytics
        account.
      flows:
        clientCredentials:
          tokenUrl: https://api.economy.com/data/v1/oauth2/token
          scopes: {}

  parameters:
    mnemonic:
      name: mnemonic
      in: query
      description: >-
        The unique series mnemonic identifier. Mnemonics follow the Data
        Buffet naming convention, e.g., FGDP_US for US GDP or
        EMPLPAY.IUSA for US total nonfarm payrolls.
      required: true
      schema:
        type: string
      examples:
        usGdp:
          summary: US Gross Domestic Product
          value: FGDP_US
        usPayrolls:
          summary: US Total Nonfarm Payrolls
          value: EMPLPAY.IUSA
    freq:
      name: freq
      in: query
      description: >-
        The desired output frequency for the series. When specified,
        frequency conversion is applied. For example, converting quarterly
        GDP to annual.
      required: false
      schema:
        type: string
        enum:
        - A
        - Q
        - M
        - W
        - D
    trans:
      name: trans
      in: query
      description: >-
        The mathematical transformation to apply to the series values.
        Supports common economic transformations.
      required: false
      schema:
        type: string
        enum:
        - Level
        - SimpleDifference
        - PercentChange
        - AnnualizedGrowth
        - YearOverYearPercentChange
        - CompoundAnnualGrowthRate
    startDate:
      name: startDate
      in: query
      description: >-
        The start date for the data range in YYYY-MM-DD format. If omitted,
        returns data from the beginning of the series.
      required: false
      schema:
        type: string
        format: date
    endDate:
      name: endDate
      in: query
      description: >-
        The end date for the data range in YYYY-MM-DD format. If omitted,
        returns data through the latest available observation or forecast.
      required: false
      schema:
        type: string
        format: date
    vintage:
      name: vintage
      in: query
      description: >-
        The vintage date for accessing historical data revisions in
        YYYY-MM-DD format. If omitted, returns the latest vintage.
      required: false
      schema:
        type: string
        format: date
    basketId:
      name: basketId
      in: path
      description: The unique identifier of the basket.
      required: true
      schema:
        type: string
    orderId:
      name: orderId
      in: path
      description: The unique identifier of the order.
      required: true
      schema:
        type: string

  schemas:
    AccessToken:
      type: object
      description: OAuth2 access token response.
      required:
      - access_token
      - token_type
      - expires_in
      properties:
        access_token:
          type: string
          description: The bearer access token for authenticating API requests.
          example: example_value
        token_type:
          type: string
          description: The type of token issued. Always "Bearer".
          enum:
          - Bearer
          example: Bearer
        expires_in:
          type: integer
          description: The number of seconds until the access token expires.

          example: 10
    SeriesResponse:
      type: object
      description: >-
        Response containing a single time series with metadata and
        observations.
      required:
      - mnemonic
      - description
      - frequency
      - data
      properties:
        mnemonic:
          type: string
          description: The unique series mnemonic identifier.
          example: example_value
        description:
          type: string
          description: Human-readable description of the series.
          example: A sample description.
        frequency:
          type: string
          description: The frequency of the returned data.
          enum:
          - Annual
          - Quarterly
          - Monthly
          - Weekly
          - Daily
          example: Annual
        source:
          type: string
          description: The original data source (e.g., BLS, BEA, IMF).
          example: example_value
        geography:
          type: string
          description: The geographic area the series covers.
          example: example_value
        units:
          type: string
          description: >-
            The unit of measurement for the series values (e.g., Billions
            of Chained 2017 Dollars, Thousands of Persons, Index).
          example: example_value
        transformation:
          type: string
          description: The transformation applied to the data, if any.
          example: example_value
        startDate:
          type: string
          format: date
          description: The start date of the returned data range.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: The end date of the returned data range.
          example: '2026-01-15'
        vintage:
          type: string
          format: date
          description: The vintage date of the returned data.
          example: '2026-01-15'
        lastUpdated:
          type: string
          format: date-time
          description: When the series was last updated in the repository.
          example: '2026-01-15T10:30:00Z'
        isForecast:
          type: boolean
          description: >-
            Whether the series contains forecast data from Moody's
            Analytics models.
          example: true
        data:
          type: array
          description: >-
            Array of date-value pairs representing the time series
            observations and/or forecasts.
          items:
            $ref: "#/components/schemas/Observation"

          example: []
    Observation:
      type: object
      description: A single time series observation or forecast data point.
      required:
      - date
      - value
      properties:
        date:
          type: string
          format: date
          description: >-
            The observation date in YYYY-MM-DD format. For frequencies
            coarser than daily, represents the period start date.
          example: '2026-01-15'
        value:
          type:
          - number
          - "null"
          description: >-
            The observation value. Null indicates missing or unavailable
            data for this period.
          example: example_value
        status:
          type: string
          description: >-
            Status indicator for the data point.
          enum:
          - History
          - Forecast
          - Preliminary

          example: History
    MultiSeriesRequest:
      type: object
      description: Request body for retrieving multiple series simultaneously.
      required:
      - series
      properties:
        series:
          type: array
          description: >-
            Array of series requests. Maximum 25 series per request.
          maxItems: 25
          items:
            $ref: "#/components/schemas/SeriesRequest"

          example: []
    SeriesRequest:
      type: object
      description: A single series request within a multi-series call.
      required:
      - mnemonic
      properties:
        mnemonic:
          type: string
          description: The unique series mnemonic identifier.
          example: example_value
        freq:
          type: string
          description: Desired output frequency.
          enum:
          - A
          - Q
          - M
          - W
          - D
          example: A
        trans:
          type: string
          description: Mathematical transformation to apply.
          enum:
          - Level
          - SimpleDifference
          - PercentChange
          - AnnualizedGrowth
          - YearOverYearPercentChange
          - CompoundAnnualGrowthRate
          example: Level
        startDate:
          type: string
          format: date
          description: Start date for the data range.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: End date for the data range.
          example: '2026-01-15'
        vintage:
          type: string
          format: date
          description: Vintage date for historical data revisions.

          example: '2026-01-15'
    MultiSeriesResponse:
      type: object
      description: Response containing multiple time series.
      required:
      - series
      properties:
        series:
          type: array
          description: Array of time series responses.
          items:
            $ref: "#/components/schemas/SeriesResponse"

          example: []
    Basket:
      type: object
      description: >-
        A saved collection of series requests that can be executed as an
        order for bulk data retrieval.
      required:
      - basketId
      - name
      - series
      properties:
        basketId:
          type: string
          description: Unique identifier for the basket.
          example: '500123'
        name:
          type: string
          description: User-defined name for the basket.
          example: Example Title
        description:
          type: string
          description: Optional description of the basket contents and purpose.
          example: A sample description.
        series:
          type: array
          description: The series requests contained in the basket.
          items:
            $ref: "#/components/schemas/SeriesRequest"
          example: []
        createdAt:
          type: string
          format: date-time
          description: When the basket was created.
          example: '2026-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the basket was last modified.

          example: '2026-01-15T10:30:00Z'
    BasketCreate:
      type: object
      description: Request body for creating or updating a basket.
      required:
      - name
      - series
      properties:
        name:
          type: string
          description: User-defined name for the basket.
          example: Example Title
        description:
          type: string
          description: Optional description of the basket.
          example: A sample description.
        series:
          type: array
          description: The series requests to include in the basket.
          items:
            $ref: "#/components/schemas/SeriesRequest"

          example: []
    Order:
      type: object
      description: >-
        A data generation order created from a basket. Orders are processed
        asynchronously and produce downloadable output files.
      required:
      - orderId
      - basketId
      - status
      properties:
        orderId:
          type: string
          description: Unique identifier for the order.
          example: '500123'
        basketId:
          type: string
          description: The basket from which the order was generated.
          example: '500123'
        status:
          type: string
          description: Current processing status of the order.
          enum:
          - Pending
          - Processing
          - Complete
          - Failed
          example: Pending
        fileType:
          type: string
          description: The output file format for the order.
          example: example_value
        createdAt:
          type: string
          format: date-time
          description: When the order was created.
          example: '2026-01-15T10:30:00Z'
        completedAt:
          type: string
          format: date-time
          description: When the order processing completed.
          example: '2026-01-15T10:30:00Z'
        downloadUrl:
          type: string
          format: uri
          description: >-
            URL to download the order output. Available only when status
            is Complete.
          example: https://www.example.com
        errorMessage:
          type: string
          description: >-
            Error description if the order failed. Present only when
            status is Failed.

          example: example_value
    OrderCreate:
      type: object
      description: Request body for creating a new order.
      required:
      - basketId
      - fileType
      properties:
        basketId:
          type: string
          description: The basket to generate the order from.
          example: '500123'
        fileType:
          type: string
          description: >-
            The desired output file format. Use the /filetypes endpoint
            to retrieve supported formats.

          example: example_value
    SearchResults:
      type: object
      description: Paginated search results for series queries.
      required:
      - totalCount
      - results
      properties:
        totalCount:
          type: integer
          description: Total number of matching series across all pages.
          example: 10
        offset:
          type: integer
          description: The current pagination offset.
          example: 10
        limit:
          type: integer
          description: The maximum results per page.
          example: 10
        results:
          type: array
          description: Array of matching series metadata.
          items:
            $ref: "#/components/schemas/SeriesSummary"

          example: []
    SeriesSummary:
      type: object
      description: Summary metadata for a series returned in search results.
      required:
      - mnemonic
      - description
      properties:
        mnemonic:
          type: string
          description: The unique series mnemonic identifier.
          example: example_value
        description:
          type: string
          description: Human-readable description of the series.
          example: A sample description.
        frequency:
          type: string
          description: Native frequency of the series.
          example: example_value
        source:
          type: string
          description: The original data source.
          example: example_value
        geography:
          type: string
          description: Geographic area covered by the series.
          example: example_value
        category:
          type: string
          description: Data category classification.
          example: example_value
        startDate:
          type: string
          format: date
          description: Earliest available observation date.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: Latest available observation or forecast date.
          example: '2026-01-15'
        hasForecast:
          type: boolean
          description: >-
            Whether the series includes forecast data from Moody's
            Analytics models.

          example: true
    FrequencyInfo:
      type: object
      description: Metadata about a supported data frequency.
      required:
      - code
      - name
      properties:
        code:
          type: string
          description: >-
            Single-character frequency code used in API parameters.
          enum:
          - A
          - Q
          - M
          - W
          - D
          example: A
        name:
          type: string
          description: Human-readable frequency name.
          enum:
          - Annual
          - Quarterly
          - Monthly
          - Weekly
          - Daily
          example: Annual
        description:
          type: string
          description: Description of the frequency and its typical use cases.

          example: A sample description.
    Vintage:
      type: object
      description: >-
        Metadata about a data vintage representing a historical revision
        of a series.
      required:
      - vintageDate
      properties:
        vintageDate:
          type: string
          format: date
          description: The date this vintage was published.
          example: '2026-01-15'
        description:
          type: string
          description: Description of the vintage release context.

          example: A sample description.
    FileType:
      type: object
      description: Metadata about a supported output file type.
      required:
      - code
      - name
      properties:
        code:
          type: string
          description: File type code used in order creation.
          example: example_value
        name:
          type: string
          description: Human-readable file type name.
          example: Example Title
        extension:
          type: string
          description: File extension (e.g., csv, xlsx, json, xml).
          example: example_value
        description:
          type: string
          description: Description of the file format.

          example: A sample description.
    HealthStatus:
      type: object
      description: Service health status information.
      required:
      - status
      properties:
        status:
          type: string
          description: Overall service health status.
          enum:
          - Healthy
          - Degraded
          - Unavailable
          example: Healthy
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the health check.
          example: '2026-01-15T10:30:00Z'
        version:
          type: string
          description: Current API version.

          example: example_value
    Error:
      type: object
      description: Standard error response.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: example_value
        message:
          type: string
          description: Human-readable error message.
          example: example_value
        details:
          type: string
          description: Additional details about the error.
          example: example_value