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 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)

[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
#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)

[RudyBricks]

I would also recommend having a look at #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)