Overlays Meeting (2025-02-25)

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

[kevinswiber]

Small meeting today, just @mikeschinkel and myself. We reviewed the last talk I gave on Overlays at the DeveloperWeek Conference.

• Some confusion over JSONPath. Some folks weren't aware there was a new RFC.
• I used https://overlay.speakeasy.com to demonstrate Overlays. That went really well. Still some confusion over needing to set a specific extension for getting the JSONPath RFC support.
• Overall, good questions and good usage discussion. One person asked if they could submit an OpenAPI Description along with a bunch of Overlays for multi-language support and have an OpenAPI docs generator figure it out without having to compile multiple Overlay+OAD docs. I don't think anyone supports that quite yet.

[kevinswiber]

@handrews I'd hesitate to go through the multitudes of JSONPath implementation options. There are so many libraries out there, and most of them do at least 1 thing different than the others. That's why I say if we go down that path, we might as well take it all the way. The standardization is helpful, but only if implementors actually create the software that adheres to the standard. We could try "jsonpath-draft", "jsonpath-plus", and "jsonpath-rfc9535" (default) as options. But like... that's still a pluggable engine... so lemme use "jq", too, y'know?

[ThomasRooney]

Still some confusion over needing to set a specific extension for getting the JSONPath RFC support

FYI as the person who made the call to add the extension, I think it is confusing too. We plan on removing it within ~6 months.

It exists because we needed a migration path/config flag to move our customers over to RFC9535 from the previously non-compliant library https://github.com/vmware-labs/yaml-jsonpath. Effectively we started flagging a warning to end-users that had jsonpaths that differed in behaviour between the two libraries to opt in, and in ~6 months we'll re-evaluate where we are and hopefully remove the extension. To make it less confusing to new users, the default overlays created in the playground & other speakeasy properties had the extension for opting in to RFC9535 compliance jsonpaths enforced.

I don't think it makes sense to adopt for the specification; it's a consequence of Speakeasy being an early adopter.

[handrews]

@ThomasRooney @kevinswiber I'm happy to drop the idea of adding anything to the spec for this.

[kevinswiber]

@handrews Yes, I was just trying to be selfish and sneak something into the spec that I want but was ultimately voted against previously. (I wanted a declaration for the query engine so we could swap out the query mechanism. I wanted to use jq, which also has libjq that can be added to most language runtimes.) But that's okay. With @ThomasRooney's input here, I think we should drop it for now!

[mikeschinkel]

@kevinswiber — For future reference, I'd like to hear more about your idea as it sounds like it might be compelling.