Django Mastery: Mastering Database Models from JSON Data

JSON to Django Model: Field Types, null vs blank, and DRF Serializers

Django's ORM maps Python classes directly to database tables. But converting a JSON object to a Django model isn't just a type mapping exercise — the decisions that matter most are Django-specific: whether a field is null=True, blank=True, or both (they mean different things); which field type handles money correctly; how JSONField stores structured sub-objects; and how the generated model feeds directly into a Django REST Framework serializer for your API layer. Get these decisions right at schema design time and migrations stay clean.

Live Example: Product Catalog Model

# Input JSON
{
  "sku": "WIDGET-PRO-L",
  "name": "Widget Pro (Large)",
  "description": "Industrial-grade widget",
  "price": "149.99",
  "stock": 250,
  "category": "hardware",
  "is_available": true,
  "attributes": { "color": "black", "weight_kg": 1.2, "dimensions": [30, 20, 10] },
  "created_at": "2024-01-15T08:30:00Z"
}

# Generated Django Model (models.py)
from django.db import models
from django.core.validators import MinValueValidator

class Category(models.TextChoices):
    HARDWARE   = 'hardware',   'Hardware'
    SOFTWARE   = 'software',   'Software'
    SERVICES   = 'services',   'Services'
    ACCESSORY  = 'accessory',  'Accessory'

class Product(models.Model):
    sku          = models.CharField(max_length=64, unique=True)
    name         = models.CharField(max_length=200)
    description  = models.TextField(blank=True, default='')  # optional text, empty string OK
    price        = models.DecimalField(max_digits=10, decimal_places=2,
                                       validators=[MinValueValidator('0.01')])
    stock        = models.PositiveIntegerField(default=0)
    category     = models.CharField(max_length=20,
                                    choices=Category.choices,
                                    default=Category.HARDWARE)
    is_available = models.BooleanField(default=True)
    attributes   = models.JSONField(default=dict, blank=True)
    created_at   = models.DateTimeField(auto_now_add=True)
    updated_at   = models.DateTimeField(auto_now=True)

    class Meta:
        db_table  = 'catalog_products'
        ordering  = ['-created_at']
        indexes   = [
            models.Index(fields=['category', 'is_available']),
            models.Index(fields=['sku']),
        ]

    def __str__(self):
        return f"{self.sku}: {self.name}"

The null vs blank Distinction

This is the most Django-specific mistake in model design. null and blank control different layers:

# null=True  → database allows NULL (affects DB schema)
# blank=True → Django validation allows empty values (affects forms and serializers)
# They are independent and mean different things.

# String-based fields (CharField, TextField, EmailField, URLField):
# Django convention: DON'T use null=True — use blank=True + default='' instead.
# Two ways to say "no value" for strings (NULL and '') creates querying problems.
bio      = models.TextField(blank=True, default='')   # correct: empty string = no bio
nickname = models.CharField(max_length=50, blank=True, default='')

# Non-string fields (IntegerField, DateField, ForeignKey, etc.):
# Here null=True makes sense — there's no "empty" integer or date.
age       = models.PositiveIntegerField(null=True, blank=True)   # may be unknown
deleted_at = models.DateTimeField(null=True, blank=True)         # soft-delete timestamp
manager   = models.ForeignKey('self', null=True, blank=True,     # optional relation
                               on_delete=models.SET_NULL,
                               related_name='reports')

# Special case: BooleanField
# Never use null=True on BooleanField — use NullBooleanField (deprecated)
# or just BooleanField with a default and make the field required.
is_active = models.BooleanField(default=True)   # never null

Complete Field Type Reference

