2.6. Document Validation¶
By design, MongoEngine strictly validates the documents right before they are inserted in MongoDB and makes sure they are consistent with the fields defined in your models.
MongoEngine makes the assumption that the documents that exists in the DB are compliant with the schema. This means that Mongoengine will not validate a document when an object is loaded from the DB into an instance of your model but this operation may fail under some circumstances (e.g. if there is a field in the document fetched from the database that is not defined in your model).
2.6.1. Built-in validation¶
Mongoengine provides different fields that encapsulate the corresponding validation out of the box. Validation runs when calling .validate() or .save()
from mongoengine import Document, EmailField, IntField class User(Document): email = EmailField() age = IntField(min_value=0, max_value=99) user = User(email='invalid@', age=24) user.validate() # raises ValidationError (Invalid email address: ['email']) user.save() # raises ValidationError (Invalid email address: ['email']) user2 = User(email@example.com', age=1000) user2.save() # raises ValidationError (Integer value is too large: ['age'])
2.6.2. Custom validation¶
The following feature can be used to customize the validation:
Field validation parameter
def not_john_doe(name): if name == 'John Doe': raise ValidationError("John Doe is not a valid name") class Person(Document): full_name = StringField(validation=not_john_doe) Person(full_name='Billy Doe').save() Person(full_name='John Doe').save() # raises ValidationError (John Doe is not a valid name)
Document clean method
This method is called as part of
save() and should be used to provide
custom model validation and/or to modify some of the field values prior to validation.
For instance, you could use it to automatically provide a value for a field, or to do validation
that requires access to more than a single field.
class Essay(Document): status = StringField(choices=('Published', 'Draft'), required=True) pub_date = DateTimeField() def clean(self): # Validate that only published essays have a `pub_date` if self.status == 'Draft' and self.pub_date is not None: raise ValidationError('Draft entries should not have a publication date.') # Set the pub_date for published items if not set. if self.status == 'Published' and self.pub_date is None: self.pub_date = datetime.now()
Cleaning is only called if validation is turned on and when calling
Adding custom Field classes
We recommend as much as possible to use fields provided by MongoEngine. However, it is also possible to subclass a Field and encapsulate some validation by overriding the validate method
class AgeField(IntField): def validate(self, value): super(AgeField, self).validate(value) # let IntField.validate run first if value == 60: self.error('60 is not allowed') class Person(Document): age = AgeField(min_value=0, max_value=99) Person(age=20).save() # passes Person(age=1000).save() # raises ValidationError (Integer value is too large: ['age']) Person(age=60).save() # raises ValidationError (Person:None) (60 is not allowed: ['age'])
When overriding validate, use self.error(“your-custom-error”) instead of raising ValidationError explicitly, it will provide a better context with the error message
2.6.3. Skipping validation¶
Although discouraged as it allows to violate fields constraints, if for some reason you need to disable
the validation and cleaning of a document when you call
save(), you can use .save(validate=False).
class Person(Document): age = IntField(max_value=100) Person(age=1000).save() # raises ValidationError (Integer value is too large) Person(age=1000).save(validate=False) person = Person.objects.first() assert person.age == 1000