Response Properties Policy

Author: p1c2u

docs/configuration.md

@@ -138,6 +138,11 @@ By default, OpenAPI follows JSON Schema behavior: when an object schema omits `a
 
 If you want stricter behavior, enable `strict_additional_properties`. In this mode, omitted `additionalProperties` is treated as `false`.
 
+This mode is particularly useful for:
+- **Preventing data leaks**: Ensuring your API doesn't accidentally expose internal or sensitive fields in responses that aren't explicitly documented.
+- **Strict client validation**: Rejecting client requests that contain typos, extraneous data, or unsupported fields, forcing clients to adhere exactly to the defined schema.
+- **Contract tightening**: Enforcing the exact shape of objects across your API boundaries.
+
 ``` python hl_lines="4"
 from openapi_core import Config
 from openapi_core import OpenAPI
@@ -153,24 +158,27 @@ 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).
+
+This mode is intentionally stricter than the OpenAPI default. It is particularly useful for:
+- **Contract completeness checks in tests**: Ensuring that the backend actually returns all the properties documented in the OpenAPI specification.
+- **Detecting API drift**: Catching bugs where a database schema change or serializer update inadvertently drops fields from the response.
+- **Preventing silent failures**: Making sure clients aren't broken by missing data that they expect to be present according to the API documentation.
 
 ``` 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)
 ```
 
-This mode is intentionally stricter than the OpenAPI default and is useful for contract completeness checks in tests.
-
 ## Extra Format Validators
 
 OpenAPI defines a `format` keyword that hints at how a value should be interpreted. For example, a `string` with the format `date` should conform to the RFC 3339 date format.

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,
         )

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.
     """

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,

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)

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,
         )

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"
+    )

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(

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
                 )

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)