Meeting: July 23, 2024 agenda

[earth2marsh]

Weekly meetings happen on Tuesdays

Time: 5pm GMT / 9am Pacific
Zoom: https://zoom.us/j/975841675, dial-in passcode: 763054

Accessibility & Etiquette

• Participants must abide by our Code-of-Conduct.
• Meetings are recorded for future reference, and for those who are not able to attend in-person.
• We invited challenges to language or behaviour that is harmful or not inclusive during this meeting.
• We look forward to your participation, but please consider these acts of etiquette:
  • Remain on mute when not speaking to prevent interruptions.
  • Blur your background to reduce visual distractions.
  • Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak.

Blur My Background	Raise Hand

Agenda Structure

Topic	Owner	Decision/NextStep
Intros and governance meta-topics (5 mins)	SIG members	--
General discussion topics (list below)	SIG members	--
Wrap-up and seed the next agenda (5 mins)	SIG members	--

Whether attending or not, anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals.

[earth2marsh]

From last week: Show and tell on what folks think might be helpful for us to narrow down what we think the output of a standardized parser.

[darrelmiller]

We are looking to understand the value of formalizing the "low level" model. If the low level model was standardized it may make it easier for folks to build new tools on top of existing parsers and it could make it easier to do compliance testing of parsers.

[mattpolzin]

I can't commit to meeting attendance, but I am the maintainer of the Swift OpenAPIKit project mentioned above and I'd be happy to talk to its goals, design decisions, things that made migration from v3.0 to v3.1 of the spec difficult given aforementioned design decisions, etc.

I'd love to field questions, but I'll start with a brief introduction to the above and then go into just a bit more in the details below the fold.

Swift OpenAPIKit supports decoding OpenAPI documents, creating or modifying them in Swift code, and encoding them. Decoding and encoding are done generically so that both YAML and JSON are supported. OpenAPIKit aims to be flexible but not infinitely so with Swift types that represent OpenAPI and JSON Schema requirements as tightly as possible so that errors and warnings can be generated as part of the process of decoding OpenAPI documents and any OpenAPI written in Swift code is nearly guaranteed to result in a valid reasonable OpenAPI Document.

In Swift, it made sense to me to (a) lean on the language-standard `Codable` framework for encoding/decoding and (b) lean into the value semantics of the language and nice static guarantees offered by the Swift type system given structured value types. The two points are intertwined a bit so you can't speak to the benefits/challenges of one without the other, but more or less (a) is not as interesting in the context of design discussion in my opinion. I'll briefly touch on (b) which definitely differentiates OpenAPIKit from at least some other implementations of the spec.

Designing OpenAPIKit around sum and product types (strongly typed structs and enums in Swift) has familiar benefits to those who have worked in statically typed languages: the compiler can help you out a lot when you're building an OpenAPI document in-code or accessing parts of an OpenAPI document you've parsed. It also impacts the complexity of representing OpenAPI documents in two large ways:

1. It benefits both maintenance of the library and use of documents in-code for OpenAPIKit to represent equivalent semantics in exactly one way, but it is also important to decode and then re-encode an OpenAPI document without changing the encoded representation because OpenAPI authors have their own reasons for representing things in one way or another. This is a constant give-and-take then when deciding how to represent things like JSON Schema enum vs. const where the the former with exactly one element is equivalent to the latter (just a small example).
2. It can be incredibly useful to create Swift types for OpenAPIKit that naturally limit possible values to the only allowable options per the OpenAPI specification, but it's also easy to accidentally disallow an edge case at which point the type has gone from useful to buggy. Pre-release periods and major versions (follow semantic version standards) have been the way OpenAPIKit deals with this inevitable conflict, but an introduction of a new major version of the specification has massive ramifications -- what type-level decisions that were very helpful for the previous version of the specification become blockers to adopting the new version? This was the biggest battle with adopting v3.1 of the specification by far.

I'm not trying to argue for v4 to be less drastic than v3.1, but I am definitely more than happy to explain more about what actually is challenging for OpenAPIKit to change and why. I know v3.0 to v3.1 was intended to be a relatively easy transition, and on paper it feels that way, but it also ended up meaning an impressively large amount of work given the way I chose to design OpenAPIKit's types!

[handrews]

