Response Properties Policy

p1c2u · p1c2u · commit 46b9e80b6248 · 2026-03-04T20:36:48.000Z
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -153,18 +153,18 @@ When strict mode is enabled:
 - object schema with omitted `additionalProperties` rejects unknown fields
 - object schema with `additionalProperties: true` still allows unknown fields
 
-## Strict Response Properties
+## Response Properties Policy
 
 By default, OpenAPI follows JSON Schema behavior for `required`: response object properties are optional unless explicitly listed in `required`.
 
-If you want stricter response checks, enable `strict_response_properties`. In this mode, response object schemas are validated as if all documented properties were required, except properties marked as `writeOnly`.
+If you want stricter response checks, change `response_properties_default_policy` to `required`. In this mode, response object schemas are validated as if all documented properties were required (except properties marked as `writeOnly` in OpenAPI 3.0).
 
 ``` python hl_lines="4"
 from openapi_core import Config
 from openapi_core import OpenAPI
 
 config = Config(
-    strict_response_properties=True,
+    response_properties_default_policy="required",
 )
 openapi = OpenAPI.from_file_path('openapi.json', config=config)
 ```
diff --git a/openapi_core/app.py b/openapi_core/app.py
@@ -447,7 +447,8 @@ def response_validator(self) -> ResponseValidator:
             extra_format_validators=self.config.extra_format_validators,
             extra_media_type_deserializers=self.config.extra_media_type_deserializers,
             strict_additional_properties=self.config.strict_additional_properties,
-            strict_response_properties=self.config.strict_response_properties,
+            enforce_properties_required=self.config.response_properties_default_policy
+            == "required",
         )
 
     @cached_property
@@ -485,7 +486,8 @@ def webhook_response_validator(self) -> WebhookResponseValidator:
             extra_format_validators=self.config.extra_format_validators,
             extra_media_type_deserializers=self.config.extra_media_type_deserializers,
             strict_additional_properties=self.config.strict_additional_properties,
-            strict_response_properties=self.config.strict_response_properties,
+            enforce_properties_required=self.config.response_properties_default_policy
+            == "required",
         )
 
     @cached_property
@@ -525,7 +527,8 @@ def response_unmarshaller(self) -> ResponseUnmarshaller:
             extra_format_validators=self.config.extra_format_validators,
             extra_media_type_deserializers=self.config.extra_media_type_deserializers,
             strict_additional_properties=self.config.strict_additional_properties,
-            strict_response_properties=self.config.strict_response_properties,
+            enforce_properties_required=self.config.response_properties_default_policy
+            == "required",
             schema_unmarshallers_factory=self.config.schema_unmarshallers_factory,
             extra_format_unmarshallers=self.config.extra_format_unmarshallers,
         )
@@ -567,7 +570,8 @@ def webhook_response_unmarshaller(self) -> WebhookResponseUnmarshaller:
             extra_format_validators=self.config.extra_format_validators,
             extra_media_type_deserializers=self.config.extra_media_type_deserializers,
             strict_additional_properties=self.config.strict_additional_properties,
-            strict_response_properties=self.config.strict_response_properties,
+            enforce_properties_required=self.config.response_properties_default_policy
+            == "required",
             schema_unmarshallers_factory=self.config.schema_unmarshallers_factory,
             extra_format_unmarshallers=self.config.extra_format_unmarshallers,
         )
diff --git a/openapi_core/configurations.py b/openapi_core/configurations.py
@@ -38,7 +38,7 @@ class Config(UnmarshallerConfig):
         response_unmarshaller_cls: Response unmarshaller class.
         webhook_request_unmarshaller_cls: Webhook request unmarshaller class.
         webhook_response_unmarshaller_cls: Webhook response unmarshaller class.
