inconsistency between documentation and spec: is paths required?

[karenetheridge]

in https://github.com/OAI/Documentation/blob/main/specification-structure.md:

The root object in any OpenAPI document is the OpenAPI Object and only three of its fields are mandatory: openapi, info and paths.

But the schema (https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.yaml) says:

anyOf:
  - required:
    - paths
  - required:
    - components
  - required:
    - webhooks

Which one is correct?

[webron]

Neither of those is the specification. Not sure if the Documentation was updated to OAS 3.1 but the section you're referring to is true in OAS 3.0 but changed in OAS 3.1. The snippet from the schema is true to OAS 3.1.

[karenetheridge]

I also noticed that on the next page, https://oai.github.io/Documentation/specification-paths.html, says that "responses" is mandatory in the operations object, neither the spec nor the schema contain this constraint.

Have these doc pages been updated for v3.0.3->v3.1.0?

[webron]

Apparently, they've not been. As always, the source of truth is always the specs. For reference, https://spec.openapis.org/oas/v3.1.0.html and https://spec.openapis.org/oas/v3.0.0.html (or just https://github.com/OAI/OpenAPI-Specification/tree/main/versions).

[MikeRalphson]

Thanks for pointing this out @karenetheridge - do you have bandwidth to raise a PR to fix these issues? If not, I can.

[karenetheridge]

I can PR it this weekend.