Meeting: August 20th, 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.

[earth2marsh]

[NB: carrying this over from last week's agenda] Let's continue the data modeling discussion with high level thoughts on SDK vs HTTP interfaces. Background:

• July 30th agenda (we discussed all of this)
• Aug 6th agenda (we only discussed the very first bullet point group so far)

Here are the "for next week" comments from last week's agenda:

• 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

[handrews]

@earth2marsh since the "consumer-ready" format came up in last week's call (I read the transcript), I'd like to address that. There are some points in there that we should really resolve because they keep coming up over and over again.

• Proposal: a consumer-optimized form of OpenAPI descriptions #63

[darrelmiller]

Attempted diagram of Henry's thinking...

[kevinswiber]

Here you go:

┌─────────────────┐   ┌────────────────┐     ┌─────────────────┐         ┌─────────────────┐   ┌────────────────┐     ┌─────────────────┐
│                 │   │                │     │                 │         │                 │   │                │     │                 │
│   Server-side   │   │      SDKs      │     │   Server-side   │         │   Server-side   │   │  Client-side   │     │  Documentation  │
│     Handlers    │   │                │     │     Routing     │         │   Marshalling   │   │  Marshalling   │     │                 │
│                 │   │                │     │                 │         │                 │   │                │     │                 │
└─────────────────┘   └────────────────┘     └─────────────────┘         └─────────────────┘   └────────────────┘     └─────────────────┘
         ▲                     ▲                      ▲                           ▲                     ▲                      ▲         
         │                     │                      │                           │                     │                      │         
         │                     │                      │                           │                     │                      │         
         │                     │                      │                           │                     │                      │         
         │                     │                      │                           │                     │                      │         
         │                     │                      │                           │                     │                      │         
         │                     │                      │                           │                     │                      │         
         │           ┌─────────┼─────────┐            │                           │           ┌─────────┼─────────┐            │         
         │           │                   │            │                           │           │                   │            │         
         │           │                   │            │                           │           │                   │            │         
         └───────────┼     Generated     ┼────────────┘                           └───────────┼     Generic       ┼────────────┘         
                     │       Code        │                                                    │       Code        │                      
                     │                   │                                                    │                   │                      
                     │                   │                                                    │                   │                      
                     └───────────────────┘                                                    └───────────────────┘                      
                               ▲                                                                        ▲                                
                               │                                                                        │                                
                               │                                                                        │                                
                               │                                                                        │                                
                               │                                                                        │                                
                               │                                                                        │                                
                               │                   ┌──────────────────────────────────┐                 │                                
                               │                   │                                  │                 │                                
                               │                   │                                  │                 │                                
                               │                   │                                  │                 │                                
                               │                   │       OpenAPI Description        ┼─────────────────┘                                
                               └───────────────────┤                                  │                                                  
                                                   │                                  │                                                  
                                                   │                                  │                                                  
                                                   └──────────────────────────────────┘                                                  

[handrews]

@kevinswiber YEESSSS! ASCII ART FTW!!!!!!

[handrews]

I'm wondering if maybe documentation should be moved to "generated", as we talk about generating docs. The distinction is probably whether the specification dictates the output, and in the case of documentation, it does not. On the other hand, the specification dictates what an HTTP message should look like given certain input data.

The server-side checks (included in the list but not the diagram) are still pretty vague in scope so it's still not quite clear to me where they land. We need to look at what tools do for security checks, rate limiting, etc.

[kevinswiber]

@handrews I think documentation, with respect to OpenAPI use cases, is always in the "generated" category. I think of "generic code" as using some OpenAPI library (either published or internal) that can reference the details of the OAD and be used within a larger use case context. I don't see documentation tools doing this.

[handrews]

@kevinswiber yeah I think you're right, we should move docs to generated. Web forms are another generation use case, and one that is sometimes integrated with docs to provide a "try this" interface.

In fact, I think we could define the client side of the "generic" part as... assuming you have a web form that accepts all necessary input as bits of JSON (because all input, be it parameters, request bodies, etc. is described by JSON Schemas), what code is needed to produce the HTTP request? This also tells us what fields are needed for this part of the larger set of use cases.

I was thinking about this more yesterday and started slicing up the spec yet another way: What Objects/fields are needed to define the minimal interface presented to humans/code/uis/whatever vs what fields constitute the configuration necessary to know how to map input that is valid against that interface to HTTP? This is relatively straightforward on the client side, and less clear on the server side.

This is related to generated vs generic but might be an even more fundamental way to think about it. When users ask for things like relational constraints across parameters, they're not really asking us to (for example) model HTTP messages, which is an approach we've discussed for Moonwalk. They're thinking about the interface to an operation (or resource), as a single thing, and there might be relational constraints within this interface. The fact that the single interface maps to a range of different locations in HTTP is important, but is properly hidden behind that interface.

Generators project the interface into various domains, while generic tools apply the configuration to convert between the interface and HTTP. Of the various ways we've discussed to carve up how we look at the OAS, this one is feeling like the most important so far. The seven functional areas are still important, and somewhat orthogonal. But they're a little more abstract.

For example, I was getting bogged down thinking about data modeling in the abstract. If we have data models at the interface layer and the HTTP layer, then we need to handle some sort of mapping between arbitrary data models on either side. But really, HTTP is well-defined. Media types are well-defined. It's only the interface-side data model that varies. If we concentrate "data modeling" on that interface, and treat the HTTP side as a configurable transformation to a known, rather than free, format, then this might start to get more manageable. We kind-of already do that with some OAS Objects, but not in a consistent, coherent way.