-        strict_response_properties: If true, require documented response
+        response_properties_default_policy: If true, require documented response
             properties (except writeOnly properties) in response validation and
             unmarshalling.
     """
diff --git a/openapi_core/unmarshalling/response/protocols.py b/openapi_core/unmarshalling/response/protocols.py
@@ -56,7 +56,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
         schema_unmarshallers_factory: Optional[
             SchemaUnmarshallersFactory
         ] = None,
@@ -93,7 +93,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
         schema_unmarshallers_factory: Optional[
             SchemaUnmarshallersFactory
         ] = None,
diff --git a/openapi_core/unmarshalling/schemas/factories.py b/openapi_core/unmarshalling/schemas/factories.py
@@ -39,7 +39,7 @@ def create(
         extra_format_validators: Optional[FormatValidatorsDict] = None,
         extra_format_unmarshallers: Optional[FormatUnmarshallersDict] = None,
         strict_additional_properties: bool = False,
-        require_all_properties: bool = False,
+        enforce_properties_required: bool = False,
     ) -> SchemaUnmarshaller:
         """Create unmarshaller from the schema."""
         if schema is None:
@@ -55,7 +55,7 @@ def create(
             format_validators=format_validators,
             extra_format_validators=extra_format_validators,
             strict_additional_properties=strict_additional_properties,
-            require_all_properties=require_all_properties,
+            enforce_properties_required=enforce_properties_required,
         )
 
         schema_format = (schema / "format").read_str(None)
diff --git a/openapi_core/unmarshalling/unmarshallers.py b/openapi_core/unmarshalling/unmarshallers.py
@@ -51,7 +51,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
         schema_unmarshallers_factory: Optional[
             SchemaUnmarshallersFactory
         ] = None,
@@ -76,7 +76,7 @@ def __init__(
             extra_format_validators=extra_format_validators,
             extra_media_type_deserializers=extra_media_type_deserializers,
             strict_additional_properties=strict_additional_properties,
-            strict_response_properties=strict_response_properties,
+            enforce_properties_required=enforce_properties_required,
         )
         self.schema_unmarshallers_factory = (
             schema_unmarshallers_factory or self.schema_unmarshallers_factory
@@ -94,7 +94,7 @@ def _unmarshal_schema(self, schema: SchemaPath, value: Any) -> Any:
             format_validators=self.format_validators,
             extra_format_validators=self.extra_format_validators,
             strict_additional_properties=self.strict_additional_properties,
-            require_all_properties=self.strict_response_properties,
+            enforce_properties_required=self.enforce_properties_required,
             format_unmarshallers=self.format_unmarshallers,
             extra_format_unmarshallers=self.extra_format_unmarshallers,
         )
diff --git a/openapi_core/validation/configurations.py b/openapi_core/validation/configurations.py
@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Literal
 from typing import Optional
 
 from openapi_core.casting.schemas.factories import SchemaCastersFactory
@@ -46,7 +47,7 @@ class ValidatorConfig:
         strict_additional_properties
             If true, treat schemas that omit additionalProperties as if
             additionalProperties: false.
-        strict_response_properties
+        response_properties_default_policy
             If true, response schema properties are treated as required during
             response validation/unmarshalling, except properties marked as
             writeOnly.
@@ -70,4 +71,6 @@ class ValidatorConfig:
         security_provider_factory
     )
     strict_additional_properties: bool = False
-    strict_response_properties: bool = False
+    response_properties_default_policy: Literal["optional", "required"] = (
+        "optional"
+    )
diff --git a/openapi_core/validation/response/protocols.py b/openapi_core/validation/response/protocols.py
@@ -48,7 +48,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
     ): ...
 
     def iter_errors(
@@ -86,7 +86,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
     ): ...
 
     def iter_errors(
diff --git a/openapi_core/validation/schemas/factories.py b/openapi_core/validation/schemas/factories.py
@@ -59,7 +59,7 @@ def create(
         format_validators: Optional[FormatValidatorsDict] = None,
         extra_format_validators: Optional[FormatValidatorsDict] = None,
         strict_additional_properties: bool = False,
-        require_all_properties: bool = False,
+        enforce_properties_required: bool = False,
     ) -> SchemaValidator:
         validator_class: type[Validator] = self.schema_validator_class
         if strict_additional_properties:
@@ -74,7 +74,7 @@ def create(
         )
         with schema.resolve() as resolved:
             schema_value = resolved.contents
-            if require_all_properties:
+            if enforce_properties_required:
                 schema_value = self._build_required_properties_schema(
                     schema_value
                 )
diff --git a/openapi_core/validation/validators.py b/openapi_core/validation/validators.py
@@ -65,7 +65,7 @@ def __init__(
             MediaTypeDeserializersDict
         ] = None,
         strict_additional_properties: bool = False,
-        strict_response_properties: bool = False,
+        enforce_properties_required: bool = False,
     ):
         self.spec = spec
         self.base_url = base_url
@@ -104,7 +104,7 @@ def __init__(
         self.extra_format_validators = extra_format_validators
         self.extra_media_type_deserializers = extra_media_type_deserializers
         self.strict_additional_properties = strict_additional_properties
-        self.strict_response_properties = strict_response_properties
+        self.enforce_properties_required = enforce_properties_required
 
     @cached_property
     def path_finder(self) -> BasePathFinder:
@@ -145,7 +145,7 @@ def _deserialise_media_type(
                 format_validators=self.format_validators,
                 extra_format_validators=self.extra_format_validators,
                 strict_additional_properties=self.strict_additional_properties,
-                require_all_properties=self.strict_response_properties,
+                enforce_properties_required=self.enforce_properties_required,
             )
         deserializer = self.media_type_deserializers_factory.create(
             mimetype,
@@ -177,7 +177,7 @@ def _validate_schema(self, schema: SchemaPath, value: Any) -> None:
             format_validators=self.format_validators,
             extra_format_validators=self.extra_format_validators,
             strict_additional_properties=self.strict_additional_properties,
-            require_all_properties=self.strict_response_properties,
+            enforce_properties_required=self.enforce_properties_required,
         )
         validator.validate(value)
 
diff --git a/tests/integration/unmarshalling/test_response_unmarshaller_response_properties_default_policy.py b/tests/integration/unmarshalling/test_response_unmarshaller_response_properties_default_policy.py
@@ -67,7 +67,7 @@ def test_response_unmarshal_default_allows_missing_optional_properties():
 
 
 def test_response_unmarshal_strict_rejects_missing_documented_properties():
-    config = Config(strict_response_properties=True)
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest("http://example.com", "get", "/resources")
     response = MockResponse(
@@ -83,7 +83,7 @@ def test_response_unmarshal_strict_rejects_missing_documented_properties():
 
 
 def test_response_unmarshal_strict_excludes_write_only_properties():
-    config = Config(strict_response_properties=True)
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest("http://example.com", "get", "/resources")
     response = MockResponse(
diff --git a/tests/integration/validation/test_response_properties_default_policy.py b/tests/integration/validation/test_response_properties_default_policy.py
@@ -88,7 +88,7 @@ def test_response_validation_default_allows_missing_optional_properties():
 
 
 def test_response_validation_strict_rejects_missing_documented_properties():
-    config = Config(strict_response_properties=True)
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest("http://example.com", "get", "/resources")
     response = MockResponse(
@@ -102,7 +102,7 @@ def test_response_validation_strict_rejects_missing_documented_properties():
 
 
 def test_response_validation_strict_allows_nullable_properties_when_present():
-    config = Config(strict_response_properties=True)
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest("http://example.com", "get", "/resources")
     response = MockResponse(
@@ -121,7 +121,7 @@ def test_response_validation_strict_allows_nullable_properties_when_present():
 
 
 def test_response_validation_strict_excludes_write_only_properties():
-    config = Config(strict_response_properties=True)
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest("http://example.com", "get", "/resources")
     response = MockResponse(
@@ -139,8 +139,8 @@ def test_response_validation_strict_excludes_write_only_properties():
     openapi.validate_response(request, response)
 
 
-def test_request_validation_ignores_strict_response_properties_flag():
-    config = Config(strict_response_properties=True)
+def test_request_validation_ignores_response_properties_default_policy_flag():
+    config = Config(response_properties_default_policy="required")
     openapi = OpenAPI.from_dict(_spec_dict(), config=config)
     request = MockRequest(
         "http://example.com",
diff --git a/tests/unit/validation/test_schema_validators.py b/tests/unit/validation/test_schema_validators.py
@@ -276,7 +276,7 @@ def test_additional_properties_true_strict_allows_extra(self):
 
         assert result is None
 
-    def test_require_all_properties_rejects_missing_property(self):
+    def test_enforce_properties_required_rejects_missing_property(self):
         schema = {
             "type": "object",
             "properties": {
@@ -290,10 +290,10 @@ def test_require_all_properties_rejects_missing_property(self):
         with pytest.raises(InvalidSchemaValue):
             oas30_write_schema_validators_factory.create(
                 spec,
-                require_all_properties=True,
+                enforce_properties_required=True,
             ).validate({"name": "openapi-core"})
 
-    def test_require_all_properties_ignores_write_only_fields(self):
+    def test_enforce_properties_required_ignores_write_only_fields(self):
         schema = {
             "type": "object",
             "properties": {
@@ -309,12 +309,14 @@ def test_require_all_properties_ignores_write_only_fields(self):
 
         result = oas30_write_schema_validators_factory.create(
             spec,
-            require_all_properties=True,
+            enforce_properties_required=True,
         ).validate({"name": "openapi-core"})
 
         assert result is None
 
-    def test_require_all_properties_applies_to_nested_composed_schemas(self):
+    def test_enforce_properties_required_applies_to_nested_composed_schemas(
+        self,
+    ):
         schema = {
             "allOf": [
                 {
@@ -341,5 +343,5 @@ def test_require_all_properties_applies_to_nested_composed_schemas(self):
         with pytest.raises(InvalidSchemaValue):
             oas30_write_schema_validators_factory.create(
                 spec,
-                require_all_properties=True,
+                enforce_properties_required=True,
             ).validate({"name": "openapi-core", "meta": {}})
