traits.yaml

openapi: 3.1.0-pre1
info:
  title: API
  version: 1.0.0
components:
  parameters:
    ...
  headers:
    ...
  traits:
      # each traitObject MUST have a parameters array XOR a response headers map
      # + optionally, a summary, description and externalDocs object
      # and a property: global (boolean, default false) to indicate it applies without exception to all operations/responses
      # possibly could be expanded with requestBody, responses and links properties
      # traits are layered in the order they are applied, and local conflicting definitions override those from traits
    version:
      global: true # applies to all pathItems
      parameters:
        - name: version
          in: query
          required: true
          schema:
            type: string
    pagination:
      parameters:
        - $ref: '#/components/parameters/pageNo'
        - $ref: '#/components/parameters/perPage'
      externalDocs:
        url: 'https://megadodopublications.com/api/pagination'
    rateLimiting:
      headers:
        'X-Rate-Limited':
          $ref: '#/components/headers/xRateLimited'
        'X-Requests-Left':
          $ref: '#/components/headers/xRequestsLeft' 
      externalDocs:
        description: 'Find out more about rate limiting'
        url: 'https://megadodopublications.com/api/rate-limiting'
paths:
  /:
    get:
      traits:
        - $ref: '#/components/traits/pagination'
      responses:
        '200':
          description: OK
          traits:
            - $ref: '#/components/traits/rateLimiting'

The idea of using components/overlays or components/updates may be a worthwhile alternative to explore.

IMHO the global flag may be problematic because it modifies a component outside its scope.

https://gist.github.com/MikeRalphson/7ee0624fc1df70c0475717d89a5b6e4b#file-traits-yaml-L17

@ioggstream I can see the potential downside of that approach, but without some way to invoke traits globally, we're not necessarily answering the original requests for this feature.

What about a top-level traits or globalTraits array (containing trait objects or $refs)?

If you mean a globalTraits at the same level of "paths" it seems reasonable.