prevent additional properties

Author: the-infinity

docs/05-dataclasses.md

@@ -297,6 +297,31 @@ It is also worth noting that you can use the `@validataclass` decorator with opt
 being applied to the class.
 
 
+## Prevent additional properties
+
+Per default, validataclass just ignores any additional properties in the input dictionary when validating an object.
+This makes sense for normal APIs, as additional fields are just filtered out, and it makes validataclass more robust to 
+changes in the API. There might be situations where one needs to have a strict validation of additional parameters,
+for example, to match an OpenAPI validation. 
+
+You can prevent additional properties by setting `prevent_additional_properties` at the `@validataclass` to `True`, 
+like this:
+
+```python
+from validataclass.dataclasses import validataclass
+from validataclass.validators import DataclassValidator, StringValidator
+
+@validataclass(prevent_additional_properties=True)
+class MyModel:
+    name: str = StringValidator()
+
+my_validator = DataclassValidator(MyModel)
+
+my_validator.validate({'name': 'test'})  # would work fine
+my_validator.validate({'name': 'test', 'more': 'stuff'})  # would throw an AdditionalPropertiesError
+```
+
+
 ## Defining field defaults
 
 While dataclasses have built-in support for field default values, they unfortunately have a rather impractical

src/validataclass/dataclasses/validataclass.py

@@ -88,14 +88,22 @@ class ExampleDataclass:
     """
 
     def decorator(_cls: type[_T]) -> type[_T]:
+        # Pop validataclass-specific options before passing kwargs to @dataclass
+        prevent_additional_properties = kwargs.pop('prevent_additional_properties', False)
+
         # Set kw_only=True as the default to allow required and optional fields in any order
         kwargs.setdefault('kw_only', True)
 
         # Prepare class to become a validataclass
         _prepare_dataclass_metadata(_cls)
 
         # Use @dataclass decorator to turn class into a dataclass
-        return dataclasses.dataclass(**kwargs)(_cls)
+        _cls = dataclasses.dataclass(**kwargs)(_cls)
+
+        # Store validataclass-specific settings on the class
+        _cls.__prevent_additional_properties__ = prevent_additional_properties  # type: ignore[attr-defined]
+
+        return _cls
 
     # Wrap actual decorator if called with parentheses
     return decorator if cls is None else decorator(cls)

src/validataclass/exceptions/__init__.py

@@ -10,7 +10,7 @@
     InvalidTypeError,
     RequiredValueError,
 )
-from .dataclass_exceptions import DataclassPostValidationError
+from .dataclass_exceptions import AdditionalPropertiesError, DataclassPostValidationError
 from .datetime_exceptions import (
     DateTimeRangeError,
     InvalidDateError,
@@ -50,6 +50,7 @@
 from .url_exceptions import InvalidUrlError
 
 __all__ = [
+    'AdditionalPropertiesError',
     'DataclassInvalidPreValidateSignatureException',
     'DataclassPostValidationError',
     'DataclassValidatorFieldException',

src/validataclass/exceptions/dataclass_exceptions.py

@@ -9,10 +9,33 @@
 from .base_exceptions import ValidationError
 
 __all__ = [
+    'AdditionalPropertiesError',
     'DataclassPostValidationError',
 ]
 
 
+class AdditionalPropertiesError(ValidationError):
+    """
+    Validation error raised by `DataclassValidator` when the input dictionary contains keys that do not correspond to
+    any field in the dataclass, and `prevent_additional_properties` is set to `True`.
+
+    The `additional_properties` attribute contains a sorted list of the extra field names.
+
+    Example as dictionary:
+
+    ```
+    {
+        'code': 'additional_properties',
+        'additional_properties': ['unknown1', 'unknown2'],
+    }
+    ```
+    """
+    code = 'additional_properties'
+
+    def __init__(self, *, additional_properties: list[str], **kwargs: Any):
+        super().__init__(additional_properties=sorted(additional_properties), **kwargs)
+
+
 class DataclassPostValidationError(ValidationError):
     """
     Validation error raised by `DataclassValidator` (or by a dataclass itself) when a user-defined post-validation

