OpenAPI v3.1 Support

[philsturgeon]

Hey there, I help maintain two tools which use this package: Spectral and Prism.

Both are looking to update OAS support to OpenAPI v3.1, and to do that changes to this package will be required.

I'll be happy to help out, I just wanted to start the conversation somewhere. First and foremost, how do we go about supporting both OAS 3.0 and 3.1 in the same package, because there's some breaking changes in there.

[amazing-gao]

Hi, I have not read the 3.x specifications totally, but I will read it late.
In order to adapt to the breaking changes, we can publish a new version eg: 2.0.
Do you have any idea?

[philsturgeon]

That would be possible, and then people could use 1.x for OAS3.0 and 2.x for OAS3.1, but that makes life tricky for tooling that is trying to support both OAS3.0 and OAS3.1 at the same time.

I think there's going to be a fair bit of tooling around which only uses this dependency, so it might be a good place to try and buffer out this awkard difference.

One thing I've been playing with is converting the old OpenAPI schema.json used here up to draft 2019-09, so that I can use AJV v7 for both OAS3.0 and OAS3.1. This is a bit of a hack but does seem to work...

I know there's a lot to sift through in this PR, but I've basically done this already if you'd like to take a look.

https://github.com/stoplightio/spectral/pull/1399/files

Then its just a case of adding a few more format validators and working out which to use, and making them off by default as OAS3.1 does not recommend validating format by default anymore.

[philsturgeon]

Oh btw the OAS 3.1 schema is being worked on over here, it's not quite right yet but will be soon. OAI/OpenAPI-Specification#2474

[amazing-gao]

This is a hack way indeed. I find another way to use different version ajvs. It is more elegant.

npm install <alias>@npm:<name>:

Install a package under a custom alias. Allows multiple versions of a same-name package side-by-side, more convenient 
import names for packages with otherwise long ones and using git forks replacements or forked npm packages as 
replacements. Aliasing works only on your project and does not rename packages in transitive dependencies. Aliases 
should follow the naming conventions stated in validate-npm-package-name.

npm install ajv6@npm:[email protected]
npm install ajv7@npm:ajv@7

So, we can use two versions ajv like this.

  "dependencies": {
    "ajv6": "npm:ajv@^6.10.2",
    "ajv7": "npm:ajv@^7.1.1",
    "decimal.js": "^10.2.0"
  },

const Ajv6 = require('ajv6')
const Ajv7 = require('ajv7').default

What do you think of this method?

[philsturgeon]

Yeah i went down that road in a throwaway branch and threw it away. 1. It increases the bundle size a fair bit 2. The api is quite different so you need to write abstractions 3. The amount of work is more than converting the OpenAPI schema. The author of AJV also wrote https://github.com/ajv-validator/json-schema-migrate and the output seems pretty good, so it seems like the lesser of two hacks IMHO. Please give it a try and see what conclusion you get to! Maybe you find a more elegant way to implement the dual version approach.

…

On Mon, Feb 22, 2021 at 12:03, Gao ***@***.***> wrote: This is a hack way indeed. I find another way to use different version ajvs. It is more elegant. npm install ***@***.***:<name>: Install a package under a custom alias. Allows multiple versions of a same-name package side-by-side, more convenient import names for packages with otherwise long ones and using git forks replacements or forked npm packages as replacements. Aliasing works only on your project and does not rename packages in transitive dependencies. Aliases should follow the naming conventions stated in validate-npm-package-name. npm install ***@***.******@***.*** npm install ***@***.******@***.*** So, we can use two versions ajv like this. " dependencies " : { " ajv6 " : " npm:ajv@^6.10.2 " , " ajv7 " : " npm:ajv@^7.1.1 " , " decimal.js " : " ^10.2.0 " }, const Ajv6 = require ( 'ajv6' ) const Ajv7 = require ( 'ajv7' ) . default What do you think of this method? — You are receiving this because you authored the thread. Reply to this email directly, [view it on GitHub](#11 (comment)), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/AAAQONLN3DO7FMNC7VDQQCLTAJBYJANCNFSM4XYUNZ2A).

[amazing-gao]

It looks like good, I will try it.

[amazing-gao]

@philsturgeon I make a PR #12.

There is something changed:

1. Minimum node version change to 10
2. Ajv upgrade to v7
3. Option metaSchema removed
4. Option coerceTypes default value change to false
5. Add oasVer option to select OAS 3.0 or 3.1

You can take oas31.test.js#L5-L17 as reference. Can this satisfy you?

[philsturgeon]

I might just be a bit confused from working on 324897 things at once but I thought you would need the meta schema that is still under development OAI/OpenAPI-Specification#2489.

How would this package know how to validate nullable or type: null, or any of the other big changes between the two versions?