Unsupported keywords rule support

[DerkSchooltink]

When composing JSON schema's for OpenAPI 3 definitions, you have to keep in mind that there are keywords that you used to use in schemas are no longer supported (OAS3 keywords):

• $schema
• additionalItems
• const
• contains
• dependencies
• id,
• $id
• patternProperties
• propertyNames

While this does not break the OpenAPI specifications, I would suggest that using these keywords is frowned upon and should only be used when you absolutely have to (mid-migration, regression issues, etc...).

Keeping this info in mind, I would like to suggest a rule in the openapi-validator that checks all schema's attached to a OAS3 definition for the existence of these properties. Based on the severity for this rule you could issue a warning, error or info to the user. By default I think this should be a warning, as it is not explicitly forbidden to use them.

If this feature is deemed as a viable addition to this tool I am able to get going on a pull request. I'm curious if there's support and if anyone has valuable additions to this discussion I'll be glad to hear it!

[mkistler]

This does look like a valuable addition. Now that we have support for Spectral custom rules, I think the best approach would be to implement this as a Spectral rule, which automatically makes it configurable by users. We would welcome a PR along these lines.

[toastyblast]

After reading your suggestion and becoming curious if OAS 3 treats these unsupported keywords as just warnings, I fiddled around a bit with them.
Upon checking how the official online Swagger Editor responds to the addition of these now unsupported keywords found on OAS 3's documentation it seems OAS itself throws hard errors, not warnings, upon the inclusion of these unsupported keywords in any schemas.

However, it seems it does not treat these in a special manner. From what I could gather, it throws the exact same behaviour for bogus keywords (i.e. something like "notARealProperty": true). This leads me to believe that there are no special checks for these previously supported, now unsupported keywords, and instead they are treated the same as these bogus keywords (a.k.a. it's either a supported keyword, or it's an error - There is no middle ground).

Still, to me this seems that OAS 3's stance is that unsupported keywords are hard errors, and shouldn't just be warnings, as you initially suggested. I cannot find mention of this in their documentation, however.

[barrett-schonefeld]

However, it seems it does not treat these in a special manner. From what I could gather, it throws the exact same behaviour for bogus keywords (i.e. something like "notARealProperty": true).

Based on this behavior, the introduction of the oas3-schema rule should resolve this issue because it validates the given OpenAPI definition against the OpenAPI spec and errors for invalid properties.

Closing this issue as it is covered by Spectral's oas3-schema rule.