src/validataclass/validators/dataclass_validator.py

@@ -11,6 +11,7 @@
 
 from validataclass.dataclasses import Default, NoDefault
 from validataclass.exceptions import (
+    AdditionalPropertiesError,
     DataclassInvalidPreValidateSignatureException,
     DataclassPostValidationError,
     DataclassValidatorFieldException,
@@ -109,6 +110,9 @@ def __post_validate__(self, *, require_optional_field: bool = False):
     # Dataclass type that the validated dictionary will be converted to
     dataclass_cls: type[T_Dataclass]
 
+    # Whether to prevent additional properties in the input dictionary
+    prevent_additional_properties: bool
+
     # Field default values
     field_defaults: dict[str, Default]
 
@@ -129,6 +133,7 @@ def __init__(self, dataclass_cls: type[T_Dataclass] | None = None) -> None:
             raise InvalidValidatorOptionException('Parameter "dataclass_cls" must be a dataclass type.')
 
         self.dataclass_cls = dataclass_cls
+        self.prevent_additional_properties = getattr(dataclass_cls, '__prevent_additional_properties__', False)
         self.field_defaults = {}
 
         # Collect field validators and required fields for the DictValidator by examining the dataclass fields
@@ -223,6 +228,13 @@ def _pre_validate(self, input_data: Any, **kwargs: Any) -> dict[str, Any]:
             # Filter input dictionary through __pre_validate__()
             input_data = pre_validate_func(input_data, **context_kwargs)
 
+        # Check for additional properties if not allowed
+        if self.prevent_additional_properties:
+            self._ensure_type(input_data, dict)
+            additional = sorted(set(input_data.keys()) - set(self.field_validators.keys()))
+            if additional:
+                raise AdditionalPropertiesError(additional_properties=additional)
+
         # Validate raw dictionary using underlying DictValidator
         validated_dict = super().validate(input_data, **kwargs)
 

tests/unit/exceptions/dataclass_exceptions_test.py

@@ -5,13 +5,52 @@
 """
 
 from validataclass.exceptions import (
+    AdditionalPropertiesError,
     DataclassPostValidationError,
     DictRequiredFieldError,
     InvalidTypeError,
     ValidationError,
 )
 
 
+class AdditionalPropertiesErrorTest:
+    """
+    Tests for the AdditionalPropertiesError exception class.
+    """
+
+    @staticmethod
+    def test_additional_properties_error_single_property():
+        """ Tests AdditionalPropertiesError with a single additional property. """
+        error = AdditionalPropertiesError(additional_properties=['unknown_field'])
+
+        assert error.to_dict() == {
+            'code': 'additional_properties',
+            'additional_properties': ['unknown_field'],
+        }
+
+    @staticmethod
+    def test_additional_properties_error_multiple_properties():
+        """ Tests AdditionalPropertiesError with multiple additional properties (sorted). """
+        error = AdditionalPropertiesError(additional_properties=['watermelon', 'apple', 'mango'])
+
+        assert error.to_dict() == {
+            'code': 'additional_properties',
+            'additional_properties': ['apple', 'mango', 'watermelon'],
+        }
+
+    @staticmethod
+    def test_additional_properties_error_repr():
+        """ Tests repr of AdditionalPropertiesError. """
+        error = AdditionalPropertiesError(additional_properties=['unknown1', 'unknown2'])
+
+        assert (
+            repr(error)
+            == "AdditionalPropertiesError(code='additional_properties', "
+               "additional_properties=['unknown1', 'unknown2'])"
+        )
+        assert str(error) == repr(error)
+
+
 class DataclassPostValidationErrorTest:
     """
     Tests for the DataclassPostValidationError exception class.

tests/unit/validators/dataclass_validator_test.py

@@ -13,6 +13,7 @@
 from tests.test_utils import UnitTestContextValidator
 from validataclass.dataclasses import Default, DefaultFactory, DefaultUnset, validataclass, validataclass_field
 from validataclass.exceptions import (
+    AdditionalPropertiesError,
     DataclassInvalidPreValidateSignatureException,
     DataclassPostValidationError,
     DataclassValidatorFieldException,
@@ -58,6 +59,17 @@ class UnitTestNestedDataclass:
         validataclass_field(DataclassValidator(UnitTestDataclass), default=None)
 
 
+# Dataclass with prevent_additional_properties=True
+
+@validataclass(prevent_additional_properties=True)
+class UnitTestStrictDataclass:
+    """
+    Dataclass that does not allow additional properties in the input dictionary.
+    """
+    name: str = StringValidator()
+    color: str = StringValidator(), Default('unknown color')
+
+
 # Dataclass with non-init field and __post_init__() method
 
 @validataclass
@@ -1131,3 +1143,95 @@ class IncompatibleDataclass:
             DataclassValidator(IncompatibleDataclass)
 
         assert str(exception_info.value) == 'Default specified for dataclass field "foo" is not of type "Default".'
+
+    # Tests for prevent_additional_properties option
+
+    @staticmethod
+    def test_strict_dataclass_valid():
+        """ Validate a strict dataclass with no extra keys. """
+        validator = DataclassValidator(UnitTestStrictDataclass)
+        validated_data = validator.validate({
+            'name': 'banana',
+            'color': 'yellow',
+        })
+
+        assert type(validated_data) is UnitTestStrictDataclass
+        assert validated_data.name == 'banana'
+        assert validated_data.color == 'yellow'
+
+    @staticmethod
+    def test_strict_dataclass_valid_with_optional_field_omitted():
+        """ Validate a strict dataclass with optional field omitted. """
+        validator = DataclassValidator(UnitTestStrictDataclass)
+        validated_data = validator.validate({
+            'name': 'apple',
+        })
+
+        assert type(validated_data) is UnitTestStrictDataclass
+        assert validated_data.name == 'apple'
+        assert validated_data.color == 'unknown color'
+
+    @staticmethod
+    def test_strict_dataclass_with_additional_properties():
+        """ Test that a strict dataclass raises AdditionalPropertiesError for unknown keys. """
+        validator = DataclassValidator(UnitTestStrictDataclass)
+
+        with pytest.raises(AdditionalPropertiesError) as exception_info:
+            validator.validate({
+                'name': 'banana',
+                'unknown_field': 'unknown_value',
+            })
+
+        assert exception_info.value.to_dict() == {
+            'code': 'additional_properties',
+            'additional_properties': ['unknown_field'],
+        }
+
+    @staticmethod
+    def test_strict_dataclass_with_multiple_additional_properties():
+        """ Test that additional properties are sorted in the error. """
+        validator = DataclassValidator(UnitTestStrictDataclass)
+
+        with pytest.raises(AdditionalPropertiesError) as exception_info:
+            validator.validate({
+                'name': 'banana',
+                'zebra': 1,
+                'alpha': 2,
+                'mango': 3,
+            })
+
+        assert exception_info.value.to_dict() == {
+            'code': 'additional_properties',
+            'additional_properties': ['alpha', 'mango', 'zebra'],
+        }
+
+    @staticmethod
+    def test_default_allows_additional_properties():
+        """ Test that by default (prevent_additional_properties=False), unknown keys are silently ignored. """
+        validator = DataclassValidator(UnitTestDataclass)
+        validated_data = validator.validate({
+            'name': 'banana',
+            'color': 'yellow',
+            'amount': 10,
+            'weight': '1.234',
+            'unknown_field': 'should be ignored',
+        })
+
+        assert type(validated_data) is UnitTestDataclass
+        assert validated_data.name == 'banana'
+
+    @staticmethod
+    def test_explicit_prevent_additional_properties_false():
+        """ Test that prevent_additional_properties=False explicitly allows unknown keys. """
+
+        @validataclass(prevent_additional_properties=False)
+        class ExplicitAllowDataclass:
+            name: str = StringValidator()
+
+        validator = DataclassValidator(ExplicitAllowDataclass)
+        validated_data = validator.validate({
+            'name': 'banana',
+            'extra': 'ignored',
+        })
+
+        assert validated_data.name == 'banana'