Models Field Types

String Fields — When to Use Which

class Firmware(TimestampedModel):
    name = models.CharField(max_length=255)           # short, indexed
    slug = models.SlugField(max_length=255, unique=True)
    description = models.TextField(blank=True, default="")  # long, not indexed
    version = models.CharField(max_length=50)
    download_url = models.URLField(max_length=500, blank=True, default="")

Choices with TextChoices Enum

class FirmwareType(models.TextChoices):
    OFFICIAL = "official", "Official"
    ENGINEERING = "engineering", "Engineering"
    READBACK = "readback", "Readback"
    MODIFIED = "modified", "Modified"
    OTHER = "other", "Other"

class Firmware(TimestampedModel):
    firmware_type = models.CharField(
        max_length=20,
        choices=FirmwareType.choices,
        default=FirmwareType.OFFICIAL,
    )

Numeric Fields

class Product(TimestampedModel):
    price = models.DecimalField(max_digits=10, decimal_places=2)  # money
    stock = models.PositiveIntegerField(default=0)
    file_size = models.BigIntegerField(default=0)  # bytes

JSONField — Flexible Schema

class DeviceConfig(TimestampedModel):
    """Singleton config — uses JSONField for nested settings."""
    fingerprinting_policy = models.JSONField(default=dict, blank=True)
    quota_overrides = models.JSONField(default=dict, blank=True)

    # Query JSONField:
    # DeviceConfig.objects.filter(fingerprinting_policy__enabled=True)

Date/Time Fields

class Campaign(TimestampedModel):
    start_at = models.DateTimeField()
    end_at = models.DateTimeField(null=True, blank=True)  # null OK for optional dates
    launch_date = models.DateField(null=True, blank=True)

File Fields

class FirmwareFile(TimestampedModel):
    file = models.FileField(upload_to="firmwares/%Y/%m/")
    image = models.ImageField(upload_to="images/", blank=True)
    # Always validate MIME type and size in services.py before saving

null vs blank Cheat Sheet

Anti-Patterns

• null=True on CharField / TextField — use default="" instead
• FloatField for prices or currency — always DecimalField
• Missing related_name on FK/M2M — causes clash errors
• CharField for IP addresses — use GenericIPAddressField
• Hard-coded choice strings — use TextChoices enum

Quality Gate

& .\.venv\Scripts\python.exe -m ruff check . --fix
& .\.venv\Scripts\python.exe -m ruff format .
& .\.venv\Scripts\python.exe manage.py check --settings=app.settings_dev

References

• Django Model Field Reference