Beyond 3.1: The New Big List of Possibilities

[earth2marsh]

With 3.1 released, it's time to revisit the backlog of possible stories to consider as the specification continues to evolve. In cases where a specific TSC or TDC member has indicated interest, their name will be listed in [brackets].

Descriptiveness:

• [ ] Disambiguating based on query OAI/OpenAPI-Specification#182 [Jeremy]
• [ ] Optional and Multi-segment Paths OAI/OpenAPI-Specification#1459 [Darrel, Jeremy, Tim B.]
• [ ] Backlinks proposal [Mike K, Kade] OAI/OpenAPI-Specification#2196
• [ ] Support for structured-headers de/serialization OAI/OpenAPI-Specification#1980
• [ ] Alternative schemas, potential alignment with AsyncAPI (#1443 related?)
• [ ] Reconsider discriminator

Issues covered by SIGS

• [ ] Scenario descriptions
• [ ] Request vs response schemas and hints?
• [ ] Codegen vocabulary [Jonas Lagoni, Ben, Jason, Mike R]
• [ ] Security scheme improvements, such as: signing requirements, discovery mechanisms (#451), signaling deprecation of schemes, and/or digital signatures and encryption OAI/OpenAPI-Specification#1464 [Jeremy, Mike R, Isabelle]

Authoring improvements:

• [ ] Overlays [Darrel/Mike/Ron] (POC Issue OAI/Overlay-Specification#36) Separate document that augments another API description
• [ ] Consider a higher level abstraction, reduce boilerplate
• [ ] Reusable groups OAI/Overlay-Specification#34 [Ron], e.g., $ref more than one component, collections of resources, easier to move around
• [ ] Lifecycle attributes, such as deprecation dates or indicating contract evolution sequences (e.g., prev/next, see OAI/OpenAPI-Specification#1973 )
• [ ] Clarify version in info block (and document potentially other common pitfalls)
• [ ] Clarify wording around root schemas (define what it is?) and XML OAI/OpenAPI-Specification#1435 OAI/OpenAPI-Specification#1622 OAI/OpenAPI-Specification#1638 [Ted, Mike, Ron]

Out of scope for X.X, but important to track for the future:

• [ ] TBD (as items shift above)

[darrelmiller]

Proposal to start separate working groups to drive special interest areas:

Overlays Working Group - Ron Security Working Group - Initially MikeR Scenario Descriptions - Phil

Basic process (suggested):

• Designate a facilitator to start/stop/record meetings.
• Create a doodle to find a good time for folks interested
• Ask Neal to create a Slack channel?
• Summarize progress in weekly TDC call.

[balazstbb]

Would be nice to finally get a solution for https://github.com/OAI/OpenAPI-Specification/issues/182 that is a long outstanding problem with many people requesting it. I know that would come with model change it may break the compatibility with all generators, but later you get there more work will be done. And people can keep using older versions and generators until this supports it.

[peteraritchie]

Is "Reusable groups" specifically for parameters or more general (e.g. for all components)

[RCBiczok]

I would also recommend having a look at OAI/OpenAPI-Specification#630 - like every ISO 20022-based service depends on it.

[rafalkrupinski]

Explicit property requirement/nullability for read and write. Something like

properties:
  prop:
    schema: <schema or ref>
    read:
      require: boolean | 'forbid'
      nullable: boolean
    write: ...

[rafalkrupinski]

Currently we have read- and writeOnly properties to handle cases of slightly different types for incoming and outgoing data. But the PATCH operation is special as it typically allows any property to be omitted and others to be null. The current solution to this is to define a whole new type that has all the properties marked as such. Therefore I think it would be useful to have some means to modify a type in such a way to make it easily work with PATCH method.

[handrews]

I'm going to close this as outdated- the "big list of possibilities" has long since moved to the Moonwalk discussions, and our approach to a possible 3.2+ is very different and more focused (see #3529)