Enforcing Structure on JSONField in Django

You're right to be concerned about ensuring data integrity for your JSONField. Let's explore the best approaches for enforcing a specific JSON structure at the model level.

Custom Field Validator

The most direct approach is to create a custom validator for your JSONField. This will be applied during model validation and can be attached directly to the field:

PYTHONCopied
from django.core.exceptions import ValidationError
from django.db import models
import jsonschema

def validate_json_schema(value):
    schema = {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"},
            "email": {"type": "string", "format": "email"}
        },
        "required": ["name", "email"]
    }
    
    try:
        jsonschema.validate(instance=value, schema=schema)
    except jsonschema.exceptions.ValidationError as e:
        raise ValidationError(f"JSON schema validation error: {e}")

class Person(models.Model):
    data = models.JSONField(validators=[validate_json_schema])
    # other fields...

This approach uses the jsonschema library (which you would need to install) to validate against a predefined schema.

Custom JSONField Subclass

For a more comprehensive solution that handles all save operations including update() and bulk_update(), you could create a custom JSONField subclass:

PYTHONCopied
from django.db import models
from django.core.exceptions import ValidationError
import jsonschema

class SchemaJSONField(models.JSONField):
    def __init__(self, *args, **kwargs):
        self.schema = kwargs.pop('schema', None)
        super().__init__(*args, **kwargs)

    def validate(self, value, model_instance):
        super().validate(value, model_instance)
        if self.schema and value is not None:
            try:
                jsonschema.validate(instance=value, schema=self.schema)
            except jsonschema.exceptions.ValidationError as e:
                raise ValidationError(f"JSON schema validation error: {e}")
                
    def pre_save(self, model_instance, add):
        value = super().pre_save(model_instance, add)
        self.validate(value, model_instance)
        return value

class Person(models.Model):
    data = SchemaJSONField(
        schema={
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "email": {"type": "string", "format": "email"}
            },
            "required": ["name", "email"]
        }
    )
    # other fields...

This approach overrides the pre_save method to ensure validation happens before any save operation.

Database Constraints

For PostgreSQL users, you could also consider using database-level constraints:

PYTHONCopied
from django.db import models

class Person(models.Model):
    data = models.JSONField()
    
    class Meta:
        constraints = [
            models.CheckConstraint(
                check=models.Q(data__has_key='name') & models.Q(data__has_key='email'),
                name='data_has_required_fields'
            )
        ]

This is more limited than full schema validation but provides database-level enforcement.

Recommendation

I recommend the custom JSONField subclass approach as it provides the most comprehensive validation across all database operations. The pre_save method is called for all save operations, including those that bypass the model's save() method.

If you're using Django REST Framework, you can still use serializers for API-level validation, but having model-level validation ensures data integrity regardless of how the data enters your database.

Remember that for complex schemas, the jsonschema library offers powerful validation capabilities that can be integrated with any of these approaches.