Overlays Meeting (2025-11-04)

[github-actions[bot]]

This discussion is about a meeting of the OpenAPI Overlays group. We meet on alternate Tuesdays at 08:00 Pacific time, and this is a public meeting.

Meeting link: https://zoom-lfx.platform.linuxfoundation.org/meeting/99628896838?password=f3ff9796-d6a0-4749-b39e-93dc7eafe7cd

This meeting is covered by the OpenAPI Initiative Code of Conduct.

Add comments to this discussion to add items to the agenda for the meeting.

[baywet]

Adding this to the agenda:

• Adds a copy action #150
• feat: adds information about overlay and comments in descriptions #213
• fix: typo in identifier #214
• fix/ref rfc 9535 #215
• fix: adds clarification regarding multi-selection #212

[ralfhandl]

• Explicit definition of how to recursively merge objects #216
• 1.1: reference latest JSON RFC #220

[lornajane]

Project governance: Do we inherit the same committers as the OpenAPI specification? And the same requirements such as two reviews? Open questions (and there should be more questions in the same vein!)

[ralfhandl]

Two reviews:

• The OpenAPI specification is even stricter and requires two approvals from TSC members for specification changes.
• I don't think the special role of the TSC applies here. It also doesn't apply to the Arazzo specification.
• Two approvals from anyone with write access should be enough.
• It might even suffice to have one approval for PRs opened by repo maintainers because that means that two maintainers agree on the change.
• The Arazzo team requires two maintainer approvals for spec changes and adds a „cooldown period“ of five days after the second approval before merging a spec change.

[baywet]

Recaping some of the talking points:

• no strict rules for any of that defined at the "initiative level" (numbers of approvers, who gets to be an approver, etc...)
• we should probably removing the OAI maintainers as a cleanup/separation of concerns thing.
• everyone seems to be in favour of having 2 reviewers for spec changes, only one for other kinds of changes.
• @lornajane performed some of the permissions updates live on the call.
• @ralfhandl is proposing that either TSC or maintainers could count for spec approvals, @lornajane that only maintainers count.
• I brought the lack of clearly defined veto process, the implicit responsibility is for people approving to take into account that somebody disagrees and all work together to get out of a "potential veto situation".

[baywet]

added:

• Update CODEOWNERS to remove the tsc team #221

[baywet]

We should "manually enforce" the 2 reviewer rules for spec changes since GitHub doesn't allow us to enforce the cardinality by path.

[baywet]

We should update the contributing guidelines to document what was just discussed.
Basically the same as OpenAPI Specification but with the team we talked about (maintainers)

[smikulcik]

I'd like to add a discussion around using overlays for features - especially in the enterprise use case

• Sharing overlay documents as the featureset to customers
• Building updated OpenAPI documents from "stacks" of overlays from historical "feature"
• etc.

[baywet]

Thank you for suggesting this point. We briefly discussed this on the call. There's a general consensus that it's probably easier for consumers to share the updated OpenAPI description instead of sharing the original description + a stack of overlay.
Some reasons for that: Shipping layers now requires your consumers to understand overlays, have access to all the pieces, apply them in the right order, etc...
The main counter point/benefit of publishing the overlay documents would be to allow the consumers to see the set of changes being apply (and potentially review them).

Hopefully this provides enough context to answer your question, if not, please add a new point to the next agenda (and come discuss it with us :) )

[baywet]

Point added during the meeting: @mikeschinkel has made great examples improvements that were unrelated to the copy proposal in #150. He will shortly send a PR our way. I'm suggesting to open an issue so we can track that in the 1.1 milestone.

[baywet]

Planning release 1.1:

• it's ok to release offline (no need to be in a meeting)
• @ralfhandl to send a PR about primitive values handling (clarification)
• @mikeschinkel to send a PR to improve the examples (see previous point)
• @lornajane is suggesting a cool down + open for reviews cycle so we don't rush things here
• @mikekistler might have some additional minor changes to push through (he was not able to join today)

But overall we're getting really close.