OAS 3.1 - The Big List of Possibilities

[darrelmiller]

• OAS JSON SCHEMA :-) !!!! [Ron,Ron,Ron]
• Mutual Auth Certificate Support [OpenAPI.Next Proposal] Add client certificate to authentication methods #1004 [Mike]
• Overlays [Uri, Jonathan) (POC Issue Yet another Overlay proposal Overlay-Specification#36 [Darrel/Mike]) Separate document that augments another API description
• Reusable groups Group multiple parameter definitions for better maintainability Overlay-Specification#34 [Ron] e.g. $ref more than one component
• Alternative Schemas OAS and data models? Alternate schema languages? #1443 [Darrel, Ted] (Need community implementations to commit to 3.1)
• Clarify wording around root schemas and read-only/write-only, 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]
• "Scopes" on Security Requirements for schemes other than OAuth2 Scopes for jwt-based security scheme #1393 API Key authentication should allow scopes to be defined. #1366
• Optional and Multi-segment Paths Proposal: Multisegment Path Parameters #1459 [Darrel, Jeremy] Priority?
• Disambiguating based on query Support an operation to have multiple specifications per path (e.g. multiple POST operation per path) #182 [Jeremy]
• Digital Signatures and Encryption Support for JOSE (JSON Signature and Encryption) Standards #1464 [Mike] Followup with Isabelle on status
• Extensions in the discriminator object [Mike]

Out of scope for 3.1, but important for future

• Discovery mechanism for security credentials (jwt, apikey, etc) (Pilot?) Support for Kerberos and others as type values of Security Scheme Object #451 [Ron]
• Supporting Message Based APIs (Ask for demo from Fran and Uri)

[eropple]

In particular, is there an ETA on having an OAS JSON Schema? My Modern project is an OpenAPI3-first web framework for Ruby and the closest things I have to validation of my output schema are openapi3_parser (which, while ambitious, is not comprehensive nor is it canonical) or putting the thing into swagger-js and seeing what errors I get out of it.

[MikeRalphson]

@eropple although there is no ETA yet, have you seen the two draft schema proposals in PRs #1236 and #1270 ?

[handrews]

@MikeRalphson is there a concise summary somewhere of why we have two stalled PRs for this? If y'all want help writing a schema I'm happy to take a crack at it but I'm kind of afraid to dig through those PRs. I'd be more likely to just eyeball the spec and make a new proposal, but I don't want to do that if either of the existing ones is likely to move forwards, and if I do make an attempt, I definitely want to avoid whatever we already know that's caused these to get stuck.

[MikeRalphson]

@handrews thanks! The opening comment of #1270 sums up the reason for there being two schemas. #1236 was generated from the spec. markdown itself and only deals with objects defined therein (thus has some limitations in its ability to thoroughly validate an OAS document). #1270 has some extended abstractions so as to enforce dependencies between properties etc.

Please see #1270 (comment) (on maintainability) and @webron's reply #1270 (comment) - is there a better way of modelling allOf with additionalProperties: false situations?

@webron is closest to how this is most likely to move forward (as #1236 is auto-generated, I suspect help on #1270 would be the more productive route).

[tedepstein]

@darrelmiller, do we want to consider Conformance Test Suite for OAS3 consumers as a possible addition to this list? Or should we treat that as something separate, because it's not a new capability in OAS itself?

[darrelmiller]

@tedepstein It's a worthy goal and it takes time, so it should be considered along with the other efforts. Whether we have the capacity to make it happen in the timeframe is a different question.

[cmheazel]

Two votes for Alternative Schema:
"For most of our customers schema documents are an important part of the management and the publication of their datasets (today mostly XML Schema, but there is growing interest in JSON Schema). Such an extension would greatly help to link those schemas from our OpenAPI definitions in a clear and unambiguous way. We would also implement the alternative schema Object in our software later this year, if it will be included in 3.1." Clemens Portele - Interactive Instruments Gmbh

"the proposal looks good to me and I support it." Peter Vretanos - CubeWerx

Both companies produce COTS products for the discovery and access of geospatial data.

[cmheazel]

JSON Schema for OAS
ESA, NASA, NOAA, and others are looking for a common way for clients to access remote sensing data. A JSON Schema for OAS would help document this interface. Think in terms of an API template which will behave the same no matter who implements it.

Use case: The EU is federating member nation clouds for processing Earth Observation data. Data and analytics will be able to move freely between the clouds. Any analytic must be able to access any data from anywhere in the federation.

[MikeRalphson]

We would also implement the alternative schema Object in our software later this year, if it will be included in 3.1

@cmheazel Great to hear, although this does completely go against the idea of draft-features.