Meeting: February 4th, 2025

[earth2marsh]

Weekly meetings happen on Tuesdays

Time: 5pm GMT / 9am Pacific
Zoom: https://zoom-lfx.platform.linuxfoundation.org/meeting/98869769538?password=d769f940-7da7-4de8-9fab-685a1cc8f33e

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]

Per #16, we're planning to re-open the discussions on how we might organize 4.x around signatures in order to be more inclusive of HTTP API designs that may not fit within the opinions of the structure of 3.x. Examples include multi-path segments, situations where query parameters may differentiate between operations,, and a much larger variety of HTTP methods (even potentially including custom methods). See also this doc from the last time we discussed this.

Extra credit: try to model how such a variety of styles might be represented in YAML!

[rafalkrupinski]

@handrews I don't think additional complexity is avoidable, since OAI want to keep all future versions at least functionally compatible, i.e. there must be a way to translate old OAD to newer versions. No reasonable type description language can fully replace JSON Schema, which is a validation language. So the only way is to add a new language as an alternative and keep JSON Schema for compatibility.

Also making the new type language interoperable (types from new language referring to schemas and vice versa) would add more complexity for tools, while keeping them separate would make it harder for OAD authors harder to transition.

But I guess there's already a discussion about this somewhere on GH....

[handrews]

@rafalkrupinski yeah everything you mention has been discussed in the Tuesday meetings, often multiple times. It still comes down to availability of volunteers with the necessary understanding. Schemas will get addressed in some way for Moonwalk, but whether that's a deep reworking of data modeling or just a more well-defined boundary so that other people can more easily experiment with alternatives will depend on who is available to figure out any sort of deep reworking.

Our challenge is not a lack of understanding of the problem or of the range of possible soluitons. It is purely one of available time and people, given the huge number of things that need to be done to get to 4.0.

[handrews]

Also, we did 3.1 to improve the situation with schemas by restoring compatibility. But that meant that we didn't do much (other than webhooks) outside of the Schema Object. We need to focus on improving the things that haven't been examined since 3.0 as well now.

[rafalkrupinski]

@handrews
Why is it not as simple as adding a new keyword to all non-json schema objects in OAD that already have schema keyword, say typedef (JSON TypeDef), and make it xor with schema keyword? Honest question, perhaps I'll join one Tuesday and ask it myself...

Also I'd be willing to experiment with adding support for it in my python generator, which is slowly getting to the point where I'm quite happy with what it generates. I just don't have any experience with any other* type description language.

edit:
*other than JSON Schema, which as we all know, isn't one

[handrews]

@rafalkrupinski solutions for alternative schemas have been proposed in the past¹ and added to our extension registry with two values.² However, we have not seen much in the way of implementations of this old (3.0-era) proposal.

So it's really not as simple as just saying "here you can do different things, go for it!" It turns out people just... don't. Maybe that was more of an issue of follow-through on our part. Shortly after that, we decided to make 3.1 fully JSON Schema-compatible, which made one of the two registered "alternative" schema values obsolete. I think it was originally mostly motivated by people wanting to use plain JSON Schema (which they can now do by default) or use XSD for XML (a small subset of potential users).

Perhaps a new push on this now would be more productive as there are more possible options out there. For something like this, getting it in the spec is only half the work. Or maybe even less.

Footnotes

1. although we seem to have lost track of some supplementary documentation that 404s, not sure what happened there ↩

2. that link to the "master issue" should go to the proposal document now- that's why the issue is closed, not because we gave up on it ↩

[earth2marsh]

@daveshanley may also join to walk through the DOM design of libopenapi.

[earth2marsh]

... which he did! Video now posted.