Closed
Description
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 Support an operation to have multiple specifications per path (e.g. multiple POST operation per path) #182 [Jeremy]
- Optional and Multi-segment Paths Proposal: Multisegment Path Parameters #1459 [Darrel, Jeremy, Tim B.]
- Backlinks proposal [Mike K, Kade] Feature suggestion: "Backlinks" - Links defined the inverse of the way they are currently #2196
- Support for structured-headers de/serialization Support for structured-headers de/serialization #1980
- Alternative schemas, potential alignment with AsyncAPI (OAS and data models? Alternate schema languages? #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 (Support for Kerberos and others as type values of Security Scheme Object #451), signaling deprecation of schemes, and/or digital signatures and encryption Support for JOSE (JSON Signature and Encryption) Standards #1464 [Jeremy, Mike R, Isabelle]
Authoring improvements:
- Overlays [Darrel/Mike/Ron] (POC Issue Yet another Overlay proposal Overlay-Specification#36) Separate document that augments another API description
- Consider a higher level abstraction, reduce boilerplate
- Reusable groups Group multiple parameter definitions for better maintainability 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 Add
info.lifecycle
with maturity/lifecycle informations. #1973 ) - Clarify version in info block (and document potentially other common pitfalls)
- Clarify wording around root schemas (define what it is?) and XML xml property and root schemas #1435 Clarify spec wrt readOnly and writeOnly in referenced schemas #1622 #1622 - Clarify spec wrt readOnly and writeOnly in referenced schemas #1638 [Ted, Mike, Ron]
Out of scope for X.X, but important to track for the future:
- TBD (as items shift above)