[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.

[lornajane]

Followup from the review last week.

[baywet]

@lornajane should we add a suppression for markdown lint for the registry link that's not published yet?

[smikulcik]

Can we add a field for a machine readable unique identifier?

Perhaps id or name?

As we start using overlays for more parts of OpenAPI, it would be great if we could uniquely identify array items

target: $.externalLinks[?(@.name=="api_reference")]

Compared to array index identifiers

target: $.externalLinks[1]

name: api_reference # <-- New field
summary: API reference
description: Interactive API documentation
url: https://example.com/api-docs
kind: api-docs

While I'd prefer to have it be required, optional is workable with validators

[karenetheridge]

Should this be "Link", singular? The externalLinks property is an array, where each item is a single "external link".

(I am not enumerating all the places where this wording would need to be changed, both in visible text and in hyperlink names.)

[karenetheridge]

I have prepared a commit which adds this object to the appropriate places in the schema, along with some passing and failing tests, which could be added to this branch or PR'd separately.

[karenetheridge]

There is an example above of adding externalLinks to a schema. If this is intentional, perhaps this should be added to the OpenAPI JSON Schema vocabulary (i.e. a new keyword at https://spec.openapis.org/oas/latest#schema-object).