OAS30 strict validator

Author: p1c2u

README.rst

@@ -101,6 +101,57 @@ By default, the latest OpenAPI schema syntax is expected.
 
 For more details read about `Validation <https://openapi-schema-validator.readthedocs.io/en/latest/validation.html>`__.
 
+
+Strict vs Pragmatic Validators
+=============================
+
+OpenAPI 3.0 has two validator variants with different behaviors for binary format:
+
+**OAS30Validator (default - pragmatic)**
+   - Accepts Python ``bytes`` for ``type: string`` with ``format: binary``
+   - More lenient for Python use cases where binary data is common
+   - Use when validating Python objects directly
+
+**OAS30StrictValidator**
+   - Follows OAS spec strictly: only accepts ``str`` for ``type: string``
+   - For ``format: binary``, only accepts base64-encoded strings
+   - Use when strict spec compliance is required
+
+Comparison Matrix
+----------------
+
++----------------------+---------------------------+---------------------------+
+| Schema               | OAS30Validator (default) | OAS30StrictValidator     |
++======================+===========================+===========================+
+| ``type: string``    |                           |                           |
++----------------------+---------------------------+---------------------------+
+| ``"test"``          | Pass                      | Pass                      |
++----------------------+---------------------------+---------------------------+
+| ``b"test"``         | **Fail**                  | **Fail**                  |
++----------------------+---------------------------+---------------------------+
+| ``type: string``    |                           |                           |
+| ``format: binary``  |                           |                           |
++----------------------+---------------------------+---------------------------+
+| ``b"test"``         | Pass                      | **Fail**                  |
++----------------------+---------------------------+---------------------------+
+| ``"dGVzdA=="``      | Pass (valid base64)      | Pass (valid base64)       |
++----------------------+---------------------------+---------------------------+
+| ``"test"``          | Pass                      | **Fail** (not base64)     |
++----------------------+---------------------------+---------------------------+
+
+.. code-block:: python
+
+   from openapi_schema_validator import OAS30Validator, OAS30StrictValidator
+
+   # Pragmatic (default) - accepts bytes for binary format
+   validator = OAS30Validator({"type": "string", "format": "binary"})
+   validator.validate(b"binary data")  # passes
+
+   # Strict - follows spec precisely
+   validator = OAS30StrictValidator({"type": "string", "format": "binary"})
+   validator.validate(b"binary data")  # raises ValidationError
+
+
 Related projects
 ################
 * `openapi-core <https://github.com/python-openapi/openapi-core>`__

openapi_schema_validator/__init__.py

@@ -1,7 +1,9 @@
 from openapi_schema_validator._format import oas30_format_checker
+from openapi_schema_validator._format import oas30_strict_format_checker
 from openapi_schema_validator._format import oas31_format_checker
 from openapi_schema_validator.shortcuts import validate
 from openapi_schema_validator.validators import OAS30ReadValidator
+from openapi_schema_validator.validators import OAS30StrictValidator
 from openapi_schema_validator.validators import OAS30Validator
 from openapi_schema_validator.validators import OAS30WriteValidator
 from openapi_schema_validator.validators import OAS31Validator
@@ -15,9 +17,11 @@
 __all__ = [
     "validate",
     "OAS30ReadValidator",
+    "OAS30StrictValidator",
     "OAS30WriteValidator",
     "OAS30Validator",
     "oas30_format_checker",
+    "oas30_strict_format_checker",
     "OAS31Validator",
     "oas31_format_checker",
 ]

openapi_schema_validator/_format.py

@@ -44,11 +44,23 @@ def is_double(instance: object) -> bool:
     return isinstance(instance, float)
 
 
-def is_binary(instance: object) -> bool:
-    if not isinstance(instance, (str, bytes)):
-        return True
-    if isinstance(instance, str):
+def is_binary_strict(instance: object) -> bool:
+    # Strict: only accepts base64-encoded strings, not raw bytes
+    if isinstance(instance, bytes):
         return False
+    if isinstance(instance, str):
+        try:
+            b64decode(instance)
+            return True
+        except Exception:
+            return False
+    return True
+
+
+def is_binary_pragmatic(instance: object) -> bool:
+    # Pragmatic: accepts bytes (common in Python) or base64-encoded strings
+    if isinstance(instance, (str, bytes)):
+        return True
     return True
 
 
@@ -72,10 +84,21 @@ def is_password(instance: object) -> bool:
 oas30_format_checker.checks("int64")(is_int64)
 oas30_format_checker.checks("float")(is_float)
 oas30_format_checker.checks("double")(is_double)
-oas30_format_checker.checks("binary")(is_binary)
+oas30_format_checker.checks("binary")(is_binary_pragmatic)
 oas30_format_checker.checks("byte", (binascii.Error, TypeError))(is_byte)
 oas30_format_checker.checks("password")(is_password)
 
+oas30_strict_format_checker = FormatChecker()
+oas30_strict_format_checker.checks("int32")(is_int32)
+oas30_strict_format_checker.checks("int64")(is_int64)
+oas30_strict_format_checker.checks("float")(is_float)
+oas30_strict_format_checker.checks("double")(is_double)
+oas30_strict_format_checker.checks("binary")(is_binary_strict)
+oas30_strict_format_checker.checks("byte", (binascii.Error, TypeError))(
+    is_byte
+)
+oas30_strict_format_checker.checks("password")(is_password)
+
 oas31_format_checker = FormatChecker()
 oas31_format_checker.checks("int32")(is_int32)
 oas31_format_checker.checks("int64")(is_int64)

openapi_schema_validator/_keywords.py

@@ -115,6 +115,7 @@ def type(
     instance: Any,
     schema: Mapping[str, Any],
 ) -> Iterator[ValidationError]:
+    """Default type validator - allows Python bytes for binary format for pragmatic reasons."""
     if instance is None:
         # nullable implementation based on OAS 3.0.3
         # * nullable is only meaningful if its value is true
@@ -125,6 +126,34 @@ def type(
             return
         yield ValidationError("None for not nullable")
 
+    # Pragmatic: allow bytes for binary format (common in Python use cases)
+    if (
+        data_type == "string"
+        and schema.get("format") == "binary"
+        and isinstance(instance, bytes)
+    ):
+        return
+
+    if not validator.is_type(instance, data_type):
+        data_repr = repr(data_type)
+        yield ValidationError(f"{instance!r} is not of type {data_repr}")
+
+
+def strict_type(
+    validator: Any,
+    data_type: str,
+    instance: Any,
+    schema: Any,
+) -> Any:
+    """
+    Strict type validator - follows OAS spec precisely.
+    Does NOT allow Python bytes for binary format.
+    """
+    if instance is None:
+        if schema.get("nullable") is True:
+            return
+        yield ValidationError("None for not nullable")
+
     if not validator.is_type(instance, data_type):
         data_repr = repr(data_type)
         yield ValidationError(f"{instance!r} is not of type {data_repr}")

openapi_schema_validator/_types.py

@@ -11,7 +11,8 @@
 
 
 def is_string(checker: Any, instance: Any) -> bool:
-    return isinstance(instance, (str, bytes))
+    # Both strict and pragmatic: only accepts str for plain string type
+    return isinstance(instance, str)
 
 
 oas30_type_checker = TypeChecker(
@@ -27,4 +28,5 @@ def is_string(checker: Any, instance: Any) -> bool:
         },
     ),
 )
+
 oas31_type_checker = draft202012_type_checker

openapi_schema_validator/validators.py

@@ -3,6 +3,7 @@
 
 from jsonschema import _keywords
 from jsonschema import _legacy_keywords
+from jsonschema.exceptions import ValidationError
 from jsonschema.validators import Draft202012Validator
 from jsonschema.validators import create
 from jsonschema.validators import extend
@@ -13,6 +14,13 @@
 from openapi_schema_validator import _types as oas_types
 from openapi_schema_validator._types import oas31_type_checker
 
+
+def _oas30_id_of(schema: Any) -> str:
+    if isinstance(schema, dict):
+        return schema.get("id", "")  # type: ignore[no-any-return]
+    return ""
+
+
 OAS30_VALIDATORS = cast(
     Any,
     {
@@ -55,6 +63,11 @@
     },
 )
 
