Introduce External Links array and deprecate External Documentation

[lornajane]

Make the changes agreed in the accepted proposal https://github.com/OAI/OpenAPI-Specification/blob/main/proposals/2026-08-01-Docs-Links.md

Feedback very welcome on any of the wording/formatting or anything else that could make this better!

• schema changes are needed for this pull request but not done yet

[miqui]

looks good @lornajane

I can't wait to see something like this:

openapi: 3.3.0
info:
  title: Flights API
  version: 1.0.0

# Root-level: array replaces the old single externalDocs object
externalLinks:
  - summary: Developer portal
    description: Guides, tutorials, and onboarding for the Flights API
    url: https://example.com/docs
    kind: documentation
  - summary: API reference
    description: Interactive API documentation
    url: https://example.com/api-docs
    kind: api-docs
  - summary: Status page
    url: https://status.example.com
    kind: status

tags:
  - name: flights
    summary: Search, book, and manage flights
    externalLinks:
      - summary: Booking flow guide
        url: https://example.com/docs/flights
        kind: documentation

paths:
  /flights:
    get:
      operationId: searchFlights
      summary: Search available flights
      externalLinks:
        - summary: Pagination guide
          url: https://example.com/docs/pagination
          kind: documentation
        - summary: Endpoint changelog
          url: https://example.com/changelog#searchFlights
          kind: changelog
      parameters:
        - name: origin
          in: query
          required: true
          schema:
            type: string
          examples:
            jfk:
              value: JFK
        - name: destination
          in: query
          required: true
          schema:
            type: string
          examples:
            lax:
              value: LAX
        - name: departureDate
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A list of matching flights
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flight'

components:
  schemas:
    Flight:
      type: object
      externalLinks:
        - summary: Flight data model docs
          url: https://example.com/docs/models/flight
          kind: documentation
      properties:
        flightNumber:
          type: string
          examples:
            - "AA100"
        origin:
          type: string
          examples:
            - JFK
        destination:
          type: string
          examples:
            - LAX
        departureTime:
          type: string
          format: date-time
        arrivalTime:
          type: string
          format: date-time
        status:
          type: string
          enum: [scheduled, delayed, cancelled, departed, arrived]
          ```

[miqui]

heads up - i am going to add this feature to the lifecycle SAF.