Align pattern error behavior with jsonschema validation paths

Author: p1c2u

docs/validation.rst

@@ -127,6 +127,22 @@ In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` inste
 
    validate({"name": "John", "age": None}, schema, cls=OAS30Validator)
 
+Schema errors vs instance errors
+-------------------------------
+
+The high-level ``validate(...)`` helper checks schema validity before instance
+validation, following ``jsonschema.validate(...)`` behavior.
+Malformed schema values (for example an invalid regex in ``pattern`` like
+``\z``) raise ``SchemaError``.
+
+If you instantiate a validator class directly and call ``.validate(...)``,
+schema checking is not performed automatically, matching
+``jsonschema`` validator-class behavior.
+For malformed regex patterns this may raise a lower-level regex error.
+
+Use ``<ValidatorClass>.check_schema(schema)`` first when you need deterministic
+schema-validation errors with direct validator usage.
+
 Read/write context
 ------------------
 

openapi_schema_validator/shortcuts.py

@@ -19,7 +19,13 @@ def validate(
     **kwargs: Any
 ) -> None:
     """
-    Validate an instance against a given schema using the specified validator class.
+    Validate an instance against a given schema using the specified
+    validator class.
+
+    Unlike direct ``Validator(schema).validate(instance)`` usage, this helper
+    checks schema validity first.
+    Invalid schemas therefore raise ``SchemaError`` before any instance
+    validation occurs.
     """
     schema_dict = cast(dict[str, Any], schema)
 

tests/integration/test_validators.py

@@ -1,3 +1,4 @@
+import re
 import warnings
 from base64 import b64encode
 from typing import Any
@@ -30,6 +31,7 @@
 from openapi_schema_validator import oas30_strict_format_checker
 from openapi_schema_validator import oas31_format_checker
 from openapi_schema_validator import oas32_format_checker
+from openapi_schema_validator import validate
 from openapi_schema_validator._dialects import OAS31_BASE_DIALECT_ID
 from openapi_schema_validator._dialects import OAS31_BASE_DIALECT_METASCHEMA
 from openapi_schema_validator._dialects import OAS32_BASE_DIALECT_ID
@@ -124,6 +126,21 @@ def test_string_invalid(self, validator_class, value):
         with pytest.raises(ValidationError):
             validator.validate(value)
 
+    def test_invalid_pattern_raises_regex_error(self, validator_class):
+        schema = {"type": "string", "pattern": r"^foo\z"}
+        validator = validator_class(schema)
+
+        with pytest.raises(re.error, match=r"bad escape \\z"):
+            validator.validate("foo")
+
+    def test_invalid_pattern_rejected_by_validate_helper(
+        self, validator_class
+    ):
+        schema = {"type": "string", "pattern": r"^foo\z"}
+
+        with pytest.raises(SchemaError, match="is not a 'regex'"):
+            validate("foo", schema, cls=validator_class)
+
     def test_referencing(self, validator_class):
         name_schema = Resource.from_contents(
             {