Meeting: July 30, 2024 agenda

[earth2marsh]

Weekly meetings happen on Tuesdays

Time: 5pm GMT / 9am Pacific
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 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.

[handrews]

I'd l like to discuss the data modeling area, specifically looking at:

• what things we are trying to model
  • media types (most notably JSON, XML, and forms)
  • grammars (HTTP headers and potentially some query strings)
  • code (basic structures, OO class hierarchies, generics, etc.)
• where in the process of using an API do models appear?
  • SDK input and output (code-oriented) - this is even more important when supporting RPC styles
  • HTTP input and output (media type and grammar-oriented)
  • how do we relate SDK-level and HTTP-level models?
• how well (or poorly) the 3.x approach fits those things and places?
  • our XML approach only covers some parts of XML
  • our approach to forms is inconsistent (query vs body content) missing features (ordering, repeated keys)
  • grammar-based targets such as HTTP headers are not supported well at all
• what other behaviors have gotten mixed into data modeling in 3.x
  • encoding needs to be distinct from data modeling
  • URI Templates conflate them, which makes sense for URI Templates but not for OAS in general
  • Even within URI Templates, the encoding options are not user-friendly
  • Encoding other things is handled in a variety of confusing ways
• how might we separate those other things to make all features more straightforward
  • Need to figure out overlap between JSON Schema content* and other mechanisms
  • Possibly content* is for encoding within a format's data, while other mechanisms are for encoding based on the target format

I've been spending a lot of time with OAS 3.x data modeling and encoding, and I think we need a deep re-think of how this works:

• Orthogonal concerns should be orthogonal (as much as is possible)
  • data "shape" - the information needed to lay out a data structure in code / memory / db table / etc. that can accommodate any valid instance
  • non-shape validation constraints - information that tells you whether an instance is valid, beyond whether or not it fits the essential shae
  • target format encoding (URI percent-encoding, punycode for international domains, base64 in cookies, base64url, etc.)
  • there is overlap here, but we can be more clear setting expectations for what code gen, in particular, is and is not expected to handle
• Simple cases should be simple, hard cases should be possible
  • most form-urlencoded strings (or form-data multipart bodies) can be modeled as JSON Objects (unique keys, unordered)
  • but full support requires ordered name-value pairs with additional metadata
  • mapping from one kind of model to another must be treated as a first-class problem rather than a collection of weird hacks scattered across different Objects and standards
• We should define and register modeling approaches for non-JSON data
  • Extensibility, especially for HTTP headers
  • But also for things like JSON sequences that are easy enough to model if you just agree on an approach
  • Code generation patterns
  • the relationship to JSON Schema vocabularies is unclear, but JSON Schema seems to be re-doing all of that so ¯\(ツ)/¯ — I think it's safer for us to use our own registries to manage things

[handrews]

In today's meeting we went over the above discussion of data modeling. There were no major objections or disagreements, but we only had a tiny bit of time to discuss implications or alternative ideas. We will pick up the discussion next week.

[rangarajl]

@earth2marsh can you please share the zoom recording for this session

[earth2marsh]

Thanks for the reminder! Video has been posted.