Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OAS 3.1 - The Big List of Possibilities #1466

Closed
4 of 13 tasks
darrelmiller opened this issue Jan 26, 2018 · 29 comments
Closed
4 of 13 tasks

OAS 3.1 - The Big List of Possibilities #1466

darrelmiller opened this issue Jan 26, 2018 · 29 comments
Milestone

Comments

@darrelmiller
Copy link
Member

darrelmiller commented Jan 26, 2018

Out of scope for 3.1, but important for future

@eropple
Copy link
Contributor

eropple commented Feb 27, 2018

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
Copy link
Member

MikeRalphson commented Feb 27, 2018

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

@handrews
Copy link
Contributor

handrews commented Feb 27, 2018

@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
Copy link
Member

MikeRalphson commented Feb 27, 2018

@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
Copy link
Contributor

tedepstein commented Jul 13, 2018

@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
Copy link
Member Author

darrelmiller commented Jul 13, 2018

@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
Copy link
Contributor

cmheazel commented Jul 26, 2018

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
Copy link
Contributor

cmheazel commented Jul 26, 2018

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 MikeRalphson pinned this issue Dec 13, 2018
@MikeRalphson
Copy link
Member

MikeRalphson commented Jan 3, 2019

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
Copy link

ahl commented May 17, 2019

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

@tiangolo
Copy link
Contributor

tiangolo commented May 20, 2019

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
Copy link
Member Author

darrelmiller commented May 20, 2019

@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
Copy link
Member Author

darrelmiller commented May 20, 2019

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

@tiangolo
Copy link
Contributor

tiangolo commented May 20, 2019

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

@philsturgeon
Copy link
Contributor

philsturgeon commented Sep 26, 2019

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
Copy link
Member

MikeRalphson commented Sep 26, 2019

@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
Copy link
Contributor

philsturgeon commented Sep 26, 2019

@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
Copy link
Contributor

handrews commented Sep 26, 2019

@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
Copy link
Contributor

ioggstream commented Sep 27, 2019

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
Copy link
Member

MikeRalphson commented Sep 27, 2019

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

@xiaoxiangmoe
Copy link

xiaoxiangmoe commented Jun 27, 2020

Is #681 possible to be supported in oas 3.1

@MikeRalphson
Copy link
Member

MikeRalphson commented Jun 27, 2020

OAS 3.1 will support #681 (comment)

@xiaoxiangmoe
Copy link

xiaoxiangmoe commented Jun 27, 2020

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

@philsturgeon
Copy link
Contributor

philsturgeon commented Jul 7, 2020

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

@handrews
Copy link
Contributor

handrews commented Jul 7, 2020

@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
Copy link

kdebski85 commented Jul 31, 2020

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
Copy link
Member

MikeRalphson commented Jul 31, 2020

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.

@grossb1
Copy link

grossb1 commented Apr 22, 2021

Was curious about the status of #445

@MikeRalphson MikeRalphson unpinned this issue Apr 29, 2021
@MikeRalphson
Copy link
Member

MikeRalphson commented May 13, 2021

Closing in favour of #2572 - thanks @earth2marsh!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests