Document intentional OAS 3.1 format compatibility behavior

docs/unmarshalling.md

@@ -17,6 +17,10 @@ Openapi-core comes with a set of built-in format unmarshallers:
 - `uuid` - converts a string into a UUID object,
 - `byte` - decodes a Base64-encoded string.
 
+!!! note
+
+    For backward compatibility, OpenAPI 3.1 unmarshalling in openapi-core currently supports `byte` and `binary` format handling.
+
 You can also define your own format unmarshallers (See [Extra Format Unmarshallers](configuration.md#extra-format-unmarshallers)).
 
 ## Request unmarshalling

docs/validation.md

@@ -13,6 +13,10 @@ Such valid formats can be further unmarshalled (See [Unmarshalling](unmarshallin
 
 Depending on the OpenAPI version, openapi-core comes with a set of built-in format validators such as: `date`, `date-time`, `binary`, `uuid`, or `byte`.
 
+!!! note
+
+    For backward compatibility, OpenAPI 3.1 validation in openapi-core currently accepts OpenAPI 3.0-style format checker behavior, including `byte` and `binary`.
+
 You can also define your own format validators (See [Extra Format Validators](configuration.md#extra-format-validators)).
 
 ## Request validation

openapi_core/unmarshalling/schemas/__init__.py

@@ -76,6 +76,9 @@
     "uuid": format_uuid,
     "byte": format_byte,
 }
+# NOTE: Intentionally reuse OAS 3.0 format unmarshallers for OAS 3.1/3.2
+# to preserve backward compatibility for `byte`/`binary` formats.
+# See https://github.com/python-openapi/openapi-core/issues/506
 oas31_format_unmarshallers = oas30_format_unmarshallers
 oas32_format_unmarshallers = oas31_format_unmarshallers
 

openapi_core/validation/schemas/__init__.py

@@ -41,7 +41,8 @@
     Proxy(
         partial(build_strict_additional_properties_validator, OAS31Validator)
     ),
-    # FIXME: OpenAPI 3.1 schema validator uses OpenAPI 3.0 format checker.
+    # NOTE: Intentionally use OAS 3.0 format checker for OAS 3.1 to preserve
+    # backward compatibility for `byte`/`binary` formats.
     # See https://github.com/python-openapi/openapi-core/issues/506
     format_checker=OAS30ReadValidator.FORMAT_CHECKER,
 )

tests/integration/unmarshalling/test_unmarshallers.py

@@ -1964,7 +1964,8 @@ def unmarshallers_factory(self):
 
     @pytest.mark.xfail(
         reason=(
-            "OpenAPI 3.1 schema validator uses OpenAPI 3.0 format checker."
+            "Intentional backward compatibility: OAS 3.1 currently uses "
+            "OAS 3.0-style format checker behavior in openapi-core. "
             "See https://github.com/python-openapi/openapi-core/issues/506"
         ),
         strict=True,