Openapi-specification: OAS 3.1 - The Big List of Possibilities

[darrelmiller]

• [X] OAS JSON SCHEMA :-) !!!! [Ron,Ron,Ron]
• [x] Mutual Auth Certificate Support #1004 [Mike]
• [ ] Overlays [Uri, Jonathan) (POC Issue #1722 [Darrel/Mike]) Separate document that augments another API description
• [ ] Reusable groups #445 [Ron] e.g. $ref more than one component
• [ ] Alternative Schemas #1443 [Darrel, Ted] (Need community implementations to commit to 3.1)
• [ ] Clarify wording around root schemas and read-only/write-only, XML #1435 #1622 #1638 [Ted, Mike, Ron]
• [x] "Scopes" on Security Requirements for schemes other than OAuth2 #1393 #1366
• [ ] Optional and Multi-segment Paths #1459 [Darrel, Jeremy] Priority?
• [ ] Disambiguating based on query #182 [Jeremy]
• [ ] Digital Signatures and Encryption #1464 [Mike] Followup with Isabelle on status
• [x] 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?) #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 https://github.com/OAI/OpenAPI-Specification/pull/1270#issuecomment-316145938 (on maintainability) and @webron's reply https://github.com/OAI/OpenAPI-Specification/pull/1270#issuecomment-316219932 - 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.

[ahl]

@darrelmiller would it be worth updating the checklist? Do I understand correctly that the JSON schema and alternative schema items are complete?

[tiangolo]

May I ask, what this item refers to?

OAS JSON SCHEMA :-) !!!! [Ron,Ron,Ron]

---

I would like to request/propose upgrading the JSON Schema compatible version to draft-07 / draft- @handrews -json-schema*-01. But I don't know if this is already being considered somewhere else.

The current version says it's compatible with "JSON Schema Specification Wright Draft 00".

But I see the included schemas declare being compatible with draft-04 (or am I misunderstanding something?).

---

Also, I don't know if a new issue would be the correct place to request it, before knowing if it applies or is already considered. And I don't want to add clutter to the issues...

I could submit a PR, but I'm not sure that would actually help you guys, or if it would be better to just add the comment here and let you guys do it yourselves.

[darrelmiller]

@tiangolo I was referring to the JSON Schema that describes an OpenAPI description document.

I don't expect the OAS to update to a newer version of JSON Schema until it comes out of draft. Alternative Schemas will be an interim solution for people who want to rely on draft versions of JSON Schema. We are waiting for implementations of Alternative Schemas to appear before incorporating it into the specification.

[darrelmiller]

@ahl JSON Schema for OAS is complete. Alternative schema is still in pilot phase.

[tiangolo]

Thanks for answering @darrelmiller ! I'll subscribe and comment on the issue about Alternative Schemas.

[philsturgeon]

Can we bump Alternative Schemas to v3.2 or v4.0 or something? I know its not formally binding or anything but on the TSC a lot of us were agreeing that alternative schemas is better done later as it's really far from being ready to go (#1943). If we can instead focus on #1977 for v3.1 we should be getting closer to done.

Also, overlays. It seems like we are nowhere near any sort of consensus and I see no movement. Can this be bumped back to v3.2 or v4.0 too?

[MikeRalphson]

@philsturgeon We got close on overlays - I even implemented it as a proof of concept (which is more than can be said for alternative schemas), the thing which derailed it was a discussion of whether overlays and traits should work in a very similar way / share syntax. Trait proposals being not as far forward yet.

[philsturgeon]

@MikeRalphson oh my bad, I mixed up overlays and traits. Should we keep waiting on traits, or get on with overlays as they are, or postpone them both until consensus? I would love to see a v3.1 at ASC in a few weeks, it'd be a nice announcement :D

[handrews]

@philsturgeon @MikeRalphson this also gets a bit into the frequency of release / marketing thing. For adding things like traits/overlays, it would make a lot of sense to scope 3.1 to what we have + what we can finish in the near future, and then say something like "3.2 will be traits/overlays, as soon as we finish those." That way, punting them out of 3.1 is not a huge deal. But that does require the ability to do a follow-on release in, say, 3 or 4 months, without people freaking out over it.

[ioggstream]

We got close on overlays - I even implemented it as a proof of concept

Is there a PR for that or you are referencing #1864 ?

[MikeRalphson]

I'm referring to #1722 - when I say implemented, I mean wrote a PoC implementation in code.

[xiaoxiangmoe]

Is https://github.com/OAI/OpenAPI-Specification/issues/681 possible to be supported in oas 3.1

[MikeRalphson]

OAS 3.1 will support https://github.com/OAI/OpenAPI-Specification/issues/681#issuecomment-438893090

[xiaoxiangmoe]

If we support integer enum with named items, can we also support named int enum as discriminator in mapping?

[philsturgeon]

Can we close this and punt some issues over to 3.2 possibilities?

[handrews]

@xiaoxiangmoe OAS 3.1 will support full JSON Schema compatibility, and while JSON Schema does not have a direct analogue of discriminator (for a whole bunch of reasons), it has several features that could be used to build a much better and more flexible discriminator-ish feature. Hopefully with that available, folks will experiment and then we can codify something that fits with JSON Schema more cleanly than the current discriminator _and_ is more flexible.

[kdebski85]

I have a question regarding support for format for integer type.

In Defined Formats section of JSON Schema I haven't found anything about integers - https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.7.3

OAS 3.0 supports formats int32 and int64.
Will OAS 3.1 support formats int8, int16, int32 and int64 or formats for integers will not be defined by OAS 3.1?

I think adding support for int8 and int16 would be very helpful because these types are often used for bytes/shorts in many dictionaries and configuration.

[MikeRalphson]

In JSON Schema draft 2019-09 and therefore in OAS 3.1, format is an annotation, not by default, a constraint so the utility of a list or registry of approved formats is somewhat diminished.

It may be better to use minimum and maximum constraints instead of (u)intXX formats going forward.