Meeting: July 22nd, 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]

Copying over the the notes we discussed last week. These represent some known, actionable items as well as some bigger topics that we can continue to chip away at week after week.

Notes from the previous meeting taken by @hudlow from our prioritization discussion for 3.3:

---

Ideas that are concrete and contained enough to consider priorities for 3.3, roughly in a priority order based on appetite/feasibility:

1. @karenetheridge issues surrounding better ways to express things in multiple documents; e.g., multiple documents that each contain paths that can be combined into a single logical OAD that has all the combined paths.
   • Might be interesting to look at the redocly join command to see how it works and what assumptions they have to make.
   • @handrews concrete and straightforward — solves a very common pain point; high priority!
2. @jeremyfiel: examples in path item operation object? @handrews possibly the HTTP message media type? RFC 9112.
   • See also: Examples using HTTP messages, preferably at the Operation Object OpenAPI-Specification#3874
   • Maybe more broadly, this is about correlating request and response examples.
   • @handrews concrete/contained enough to consider higher priority
3. How to model headers more effectively. Headers have structure, but we don't model them well and really only allow treating them as a string.
   • @handrews Background: current tools for modeling headers are inadequate, need to support something akin to media types with mapped HTTP and JSON representations. Note that this is probably a prerequisite to using headers for signatures.
   • for the Link header, there's already a media type and a well-defined way to convert between that media type and a JSON structure, so this is even a possibility for 3.2 — in any case, it sets the precedent for what is needed for structured headers and more specialized structures.
   • See also How to handle response headers? #22
   • @handrews First step is to model the generic syntaxes:
     • RFC 8941 defines structured headers, but there's no media type and no trivial mapping to JSON.
     • RFC 9110, current HTTP semantics defines general header syntax; compatible with structured fields, but closer to historical precedent with some notable exceptions.
   • Lots of headers with their own bespoke historical formatting rules, some that make sense others that are bizarre (e.g., Set-Cookie ... Cookie?) — deprecated behavior only helps so much as it may still be used in the real world.
4. Following on 3, a clear media type or media range with parameters (for request matching and maybe also response matching) / JSON mapping would be a good 3.3 enhancement
5. @pavelkornev: template paths in security schemes: Template paths in security schemas #50
   • @handrews Definitely concrete enough to be on the higher side of priorities, but some more use case work needed to determine how to strike the right balance of flexibility vs continuity with what already exists.

Bigger, less scoped ideas that need more refinement before they can be prioritized:

• What are some small, valuable pieces of the ideas in signatures that we could add in 3.3?
  • See also Indicate the signature mechanism for the API #16
  • @handrews key original ideas:
    • matching on more than the path template we have today
    • explicit disambiguation of some sort
    • correlating requests and responses
  • @handrews Signatures are fundamentally about matching and correlating, which are two separate things.
  • possible first steps:
    • reframe current behavior in these terms. Consider path templates as signatures, consider the ambiguity and resolution, consider tools now available for correlating requests and responses.
    • Figure out what people are actually asking for here:
      • Gary: would like to use signatures for new version of CDMI, and one of the items that comes up is that there are UUIDs for each type of object/operation, and signatures would be a consistent vehicle to identify the type in "real time." Would be used for path parameters, query parameters, bodies, etc.
      • @hudlow is also interested in using signatures to correlate request and response schemas.
• @hudlow adds: maybe consider modeling more fine-grained IAM systems that don't map well to scopes.
  • @handrews: @SensibleWood is the right person to collaborate with on this, there is definitely some interest, but it's a big, complicated topic.
  • @hudlow also adds this fits into the signature discussion because a motivator for carving up operations into finer-grained signatures can be wanting to describe how authorization differs for requests based on parameters, bodies, etc.
• Broadly: a more formal separation between deployment and shape. (A shape of the API might be hosted on different servers with different endpoints and security restrictions.)
  • Related to overlay, but a different emphasis
• More tools for defining resources are a very hot item (see Resource oriented #30) but we need to put some effort into honing this into specific ideas.
  • @hudlow: in theory you could have a top level "resources" property that just glued existing things (mainly operations and schemas) together into resource definitions.
• @hudlow still thinks assertions are a relevant topic at this level, but this is controversial, and needs fleshed out.

Not sure yet (didn't get to it this week):

• Webhook stuff:
  • Webhook Path parameters OpenAPI-Specification#2600
  • Support specifying webhook security scheme OpenAPI-Specification#4230

[karenetheridge]

Adding: formalizing the structure of Content-Type headers, namely separating the concept of the base media-type and its parameters, and matching the HTTP message's Content-Type to the media-type entry under content by just the base media type: OAI/OpenAPI-Specification#2342 -- pretty straight-forward, but needs a deep dive into the RFCs to see if there are any thorny edge cases with how this header is structured.

[handrews]

@karenetheridge we should look at Accept (set by the keys under content in the Response Objects) as well as Content-Type. And this will tie into questions of how to model similar headers like Accept-Patch as well.

[earth2marsh]

Discussed point 5 and considered whether a webhooks-style of approach where it's just a path item to describe some other call that could be used for a security scheme. There is data used with securitySchemes, such as JWT, how do we integrate modeling those things with how we model securitySchemes overall?

[earth2marsh]

Strict vs prioritized signature approaches seem similar to whether there is necessary determinism vs categorization with a degree of certainty, such as backend implementation vs a layered observer.

[earth2marsh]

"How much of signatures should we try to come up with solutions for?" <-- a topic for next week!

[earth2marsh]

Video is now available.