skip_on_field_errors defaults to False

Closes marshmallow-code#352
Also addresses marshmallow-code#596

Author: sloria

CHANGELOG.rst

@@ -8,6 +8,10 @@ Features:
 
 - ``fields.Nested`` respects ``only='field'`` when deserializing (:issue:`307`). Thanks :user:`erlingbo` for the suggestion and the PR.
 
+Other changes:
+
+- *Backwards-incompatible*: ``skip_on_field_errors`` defaults to ``True`` for ``validates_schema`` (:issue:`352`).
+
 
 3.0.0a1 (2017-02-26)
 ++++++++++++++++++++

docs/upgrading.rst

@@ -131,6 +131,62 @@ Use a `post_dump <marshmallow.decorators.post_dump>` to add additional data on s
     # => {'z': 123, 'y': 2, 'x': 1}
 
 
+Schema-level validators are skipped when field validation fails
+***************************************************************
+
+By default, schema validator methods decorated by `validates_schema <marshmallow.decorators.validates_schema>` will not be executed if any of the field validators fails (including ``required=True`` validation). 
+
+.. code-block:: python
+
+    from marshmallow import Schema, fields, validates_schema, ValidationError
+
+    class MySchema(Schema):
+        x = fields.Int(required=True)
+        y = fields.Int(required=True)
+
+        @validates_schema
+        def validate_schema(self, data):
+            if data['x'] <= data['y']:
+                raise ValidationError('x must be greater than y')
+
+
+    schema = MySchema(strict=True)
+
+    # 2.x
+    # A KeyError is raised in validate_schema
+    schema.load({'x': 2})
+
+    # 3.x
+    # marshmallow.exceptions.ValidationError: {'y': ['Missing data for required field.']}
+    # validate_schema is not run
+    schema.load({'x': 2})
+
+If you want a schema validator to run even if a field validator fails, pass ``skip_on_field_errors=False``. Make sure your code handles cases where fields are missing from the deserialized data (due to validation errors).
+
+
+.. code-block:: python
+
+    from marshmallow import Schema, fields, validates_schema, ValidationError
+
+    class MySchema(Schema):
+        x = fields.Int(required=True)
+        y = fields.Int(required=True)
+
+        @validates_schema(skip_on_field_errors=False)
+        def validate_schema(self, data):
+            if 'x' in data and 'y' in data:
+                if data['x'] <= data['y']:
+                    raise ValidationError('x must be greater than y')
+
+
+    schema = MySchema(strict=True)
+    schema.load({'x': 2})
+    # marshmallow.exceptions.ValidationError: {'y': ['Missing data for required field.']}
+
+
+
+
+
 Upgrading to 2.3
 ++++++++++++++++
 

marshmallow/decorators.py

@@ -69,7 +69,7 @@ def validates(field_name):
     return tag_processor(VALIDATES, None, False, field_name=field_name)
 
 
-def validates_schema(fn=None, pass_many=False, pass_original=False, skip_on_field_errors=False):
+def validates_schema(fn=None, pass_many=False, pass_original=False, skip_on_field_errors=True):
     """Register a schema-level validator.
 
     By default, receives a single object at a time, regardless of whether ``many=True``
@@ -81,6 +81,9 @@ def validates_schema(fn=None, pass_many=False, pass_original=False, skip_on_fiel
 
     If ``skip_on_field_errors=True``, this validation method will be skipped whenever
     validation errors have been detected when validating fields.
+
+    .. versionchanged:: 3.0.0b1
+        ``skip_on_field_errors`` defaults to `True`.
     """
     return tag_processor(VALIDATES_SCHEMA, fn, pass_many, pass_original=pass_original,
                          skip_on_field_errors=skip_on_field_errors)