Meeting: May 6th, 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.

[hudlow]

Last week, we discussed challenges in designing a path template/format that has the flexibility users demand, but can be statically assessed for collisions. I don't think it likely we can have our cake and eat it here, but here are some ideas for mitigating this as an issue:

Dealing with collisions:

1. Define operations in a cascade, prioritizing the first match.
2. Define rules of specificity such that a more specific signature match is prioritized over a less specific signature match.
3. Include a priority for an operation in case two paths match and requiring differing priorities when static analysis detects a possible collision.

Supporting different use cases:

1. Support a strict validation mode where any potential path collision is reported as an error.
2. Define explicit syntax for path parameters that can expand to multiple segments.

[darrelmiller]

From the meeting today we identified an example of a problem we would like to have an answer for.

Given paths that return these different representations

/mailfolders/{mailfolder-id} => GenericMailFolder
/mailfolders/inbox => InboxMailFolder

and client code that looks something like this

GetMailFolder(mailfolder-id: string): GenericMailFolder
GetInbox(): InboxMailFolder

What should the behaviour of this be?

var mail = GetMailFolder("inbox")

[hudlow]

To the best of my understanding (please suggest corrections):

scenario	example 1	example 2	3.x
different parameter names	/foo/{bar}	/foo/{baz}	illegal
sub-segment1 differing parameter names	/foo{bar}	/foo{baz}	illegal2
parameter vs literal	/foo/*	/foo/bar	specificity precedence
sub-segment parameter vs literal	/foo*	/foobar	specificity precedence
parameter/literal vs parameter/parameter	/foo/bar/*	/foo/*/*	?3
bidirectional parameter overlap	/foo/*	/*/bar	undefined4
sub-segment bidirectional parameter overlap	/foo*	/*bar	undefined
different parameter schemas	/{type=integer}	/{type=boolean}	inexpressible5
super-segment parameterization	/foo/bar/baz	/**/baz	inexpressible

Footnotes

1. I included the sub-segment examples because I think they feel different even if there's not necessarily a reason or precedent for them to act differently. ↩

2. The spec says, "Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical" and I don't really understand what the word "hierarchy" is doing there and if it's load-bearing. ↩

3. The spec says, "When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts." This doesn't account for two paths where both are parameterized but one has a superset of the other's parameterization. ↩

4. The spec says, "In case of ambiguous matching, it’s up to the tooling to decide which one to use." ↩

5. Technically, since you can define schemas at the operation level, the same path parameter could have different schemas for different operations, but you certainly can't use a path parameter schema to discriminate between two "signatures" that would otherwise collide. ↩

[handrews]

@hudlow why do some have * instead of {varname}?

[hudlow]

@handrews Well:

• I didn't want to bias too much toward the existing syntax
• I wanted to use glob-style ** to indicate multi-segment parameterization
• I couldn't think of a better syntax for showing names and types for parameters where they were salient

[hudlow]

Some user stories to spur further discussion (please suggest more):

• As a service implementor, I want unambiguous requirements for a function ("router") which, given (1) an API description and (2) an incoming HTTP request, routes the HTTP request to zero or one operations defined in an API description.
• As a client implementor, I want to understand how to craft input that a service will handle with the behavior described for a specific operation defined in an API description.
• As an API description author, I want to punctiliously describe API behavior for requests which differ in nuanced ways.

[earth2marsh]

punctilious: showing great attention to detail or correct behavior

[hudlow]

I think I mispronounced it "punctilicious" yesterday which probably has more to do with the flavors of your party refreshments.