Overlays Meeting (2024-07-02)

[lornajane]

Restarting the meetings this week. Any agenda items, please add a comment.

This meeting falls under the OpenAPI code of conduct.

[lornajane]

First meeting in over 2 years, we chatted a bit about use cases and possible next steps for the overlays specification. I'll attempt to get some of the key points down here for anyone who is interested but wasn't able to attend. One topic per comment since discussions have threads.

[lornajane]

We discussed some clear use cases, particularly where OpenAPI descriptions are generated from code, where it is impractical or just annoying to create and maintain some parts of the API description. There are some existing solutions in this space, in terms of some JSON merge tooling, Redocly decorators, and a few other alternatives.

[lornajane]

We talked about the current approach of using generic structure-based manipulation with JSON Path, in comparison to a more semantic manipulation where we could, for example, identify all parameter or operation types that match certain criteria (without matching a property named "properties" or "items"!). We considered whether a simple approach could be to combine overlays with a normalisation tool, so that schemas only exist under components.schemas and the ordering of things is deterministic - this makes JSON path more useful as a tool, and also makes overlays less brittle when API descriptions are manipulated or refactored.

We considered whether, without dictating the data structure that the OpenAPI description must be parsed into, we could offer some more friendly selector syntax for finding nodes. Whether a parameter is declared in an operation, or under components.parameters wouldn't matter - users would be able to find all parameters named *_id in paths of post requests. This would push some of the complexity into the tooling vendors' space, but give an easier on-ramp for users (hopefully!).

[lornajane]

On the basis of the current status of the Overlays Specification: We have identified that the existing remove/update action types can be limiting. There's an open pull request to switch to remove/replace/add - but it would be a breaking change. A likely next step is to release the current specification as 1.0.0 and consider what other changes we want to make before pushing a big change with a clear version number increment (if we follow semantic versioning I think changing keywords this much means doing a 2.0.0).