Open Community (TDC) Meeting, Thursday 29 May 2025

[github-actions]

Weekly meetings happen on Thursdays at 9am - 10am Pacific

This agenda gives visibility into discussion topics for the weekly Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics.

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.

Meetings take place over 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 invite you to feel comfortable to challenge any 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)	TDC
Reports from Special Interest Groups (5 mins)	SIG members
Any other business (add comments below to suggest topics)	TDC
Approved spec PRs	@OAI/tsc
Active Projects	@OAI/openapi-maintainers
New issues needing attention	@OAI/triage

/cc @OAI/tsc please suggest items for inclusion.

[handrews]

• Should be ready to go, just needs re-approval (@lornajane @karenetheridge @miqui ) after some back-and-forth on minor things– if folks can get to this before the meeting that would be fantastic:

  • v3.2: Add in: "querystring" parameter location treating the entire query string as one chunk of content #4590 (in: querystring)

• We need to talk about how these get reviewed. Thanks to @ralfhandl for the XML review and @jeremyfiel for the multipart review... how do we get two TSC approvals here?

  • v3.2: Support all common XML node types (element, attribute, text, cdata) #4592 (XML nodeType)
  • v3.2: Support ordered multipart including streaming #4589 (ordered multipart)

• This is a big mess of a discussion. @mikekistler and I have been talking and both arrived at the idea that we should leave the current fields (example in various Objects and value and externalValue) as "implementation-defined", perhaps with a recommendation to do whatever tools seem to be doing (@hudlow posted a survey in the discussion linked below), and add new fields to the Example Object that are unambiguous.

  • How should parameter examples be written? #4622 (examples... how do they work?)
  • Proposal with several examples: How should parameter examples be written? #4622 (comment)
  • Earlier sketch of proposal:
    • dataValue and externalDataValue: The value that would be passed to schema validation, which MUST be valid
    • serializedValue and externalSerializedValue: A string (and always a string, never inline JSON/YAML) or external representation of the serialized form, which SHOULD be valid (some data types have multiple possible representations in some formats, so a MUST is not feasible)
    • If both a data and serialized field are present, the serialized example SHOULD be the serialization of the data example (again SHOULD because of serialization ambiguities)
    • The same mutual exclusivity of the inline value vs external applies to these as to the original fields
    • The value and externalValue fields are deprecated, and MUST NOT be present alongside the new fields (same as with the deprecated fields in the XML Object)
    • I have examples in mind of when you would want to use each of the four new fields — there are some values that cannot be represented in the data fields and can only be shown as serialized (multipart mixing text and binary, for example)
    • OAD authors SHOULD NOT use the serialized fields if the serialization format is JSON, because it doesn't add any value and is harder to read and work with

[mikekistler]

@handrews Thanks for adding #4622 to the agenda. Sadly I am traveling this Thurs and will be unable to join, but I do hope there can be a fruitful discussion on this leading to some concrete conclusions. I will continue to add my thoughts to the discussion topic.

[handrews]

@thecheatah If you want to file an issue requesting a way to disambiguate serialization rules, do feel free to do so. I can't promise how much traction it would get. There are several mechanisms near there (format, content*, the Encoding Object) that all have their own difficulties, and overlap in confusing ways. That has made it difficult to address in 3.x.

[handrews]

@lornajane @mikekistler @karenetheridge @hudlow @thecheatah @darrelmiller I have now split the proposal into three essentially independent proposals, each with its own comment thread in the discussion. While each could be done separately, the second and third probably aren't worth doing without the first. The second and third are more independent of each other, although they do all fit together philosohpically.

• How should parameter examples be written? #4622 (comment) (The primary proposal, adding dataValue, externalDataValue, serializedValue, and externalSerializedValue to the Example Object, while deprecating value and externalValue in the External Object, and probably example in the Parameter Object, Header Object, and Media Type Object, and deeming their behavior implementation-defined)
• How should parameter examples be written? #4622 (comment) (A straightforward proposal to allow examples alongside content in the Parameter Object and Header Object, using an in: "querystring" application/jsonpath example to show that this is the only way to properly document the full serialization. I only separated this out to keep things easier to review and discuss. But it's not complex on its own
• How should parameter examples be written? #4622 (comment) (Adding examples to the Encoding Object, which plugs a gap in that it's difficult-to-impossible to use dataValue or even externalDataValue with input data mixing raw binary with JSON-friendly data. But there are some aspects of this that are unclear, and I'd like to consider it separately as we can move on either or both of the other two without having fully decided what, if anything, to do with this one)