class UserProfile(models.Model):
    # Strings
    username  = models.CharField(max_length=150, unique=True)
    bio       = models.TextField(blank=True, default='')
    email     = models.EmailField(unique=True)         # validates email format
    website   = models.URLField(blank=True, default='')  # validates URL format
    avatar    = models.ImageField(upload_to='avatars/', blank=True)  # file path

    # Numbers
    score     = models.IntegerField(default=0)
    views     = models.PositiveBigIntegerField(default=0)   # 64-bit unsigned
    rating    = models.FloatField(null=True, blank=True)    # imprecise — avoid for money
    balance   = models.DecimalField(max_digits=12, decimal_places=2)  # precise money

    # Booleans
    is_active    = models.BooleanField(default=True)
    is_verified  = models.BooleanField(default=False)

    # Dates and Times
    birth_date   = models.DateField(null=True, blank=True)
    created_at   = models.DateTimeField(auto_now_add=True)  # set once on insert
    updated_at   = models.DateTimeField(auto_now=True)      # updated on every save
    last_login   = models.DateTimeField(null=True, blank=True)

    # Choices (TextChoices/IntegerChoices)
    class Role(models.TextChoices):
        ADMIN   = 'admin',   'Administrator'
        EDITOR  = 'editor',  'Editor'
        VIEWER  = 'viewer',  'Viewer'

    role = models.CharField(max_length=20, choices=Role.choices, default=Role.VIEWER)

    # JSON (PostgreSQL, MySQL 8+, SQLite 3.37+)
    settings = models.JSONField(default=dict, blank=True)
    tags     = models.JSONField(default=list, blank=True)

    # UUID primary key (instead of auto-increment integer)
    import uuid
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)

JSONField: Querying and Indexing

class Event(models.Model):
    type    = models.CharField(max_length=50)
    payload = models.JSONField()

# Querying nested JSON with __ lookups (PostgreSQL + SQLite)
# payload = {"user_id": "u1", "amount": 4999, "tags": ["vip", "recurring"]}

Event.objects.filter(payload__user_id='u1')
Event.objects.filter(payload__amount__gte=1000)

# Array item access by index
Event.objects.filter(payload__tags__0='vip')   # first element

# PostgreSQL: JSONField with GIN index for fast containment queries
class Meta:
    indexes = [
        # GIN index via django-postgresql-extensions or raw SQL
        # models.Index(fields=['payload'], name='event_payload_gin')
    ]

# Update a specific JSON key without fetching the whole document
from django.db.models import F

# Increment a nested value (PostgreSQL JSON_SET equivalent)
# Use F() for atomic updates
Event.objects.filter(type='page_view').update(
    payload=models.functions.JSONObject(
        user_id=models.F('payload__user_id'),
        count=models.F('payload__count') + 1
    )
)

Django REST Framework: Serializers from Models

from rest_framework import serializers
from .models import Product

# ModelSerializer — auto-generates fields from model
class ProductSerializer(serializers.ModelSerializer):
    # Add computed or read-only fields
    price_display = serializers.SerializerMethodField()

    class Meta:
        model   = Product
        fields  = ['id', 'sku', 'name', 'price', 'price_display',
                   'stock', 'category', 'is_available', 'created_at']
        read_only_fields = ['id', 'created_at']

    def get_price_display(self, obj):
        return f"${obj.price:.2f}"

# Nested serializer for related objects
class OrderLineSerializer(serializers.ModelSerializer):
    product = ProductSerializer(read_only=True)   # nested
    product_id = serializers.PrimaryKeyRelatedField(
        queryset=Product.objects.all(),
        source='product',
        write_only=True
    )

    class Meta:
        model  = OrderLine
        fields = ['id', 'product', 'product_id', 'quantity', 'unit_price']

# View using the serializer
from rest_framework.viewsets import ModelViewSet
from rest_framework.permissions import IsAuthenticated

class ProductViewSet(ModelViewSet):
    queryset           = Product.objects.filter(is_available=True)
    serializer_class   = ProductSerializer
    permission_classes = [IsAuthenticated]

    def get_queryset(self):
        qs = super().get_queryset()
        category = self.request.query_params.get('category')
        if category:
            qs = qs.filter(category=category)
        return qs.select_related().prefetch_related()

N+1 Prevention: select_related and prefetch_related

class Order(models.Model):
    customer = models.ForeignKey('Customer', on_delete=models.PROTECT)
    lines    = models.ManyToManyField('Product', through='OrderLine')

class OrderLine(models.Model):
    order   = models.ForeignKey(Order, on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.PROTECT)
    quantity = models.PositiveIntegerField()

# BAD: N+1 query problem — 1 query for orders + N queries for customers
orders = Order.objects.all()
for order in orders:
    print(order.customer.name)  # DB hit per order

# GOOD: select_related — SQL JOIN for ForeignKey/OneToOne
orders = Order.objects.select_related('customer').all()
for order in orders:
    print(order.customer.name)  # no extra query

