Fix 3.1 Path Item schema #3355
Fix 3.1 Path Item schema #3355
Conversation
Path Item Objects allow "$ref", and despite the syntactic overlap, it is neither accurate nor semantically meaningful to parse a Path Item Object as a Reference Object, even if such parsing would be successful.
|
Thank you for this. But is this really the first actual PR we've seen for this? (sincere question) It's been talked about as an issue for years. |
|
@karenetheridge I didn't notice another one ¯\(ツ)/¯ |
|
I noticed that |
|
That's correct. Before publishing a new version of the Schema we generate the json from the yaml version. |
|
Okay just ran into a customer using Its just the json schema here: https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/schema.json#L294 being But this PR and the discussion around it seems to be removing the ability to use references for path items, is that correct? Should I go back to the customer and tell them what they are doing isn't valid even though the documentation states otherwise? Will the documentation be updated as part of this PR? The use-case the customer has seems totally valid (individual teams manage different endpoints that are documented in different documents and they are trying to pull it all together into one document via the references), what would someone do to organize their document in this distributed manner if this feature goes away? |
|
@TristanSpeakEasy apologies for the delay in replying, I lost track of stuff during the holiday season. This is not changing anything about the specification. The schema is not normative (meaning it does not have the force of the spec itself), so nothing changed in the schema impacts the spec. This PR is confusing because Path Item's |
Schemathesis uses static version of the current published version of the OpenApi 3.1 spec metaschema (https://spec.openapis.org/oas/3.1/schema/2022-10-07) to validate openapi 3.1 spec documents. Unfortunately, the published version has at least one known bug in which the schema for `paths` references the definition of a concrete `path-item` instead of `path-item-or-reference`, which might still be technically incorrect when it comes handling the case of ref and sibling fields, but is correct according to the documented definition of a pathItemObject. This oversight has been noticed multiple times OAI/OpenAPI-Specification#3298 OAI/OpenAPI-Specification#2635 (comment) OAI/OpenAPI-Specification#2635 (comment) OAI/OpenAPI-Specification#3513 OAI/OpenAPI-Specification#2657 (comment) And finally fixed in Feb 2024 OAI/OpenAPI-Specification#3355 with a slightly bigger rework of the pathItem schema. Sadly, due to confusion about how to release fixes in schemas OAI/OpenAPI-Specification#151 (comment) this change has not been published anywhere except schema.yaml in the git repo, not even in schema.json, which appearantly only gets refreshed once per release of the metaschema OAI/OpenAPI-Specification#3355 (comment) This commit updates the stored schema from the most up-to-date 3.1.0 schema.yaml from 0035208 to close the bug and make spec-valid openapi spec files that use $ref under path finally validate correctly in schemathesis. It also adds a corresponding regression test
Fixes #2635 (schema aspects, not spec aspects); fixes #3298
Path Item Objects allow "$ref", and despite the syntactic overlap, it is neither accurate nor semantically meaningful to parse a Path Item Object as a Reference Object, even if such parsing would be successful.