Overlays Meeting (2022-02-15)

[kevinswiber]

Overlays Meeting (2022-02-15)

Attendees

• Stu Waldron
• Ron Ratovsky
• Kevin Swiber

Recording

Topic: Overlay Specification
Start Time: Feb 15, 2022 07:59 AM

https://zoom.us/rec/share/iFqll-3wwt0NFOUoJ2-FSrxOaShzInpbcD9_LFdwVuXpu_WNMFI87nmpXK4mNids.kxKewX9pxGmNlzjW

Discussion

• Stu mentions tooling that completely hides the OpenAPI definitions from users, having them auto-generated from managed domain models.
• Visual tooling and manual editing are both goals we’re looking to support.
  • Example: Selecting a portion of an OpenAPI doc to be updated by an Overlay should generate the right filter for the Overlay spec.
  • Ron mentions query builders for databases as an example.
• Stu: The vast majority of the team won’t require the most advanced skillset. The spec has to go into the weeds, because people will need that level of control. And we also need tooling for the 80-90%. Have we made that easy to automate?
• Ron: We should aim for advanced use cases, but we shouldn’t look to solve all of them in the first version. Once we start providing solutions to some use cases, we’ll start getting feedback on what’s missing. That’s why the spec itself is also versioned.
• Has anyone built tooling for the current spec? Ron suggests asking Darrel.
• Ron: We should strive for a stronger relationship with the tooling vendors to help with prototyping solutions around spec evolution.
• Kevin is considering building an implementation.
• We should compile a list of ways people are getting around the problems today:
  • JSON patches, strategic merges
  • YAML merge keys
• It might be worth engaging the wider community (e.g., YAML, JSON Schema) around these problems, as they aren’t OpenAPI specific.
• Dependent specs:
  • Need to make sure our spec dependencies are deliberate and are taking into account the availability of tooling for dependencies. Toolmakers may need to take on writing tools for both overlays and a query language.
• Stu: Biggest bang for the buck may be less sensitive to the approaches we pick. Selecting the best fit might have a positive influence on folks finishing dependent-upon specs.
• Stu: Should we document use cases to provide folks joining the SIG, narrow the scope?
  • Ron: There are easy wins in the list of features folks ask to see in OpenAPI
    • Traits
    • Create groups of items (e.g., pagination parameters)
    • Translation of documentation
  • Ron: We can go over the open issues, look at the headlines, and see what can easily fall within overlays, choose 2 or 3 of those.

Outcomes

• Action: Ron will try to comb trough OAS issues to discover overlay candidates. If not, we’ll do it on the call next time.
• Action: Kevin will spec out tooling and bring thoughts to the next call.

[earth2marsh]

Thanks for the notes! Another use case worth noting is how middleware might transform an API surface. For example, the moment you proxy an API, you've changed the server. You might change the auth model, say from mtls to OAuth. There are many changes like this I can imagine, but I think that this kind of transformation is worth adding as a use case.

Another is to add additional metadata for codegen or test generation. An overlay might help to keep those separate. Continuing on that line of thought... examples can really blow up the size of an OpenAPI document. Why not maintain examples separately and mix them in with an overlay (which brings up the question of what approaches would feel relatively more natural for authors).

One last thought... from an end user perspective it is best to have a flattened version of a multi-part document (for example, no load failure from unavailable resource or permission prob). If we can make that assumption, it may help simplify how we think about the authoring process.

[earth2marsh]

Also, note @ponelat compiled some use cases in this thread here: #9

[kevinswiber]

Also, note @ponelat compiled some use cases in this thread here: #9

Oh, perfect! @webron, it still might be worth taking another pass at any issues that might be new since this list was made in October. That'll certain shorten the scope!

Thanks, @earth2marsh!

[kevinswiber]

Via @webron, here's the video recording of this meeting:

Topic: Overlay Specification
Start Time: Feb 15, 2022 07:59 AM
Meeting Recording:
https://zoom.us/rec/share/iFqll-3wwt0NFOUoJ2-FSrxOaShzInpbcD9_LFdwVuXpu_WNMFI87nmpXK4mNids.kxKewX9pxGmNlzjW

[lornajane]

Closing this discussion from a past meeting, but it will still be available for reference.