# GOOD: prefetch_related — separate query + Python join for ManyToMany
orders = (Order.objects
    .select_related('customer')
    .prefetch_related('lines', 'lines__product')
    .all()
)

for order in orders:
    for line in order.lines.all():    # no extra query — prefetched
        print(line.product.name)

# Prefetch with filtering
from django.db.models import Prefetch

recent_lines = OrderLine.objects.filter(
    product__is_available=True
).select_related('product')

orders = Order.objects.prefetch_related(
    Prefetch('orderline_set', queryset=recent_lines, to_attr='active_lines')
)

Migration Workflow

# 1. Create a new migration after changing models.py
python manage.py makemigrations

# 2. Preview the SQL that will run
python manage.py sqlmigrate myapp 0002

# 3. Apply to development database
python manage.py migrate

# 4. Apply to production (CI/CD step)
python manage.py migrate --run-syncdb

# When renaming a field: Django detects it as drop+add (data loss!)
# Override with a manual migration step:
# migrations/0003_rename_bio.py
from django.db import migrations

class Migration(migrations.Migration):
    dependencies = [('myapp', '0002_add_bio')]
    operations   = [
        migrations.RenameField(
            model_name='userprofile',
            old_name='bio',
            new_name='biography',
        ),
    ]

# Adding an index to a large table safely (no lock)
operations = [
    migrations.AddIndex(
        model_name='product',
        index=models.Index(
            fields=['category', 'is_available'],
            name='product_category_available_idx'
        ),
    ),
]
# → PostgreSQL uses CREATE INDEX CONCURRENTLY automatically via django-pg-zero-downtime

Django Signals for Side Effects

from django.db.models.signals import post_save, pre_delete
from django.dispatch import receiver
from .models import Order

@receiver(post_save, sender=Order)
def notify_on_order_create(sender, instance, created, **kwargs):
    if created:
        # Trigger email, webhook, or async task on new order
        send_order_confirmation.delay(instance.id)  # Celery task

@receiver(pre_delete, sender=Order)
def archive_before_delete(sender, instance, **kwargs):
    # Soft-delete pattern: copy to archive table before hard delete
    OrderArchive.objects.create(
        original_id=instance.id,
        data={
            'customer_id': str(instance.customer_id),
            'total':       str(instance.total),
        }
    )

Best Practices for Production

• Never use null=True on CharField/TextField: Django convention is to use blank=True, default='' for optional strings. Two representations of "empty" (NULL and empty string) create inconsistent query behavior — filter(field__isnull=True) and filter(field='') become two different queries for the same business concept.
• Use DecimalField, never FloatField, for money: FloatField uses IEEE 754 floating point, which cannot exactly represent values like 0.10. DecimalField(max_digits=10, decimal_places=2) maps to PostgreSQL's NUMERIC — exact decimal arithmetic.
• Always add related_name to ForeignKeys: Without it, the reverse manager is named modelname_set, which becomes ambiguous with abstract base classes and causes reverse accessor clash errors when two models point to the same model.
• Add db_index=True or Meta.indexes for columns used in WHERE/JOIN: Django automatically creates indexes for ForeignKey columns, but not for other columns you filter on. Analyze slow queries with EXPLAIN ANALYZE — missing indexes are the most common Django performance issue.

FAQ

Q: When should I use JSONField vs separate model fields?
A: JSONField is right for truly flexible or schema-less data (user preferences, event payloads, plugin configuration). Use structured fields when you need to filter, sort, or index on individual keys — SQL is much faster than payload__key__gte=X on a JSONField, especially without a GIN index.

Q: How do I handle enums that change over time?
A: Define enums as TextChoices (string-backed) rather than IntegerChoices. Adding new choices never requires a migration — the constraint exists in Django validation, not in the database. To remove a choice, search the codebase first; the DB still has existing rows with the old value.

Q: What's the difference between auto_now_add and default=timezone.now?
A: auto_now_add=True sets the field once on creation and makes it non-editable — it can't be overridden in Model.objects.create(). default=timezone.now sets a default but allows override, which is useful in tests where you need reproducible timestamps.

Q: How do I run raw SQL when the ORM isn't enough?
A: Use Model.objects.raw('SELECT ...') for raw queries that return model instances, or from django.db import connection; cursor = connection.cursor(); cursor.execute(...) for arbitrary SQL. Both are within Django's managed connection pool, so transactions work normally.