Meeting: August 6th, 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 like to continue discussing the Data Modeling area - see last week's comment for what we have discussed to date.

First, we should discuss any questions from last week that folks have thought of in the meantime.

After that, here are some topics I'd like to consider, probably in this order although if someone really wants to change the order that's fine:

• SDK-level modeling
  • What do code generation (OAD-to-code) tools need from data modeling?
  • What do spec generation (code-to-OAD) tools need from data modeling?
• HTTP-level modeling
  • What do HTTP serialization / parsing tools need from data modeling?
  • Where is the boundary between HTTP interaction modeling and data modeling?
  • Is there a distinct target format serialization / parsing component (e. g. URI percent-encoding, HTTP header escaping) and if so, what is the boundary between it and data modeling?
• Static vs Runtime usage
  • Can we classify some constructs as essential to static usage such as data structure / class generation?
  • Can we exclude some constructs from static usage, making them purely runtime (which could include "code generation" in the form of constructor or accessor logic, but not the data structure "shape")
• Mapping between SDK-level and HTTP-level modeling
  • Do we need to be able to use the same model for radically different target formats? (I'll reply to this comment with an example)
  • How, and how well, do Parameter Objects support SDK-level interfaces today?
  • What are our "worst case" scenarios that are the most difficult to support today
    • HTTP headers are essentially unsupported except for the most trivial usage
    • Form data either performs complex RFC6570-ish mapping (schema/style) or leaves it entirely to the user (content)
    • XML support is... partial
  • What are our extensibility needs?

[handrews]

Here is an example that uses the same Schema Object for four different media types:

openapi: 3.1.0
components:
  schemas:
    something:
      type: object
        properties:
          foo:
            type: string
          bar:
            $comment: |
              Assumed equivalent to xsd:boolean for XML, requires
              encoding object to ensure JSON serialization to
              the non-quoted string true in multipart
            type: boolean
            xml:
              attribute: true
  requestBodies:
    something:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/something"
        application/xml:
          schema:
            $ref: "#/components/schemas/something"
        multipart/form-data:
          schema:
            $ref: "#/components/schemas/something"
          encoding:
            bar:
              contentType: application/json
        application/x-www-form-urlencoded:
          schema:
            $ref: "#/components/schemas/something"
          encoding:
            bar:
              contentType: application/json
paths:
  /something:
    post:
      requestBody:
        $ref: "#/components/requestBodies/something"
      responses:
        "200":
          description: Ok

Here are the different serializations. I'm not entirely sure I understand how XML serialization is supposed to work, but you get the idea.

{
  "foo": "whatever",
  "bar": true
}

<?xml version="1.1"?>

<something bar="true">
  <foo>whatever</foo>
</something>

Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data;name=foo

whatever
--boundary
Content-Type: application/json
Content-Disposition: form-data;name=bar

true

foo=whatever&bar=true

[handrews]

Polymorphism (including discriminator):

• Important, widely used
• Optional field would be helpful
• Need to support class hierarchies without discriminator
• Need to support shape variants that are not class hierarchies (e.g. alternative web forms for a branch in a form flow)

SDK:

• Want to represent a resource as a class, and end users to work with the resource regardless of read/write/etc. etc.
• We've handled readOnly/writeOnly in different ways in different releases that solved different subsets of the problem

Gary's use case groups (for thinking about discriminator and other data modeling things):

• client-side
• server-side
• tooling use case

[handrews]

For next week:

• Philosophical discussion about the relative importance of the HTTP-side interface vs the SDK-side interface
  • Is one more important? To whom?
  • How does this fit with how tools are currently written and used?
  • Background philosophical concept: consumer over producer (but consumer of HTTP or consumer of SDK?)
• Scope: XML and other less-common targets
  • many older / more slow-moving standards are still XML-centric
  • Extensibility? It's easier if we don't have to solve all target representation problems up front
  • Note the example of one schema mapping to many targets in the earlier comment- do we need this?
  • One SDK representatoin for multiple representation at the HTTP may make model-to-target mappings more clear
• Consider the use case groups (client, sever, tools- Gary to elaborate on distinctions) in the above comment for any specific data modeling features
  • We'll probably get back to this after the higher-level SDK/HTTP discussions resolve a bit

[earth2marsh]

Video of the call has been posted