search

Redocly / redocly-cli

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
https://redocly.com/docs/cli/
MIT License
849 stars 129 forks source link

bug: inconsistent types for OAS3_1 schemas #1548

Open jeremyfiel opened 1 month ago

jeremyfiel commented 1 month ago

https://github.com/Redocly/redocly-cli/blob/f11ebcbe1349c5593fbd40ca14259ff432a04b5a/packages/core/src/typings/openapi.ts#L160-L164

https://github.com/Redocly/redocly-cli/blob/f11ebcbe1349c5593fbd40ca14259ff432a04b5a/packages/core/src/types/oas3_1.ts#L90-L185

Should these two separate typings be refactored to use only one of them across the core package? The openapi.ts typing does not include the unevaluated* keywords required for OAS 3.1.x /JSON Schema 2020-12 schemas.

I think this relates to https://github.com/Redocly/redocly-cli/issues/1546 where an unexpected keyword is throwing an error, but it is indeed valid for JSON Schema 2020-12 schemas to define any arbitrary properties.

In the previous version of OpenAPI 3.0.x, the schema object was strictly defined as a superset and subset of a JSON Schema draft-04 schema, and thus not all JSON Schema related behaviors applied. The interface design of OAS3_1Schema does not allow arbitrary properties.

tatomyr commented 1 month ago

Good question. They are somewhat different as the first one is using for the code typing while the second one is for an OAS description typing. Ideally they should be synchronised, but I cannot come up with a reliable solution to enforce that.