Meeting: May 20th, 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]

Video is available.

[hudlow]

We had a conversation about a few ideas related to the last couple of meetings.

One of the things we talked about last week was exploring if it might make sense to make certain kind of path overloading legal but have the behavior flagged in a specific way in the ADA. Without trying to design a real interface, the gist would be that a particular OpenAPI tool could choose to support only API descriptions without overlapping signatures and could do so in a predictable way by throwing an exception when processing an ADA that returned, say, true for hasOverlappingSignatures().

I made an assertion that I think "decomposability" is a desirable quality for an API; the idea is that you can take an API description, cull an arbitrary selection of operations and implement those operations such that when you later implement the rest you do not risk breaking any existing clients. This quality is not necessarily true of APIs that have operations with overlapping signatures and some sort of precedence logic.

We still focused on the problems already inherent in OpenAPI 3.x's signature tuple of method and path format even though the broader problem will involve bigger signature tuples.

We discussed some different variations on "format strings":

• URL template and OpenAPI style: /literal/{parameter}
• Ruby on Rails style: /literal/:parameter
• printf/scanf style: /literal/%d

Something that is notably different about the printf/scanf style is that it includes (very simple) parameter typing inline. The existence of this typing potentially allows for overloading a format in expressive ways, and its simplicity allows for practical static differentiation, but you actually have to work pretty hard to contrive real world utility from it.

For example, even if you wanted to differentiate a UUID from a integer, you'd ostensibly be matching on /resources/{string} and /resources/{integer} which of course overlap. Another variation of this is having certain "reserved" paths with inherent collisions with a generic path, such as /users/{name} and /users/me. This strikes me as a particularly realistic example.

We discussed a little how this can technically be solved in JSON Schema, or equivalent constructs, by obliging the author to manually resolve collisions with a negation. For example, /users/{name, not: "me"} and /users/me. This doesn't really feel like the right approach to me but it does solve the problem of decomposability. It's also unclear whether it would actually make sense to use JSON Schema itself to express such constructs.

A new thing we kicked around was the possibility of having a differentiability matrix of formats, likely the same formats in our format registry. I sort of love and hate this idea. It solves the problem of static differentiation of something complicated like a regex in sort of a brute-force way, but a brute-force way that is external to an OpenAPI document and sort of allows an author to be expressive and unambiguous in powerful (albeit still very constrained) ways with a syntax that is lightweight and intuitive. Essentially the format registry would have a table like this:

	int64	double	uuid	email	ipv4	date	uri
int64	------	unsafe	safe	safe	safe	safe	unsafe
double		------	safe	safe	safe	safe	unsafe
uuid			----	safe	safe	safe	unsafe
email				----	safe	safe	unsafe
ipv4					----	safe	unsafe
date						----	unsafe
uri							------

Such that if I have path formats /resources/{id, format: uuid} and /resources/{id, format: integer} the ADA statically knows based on the lookup table that these are differentiable.

I don't have any strong intuition on whether these musings are promising, but I wanted to document them for posterity.