@mattpolzin thanks so much for this! I will try to follow up more later, but I did want to note that the difficult situation with 3.1 is not one we anticipate having again. We are currently planning a 3.2 that is strictly compatible with 3.1, so that there are incremental improvements that can be implemented in the short term while both the 4.0 spec and, once it's published, any new 4.0 tooling, has time to mature. While this is all in flux as we have more conversations across the community, as of now we want to offer two paths: an incremental 3.x series that rewards immediate investment in 3.1, and a major breaking 4.0 spec that brings in substantial new capabilities. The upgrade path from 3.x to 4.0 is something we continue to discuss- it's my hope that a series of incremental 3.x releases can reduce the jump from 3.x to 4.0, but we haven't really discussed any 3.x beyond 3.2. It probably depends on how 3.2 is received.

[mattpolzin]

I'm grateful y'all are thinking about the next version and the migration so holistically. Not an easy task. I like a lot of what I am gleaning about the process you're going through (without having had time to get involved yet).

The upgrade path from 3.x to 4.0 is something we continue to discuss- it's my hope that a series of incremental 3.x releases can reduce the jump from 3.x to 4.0, but we haven't really discussed any 3.x beyond 3.2.

This sounds great. It's difficult to draw lines along breaking vs. not breaking, but a pie in the sky ideal migration path for OpenAPIKit might look like: An announced trajectory for known v3.x and even v4.x changes ahead of time (for planning purposes) but then still incremental introduction into point releases of the spec. It's possible this is exactly what you were describing; it's at least my interpretation of your text. Maybe that's not useful to all implementors, but I think it might make it easier for implementations of the spec and end users of the spec to be in line. For example, there might be arbitrary reasons why "Feature X" is introduced in 3.3 and "Feature Y" in 3.4 instead of both of them in 3.3, but the incremental nature of it is a clear indicator to spec implementors to prioritize "Feature X" and get it done first and similarly it forces end users not to use "Feature Y" until the implementor of their SDK of choice has stated support for 3.4.

Just one idea around managing the explosion of complexity from 3.0 to 3.1 (even though much of that complexity was for very good reason -- case in point, entirely adopting JSON Schema instead of partially borrowing from it).

[handrews]

@mattpolzin glad to hear this is sounding good to you! Running multiple release lines is new territory for us, and there's been healthy debate about what will be most effective.

We'll be focusing more on 3.x once we get 3.0.4 and 3.1.1 out the door. Those two releases are setting the new baseline. They are true patch releases with no new requirements, although some of the clarifications may be surprising enough to shift how people support 3.1 a bit. We've made a lot of effort to leave room for existing implementations by making some clarifications suggestions, but allowing "implementation-defined" behavior. We'll see how that lands!

There will be some sort of feedback period for 3.2 (as there was for 3.1), and I think that's where our communication strategy will really gear up. That way we can talk about a concrete scope for 3.2 instead of speculating. The 3.1 explosion was, as you noted, driven by aligning with JSON Schema. There just didn't seem to be a good incremental way of doing that, and for complex reasons that I might write about elsewhere one day, some of the new complexities weren't obvious to us at the time.

With 3.2, we want to keep things small in terms of implementation effort. Ironically, for users 3.1 is a pretty easy update- really just a few schema keywords change. But it's easy enough to find those, aside from weird nullable usage that slipped through the cracks of unclear wording until 3.0.3... difficulties with "breaking" nullable by clarification in 3.0.3 is what led us to adopt a more "we recommend X but implementations can do Y if they really want to, it's just not interoperable" approach in 3.0.4/3.1.1. If folks have implemented the "wrong" thing in good faith because the spec was unclear, we don't want to suddenly define those implementations as non-compliant. We just want to make it clear that the "wrong" behavior won't necessarily be consistent across implementations.

[earth2marsh]

Today:

• Darrel walked us through OpenAPI.NET, and we discussed libopenapi.
• There was some support for the concepts of "intermediate representation" versus "resolved model" or "standardized interface" terms
• We discussed the potential benefits of a cross-platform, multi-language, "official" libopenapi (or even the possibility of one high-quality [exemplar] implementation), i.e., an interface to the semantic concept of reading in the model.
• We'd need to consider whether the validation carve-out might have created space for this already in our charter and how it intersects with oascomply. There is some basic utility of parsing (and potentially validating) that strengthens the ecosystem without infringing on existing toolings' reasons for being. The idea here is to encourage adoption of 4.0 and to secondarily support compliance journeys.

Next week the plan is to continue to dig into more of the implementations listed above. How would this impact our Moonwalk timeline (it's almost orthogonal to Moonwalk)?

[daveshanley]

Hi folks, I'm the author of libopenapi, happy to provide context and the rationale behind the design etc.

Sorry I could not make the meeting.

[earth2marsh]

video now available, too!

[ralfhandl]

And with songs 😁