Beyond 3.1: The New Big List of Possibilities

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 #182 [Jeremy]
• Optional and Multi-segment Paths #1459 [Darrel, Jeremy, Tim B.]
• Backlinks proposal [Mike K, Kade] #2196
• Support for structured-headers de/serialization #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 #1464 [Jeremy, Mike R, Isabelle]

Authoring improvements:

• Overlays [Darrel/Mike/Ron] (POC Issue #1722) Separate document that augments another API description
• Consider a higher level abstraction, reduce boilerplate
• Reusable groups #445 [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 #1973 )
• Clarify version in info block (and document potentially other common pitfalls)
• Clarify wording around root schemas (define what it is?) and XML #1435 #1622 #1638 [Ted, Mike, Ron]

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

• TBD (as items shift above)

[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.

[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.