OAS 3.1 - arbitrary schema keywords are classified as lint errors

[Drew-Kimberly]

Describe the bug For OAS 3.1, arbitrary keywords within schemas produce lint errors. This contradicts the 3.1 specification.

To Reproduce Using minimal, this example spec from OpenAPI fails linting when it should pass.

Expected behavior

The spec should pass linting.

Logs

message: 'Property `myArbitraryKeyword` is not expected here.',

OpenAPI description

3.1

Redocly Version(s)

@redocly/[email protected]

[tatomyr]

Interesting. I didn't know arbitrary keys are allowed in Schema Objects. Could you share where exactly in the specification this is mentioned? Anyway, I'm not sure if it makes sense to allow arbitrary properties in the Schema Object when linting OAS descriptions, as it makes it harder to detect typos and other mistakes.

[Drew-Kimberly]

@tatomyr Thanks for the quick response! Here's the ref from the spec.

Typos would still be detected in most cases since schema definitions would be missing required properties. Obviously my preference here is that ReDocly strictly adheres to the specification by default 🙏 (rules can always toggle certain behaviors)

[tatomyr]

Thanks for the link @Drew-Kimberly!

I'm still not sure if we want to change the behaviour. Let's wait until we get more votes for that.

Meanwhile, you can tweak the behaviour by supplying the type extension via a plugin. I understand it won't change the default settings but most users don't need those additional keys (or they can use specification extensions instead; BTW, could the specification extension cover your case?).

[MorelSerge]

This is currently breaking for mere on a property that has a nullable defined:

"confirmedAt": {
  "type": "string",
  "description": "something something",
  "nullable": true,
  "example": "2024-07-01T14:00:00Z"
}

[lornajane]

I am not in support of changing the default behaviour because I think it works well for the majority but I can see the point that these are valid descriptions. The approach of using type extensions (especially if you use a few known keywords) is a very good workaround in the short term. However we should figure out a way to add a rule that relaxes these checks, so users can easily choose the behaviour that's right for them.

@MorelSerge thanks for the example, since nullable is a 3.0 feature, the linter will flag it if you use it in OpenAPI 3.1 descriptions. Again, you can use a type extension to work around this for now while we look at the options.