added non-native valiation only fields usage to the serializer docs

docs/api-guide/serializers.md

@@ -405,6 +405,62 @@ You can add extra fields to a `ModelSerializer` or override the default fields b
 
 Extra fields can correspond to any property or callable on the model.
 
+## Specifying non-native validation only fields
+
+You can add extra non-native `validation only` fields to a `ModelSerializer` provided that you meet the following two conditions:
+
+**A)** The extra `validation only` fields are removed from the `attrs` parameter prior to invoking the `restore_object()` method on the `parent` serializer class.
+
+**B)** The extra `validation only` fields are removed from the `fields` attribute prior to invoking the `to_native()` method on the `parent` serializer class during the `object attribute` validations.
+
+**Note:** You should `not` remove the extra `validation only` fields from the `fields` attribute prior to invoking the `to_native()` method on the `parent` serializer class during the `form creation` process if you are using the built-in browsable API.
+
+    # Example of overriding restore_object() and to_native() attributes
+
+    class UserCreationSerializer(serializers.ModelSerializer):
+        password_confirmation = serializers.CharField()
+        accept_our_terms_and_conditions = serializers.BooleanField()
+
+        custom_messages = {
+            'password_mismatch': 'The two password fields did not match.',
+            'terms_conditions': 'You must accept our terms and conditions.',
+        }
+
+        def validate_password_confirmation(self, attrs, source):
+            password_confirmation = attrs[source]
+            password = attrs['password']
+            if password_confirmation != password:
+                raise serializers.ValidationError(self.custom_messages['password_mismatch'])
+            return attrs
+
+        def validate_accept_our_terms_and_conditions(self, attrs, source):
+            accept_our_terms_and_conditions = attrs[source]
+            if not accept_our_terms_and_conditions:
+                raise serializers.ValidationError(self.custom_messages['terms_conditions'])
+            return attrs
+
+        class Meta:
+            model = ValidationOnlyFieldsExampleModel
+            fields = ('email', 'password', 'password_confirmation', 'accept_our_terms_and_conditions',)
+            write_only_fields = ('password',)
+            validation_only_fields = ('password_confirmation', 'accept_our_terms_and_conditions',)
+
+        def restore_object(self, attrs, instance=None):
+            # Flow: south-bound -- object creation: model instance
+            for attr in self.Meta.validation_only_fields:
+                attrs.pop(attr)
+            return super(UserCreationSerializer, self).restore_object(attrs, instance)
+
+        def to_native(self, obj):
+            try:
+                # Flow: north-bound -- form creation: browser API
+                return super(UserCreationSerializer, self).to_native(obj)
+            except AttributeError as e:
+                # Flow: south-bound -- object validation: model class
+                for field in self.Meta.validation_only_fields:
+                    self.fields.pop(field)
+            return super(UserCreationSerializer, self).to_native(obj)
+
 ## Relational fields
 
 When serializing model instances, there are a number of different ways you might choose to represent relationships.  The default representation for `ModelSerializer` is to use the primary keys of the related instances.