fix(oas3.1): correctly validate paths using $ref

BronzeDeer · BronzeDeer · commit 4eac10fe40cf · 2024-10-05T01:43:26.000+02:00
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
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -6,6 +6,9 @@ Changelog
 
 .. _v3.36.2:
 
+**Fixed**
+- OpenApi3.1 spec using $ref in a path is incorrectly validated as invalid
+
 :version:`3.36.2 <v3.36.1...v3.36.2>` - 2024-09-26
 --------------------------------------------------
 
diff --git a/src/schemathesis/specs/openapi/definitions.py b/src/schemathesis/specs/openapi/definitions.py
@@ -1330,6 +1330,8 @@
         },
     },
 }
+# Generated from the updated schema.yaml from 0035208, which includes unpublished bugfixes
+# https://github.com/OAI/OpenAPI-Specification/blob/0035208611701b4f7f2c959eb99a8725cca41e6e/schemas/v3.1/schema.yaml
 OPENAPI_31 = {
     "$id": "https://spec.openapis.org/oas/3.1/schema/2022-10-07",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -1345,7 +1347,7 @@
         },
         "servers": {"type": "array", "items": {"$ref": "#/$defs/server"}, "default": [{"url": "/"}]},
         "paths": {"$ref": "#/$defs/paths"},
-        "webhooks": {"type": "object", "additionalProperties": {"$ref": "#/$defs/path-item-or-reference"}},
+        "webhooks": {"type": "object", "additionalProperties": {"$ref": "#/$defs/path-item"}},
         "components": {"$ref": "#/$defs/components"},
         "security": {"type": "array", "items": {"$ref": "#/$defs/security-requirement"}},
         "tags": {"type": "array", "items": {"$ref": "#/$defs/tag"}},
@@ -1400,7 +1402,7 @@
             "$comment": "https://spec.openapis.org/oas/v3.1.0#server-object",
             "type": "object",
             "properties": {
-                "url": {"type": "string", "format": "uri-reference"},
+                "url": {"type": "string"},
                 "description": {"type": "string"},
                 "variables": {"type": "object", "additionalProperties": {"$ref": "#/$defs/server-variable"}},
             },
@@ -1439,7 +1441,7 @@
                 },
                 "links": {"type": "object", "additionalProperties": {"$ref": "#/$defs/link-or-reference"}},
                 "callbacks": {"type": "object", "additionalProperties": {"$ref": "#/$defs/callbacks-or-reference"}},
-                "pathItems": {"type": "object", "additionalProperties": {"$ref": "#/$defs/path-item-or-reference"}},
+                "pathItems": {"type": "object", "additionalProperties": {"$ref": "#/$defs/path-item"}},
             },
             "patternProperties": {
                 "^(schemas|responses|parameters|examples|requestBodies|headers|securitySchemes|links|callbacks|pathItems)$": {
@@ -1461,6 +1463,7 @@
             "$comment": "https://spec.openapis.org/oas/v3.1.0#path-item-object",
             "type": "object",
             "properties": {
+                "$ref": {"type": "string", "format": "uri-reference"},
                 "summary": {"type": "string"},
                 "description": {"type": "string"},
                 "servers": {"type": "array", "items": {"$ref": "#/$defs/server"}},
@@ -1477,11 +1480,6 @@
             "$ref": "#/$defs/specification-extensions",
             "unevaluatedProperties": False,
         },
-        "path-item-or-reference": {
-            "if": {"type": "object", "required": ["$ref"]},
-            "then": {"$ref": "#/$defs/reference"},
-            "else": {"$ref": "#/$defs/path-item"},
-        },
         "operation": {
             "$comment": "https://spec.openapis.org/oas/v3.1.0#operation-object",
             "type": "object",
@@ -1542,7 +1540,6 @@
                             "if": {"properties": {"in": {"const": "path"}}, "required": ["in"]},
                             "then": {
                                 "properties": {
-                                    "name": {"pattern": "[^/#?]+$"},
                                     "style": {"default": "simple", "enum": ["matrix", "label", "simple"]},
                                     "required": {"const": True},
                                 },
@@ -1662,7 +1659,7 @@
             "$comment": "https://spec.openapis.org/oas/v3.1.0#callback-object",
             "type": "object",
             "$ref": "#/$defs/specification-extensions",
-            "additionalProperties": {"$ref": "#/$defs/path-item-or-reference"},
+            "additionalProperties": {"$ref": "#/$defs/path-item"},
         },
         "callbacks-or-reference": {
             "if": {"type": "object", "required": ["$ref"]},
@@ -1755,7 +1752,6 @@
                 "summary": {"type": "string"},
                 "description": {"type": "string"},
             },
-            "unevaluatedProperties": False,
         },
         "schema": {
             "$comment": "https://spec.openapis.org/oas/v3.1.0#schema-object",
diff --git a/test/experimental/test_openapi_3_1.py b/test/experimental/test_openapi_3_1.py
@@ -83,3 +83,19 @@ def test_openapi_3_1_schema_validation():
     }
     with pytest.raises(SchemaError):
         from_dict(raw_schema, validate_schema=True, force_schema_version="30")
+
+
+def test_openapi_3_1_regression_path_ref():
+    OPEN_API_3_1.enable()
+    raw_schema = {
+        "openapi": "3.1.0",
+        "info": {"title": "Test correct validation of spec using $ref in pathItem", "version": "0.0.1"},
+        "paths": {
+            "/foo": {
+                "get": {"summary": "dummy", "operationId": "dummy", "responses": {"200": {"description": "Success"}}}
+            },
+            "/bar": {"$ref": "#/paths/~1bar"},
+        },
+    }
+
+    from_dict(raw_schema,validate_schema=True)
