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

edited to add: since externalDocs is defined separately in the json schema dialect for the Schema Object, externalLinks definitely needs to be defined here as well.

[lornajane]

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

I think for tags we actually did publish it, with appropriate health warnings

[lornajane]

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

Perhaps id or name?

I don't think this is a useful approach, the data here is an array of context resources, they don't have identifiers and they shouldn't be required to have them. Can you say something more about the use cases you have in mind for using Overlays with future versions of OpenAPI? Maybe I didn't understand the request.