+
+OAS30_VALIDATORS_STRICT = dict(OAS30_VALIDATORS)
+OAS30_VALIDATORS_STRICT["type"] = oas_keywords.strict_type
+
+
 OAS30Validator = create(
     meta_schema=SPECIFICATIONS.contents(
         "http://json-schema.org/draft-04/schema#",
@@ -65,11 +78,23 @@
     # NOTE: version causes conflict with global jsonschema validator
     # See https://github.com/python-openapi/openapi-schema-validator/pull/12
     # version="oas30",
-    id_of=lambda schema: (
-        schema.get("id", "") if isinstance(schema, dict) else ""
-    ),
+    id_of=_oas30_id_of,
 )
 
+
+OAS30StrictValidator = extend(
+    OAS30Validator,
+    validators={
+        "type": oas_keywords.strict_type,
+    },
+    type_checker=oas_types.oas30_type_checker,
+    format_checker=oas_format.oas30_strict_format_checker,
+    # NOTE: version causes conflict with global jsonschema validator
+    # See https://github.com/python-openapi/openapi-schema-validator/pull/12
+    # version="oas30-strict",
+)
+
+
 OAS30ReadValidator = extend(
     OAS30Validator,
     validators={

tests/integration/test_validators.py

@@ -15,10 +15,12 @@
 from referencing.jsonschema import DRAFT202012
 
 from openapi_schema_validator import OAS30ReadValidator
+from openapi_schema_validator import OAS30StrictValidator
 from openapi_schema_validator import OAS30Validator
 from openapi_schema_validator import OAS30WriteValidator
 from openapi_schema_validator import OAS31Validator
 from openapi_schema_validator import oas30_format_checker
+from openapi_schema_validator import oas30_strict_format_checker
 from openapi_schema_validator import oas31_format_checker
 
 
@@ -187,7 +189,6 @@ def test_oas30_formats_ignored(
 
         assert result is None
 
-    @pytest.mark.xfail(reason="OAS 3.0 string type checker allows byte")
     @pytest.mark.parametrize("value", [b"test"])
     def test_string_disallow_binary(self, validator_class, value):
         schema = {"type": "string"}
@@ -205,7 +206,7 @@ def test_string_binary_valid(self, validator_class, format_checker, value):
 
         assert result is None
 
-    @pytest.mark.parametrize("value", ["test", True, 3, 3.12, None])
+    @pytest.mark.parametrize("value", [True, 3, 3.12, None])
     def test_string_binary_invalid(
         self, validator_class, format_checker, value
     ):
@@ -282,7 +283,6 @@ def test_nullable_enum_with_none(self, validator_class):
     @pytest.mark.parametrize(
         "value",
         [
-            b64encode(b"string"),
             b64encode(b"string").decode(),
         ],
     )
@@ -296,7 +296,7 @@ def test_string_format_byte_valid(self, validator_class, value):
 
         assert result is None
 
-    @pytest.mark.parametrize("value", ["string", b"string"])
+    @pytest.mark.parametrize("value", ["string"])
     def test_string_format_byte_invalid(self, validator_class, value):
         schema = {"type": "string", "format": "byte"}
         validator = validator_class(
@@ -1001,3 +1001,53 @@ def test_array_prefixitems_invalid(self, validator_class, value):
             "Expected at most 4 items but found 1 extra",
         ]
         assert any(error in str(excinfo.value) for error in errors)
+
+
+class TestOAS30StrictValidator:
+    """
+    Tests for OAS30StrictValidator which follows OAS spec strictly:
+    - type: string only accepts str (not bytes)
+    - format: binary also only accepts str (no special bytes handling)
+    """
+
+    def test_strict_string_rejects_bytes(self):
+        """Strict validator rejects bytes for plain string type."""
+        schema = {"type": "string"}
+        validator = OAS30StrictValidator(schema)
+
+        with pytest.raises(ValidationError):
+            validator.validate(b"test")
+
+    def test_strict_string_accepts_str(self):
+        """Strict validator accepts str for string type."""
+        schema = {"type": "string"}
+        validator = OAS30StrictValidator(schema)
+
+        result = validator.validate("test")
+        assert result is None
+
+    def test_strict_binary_format_rejects_bytes(self):
+        """Strict validator rejects bytes even with binary format."""
+        schema = {"type": "string", "format": "binary"}
+        validator = OAS30StrictValidator(
+            schema, format_checker=oas30_format_checker
+        )
+
+        with pytest.raises(ValidationError):
+            validator.validate(b"test")
+
+    def test_strict_binary_format_rejects_str(self):
+        """
+        Strict validator with binary format rejects strings.
+        Binary format is for bytes in OAS, not plain strings.
+        """
+        schema = {"type": "string", "format": "binary"}
+        validator = OAS30StrictValidator(
+            schema, format_checker=oas30_strict_format_checker
+        )
+
+        # Binary format expects actual binary data (bytes in Python)
+        # Plain strings fail format validation because they are not valid base64
+        # Note: "test" is actually valid base64, so use "not base64" which is not
+        with pytest.raises(ValidationError, match="is not a 'binary'"):
+            validator.validate("not base64")