Data Validation Patterns

This skill provides validation patterns for ensuring data integrity across the WoD application.

When to Use This Skill

• Adding @transaction.atomic to multi-step operations (XP spending, freebie allocation)
• Adding CheckConstraint to model Meta classes
• Writing clean() methods for cross-field validation
• Adding field validators (MinValueValidator, MaxValueValidator)
• Writing tests for validation logic

Quick Reference

Transaction Pattern (XP/Freebie Operations)

from django.db import transaction
from django.core.exceptions import ValidationError

class Character(Model):
    @transaction.atomic
    def spend_xp(self, trait_name, cost, category):
        # Lock row for concurrent access
        char = Character.objects.select_for_update().get(pk=self.pk)
        
        if char.xp < cost:
            raise ValidationError(f"Insufficient XP: need {cost}, have {char.xp}")
        
        char.xp -= cost
        char.spent_xp.append({...})
        char.save(update_fields=['xp', 'spent_xp'])

Database Constraint Pattern

from django.db.models import CheckConstraint, Q

class Character(Model):
    class Meta:
        constraints = [
            CheckConstraint(
                check=Q(xp__gte=0),
                name='%(app_label)s_%(class)s_xp_non_negative',
                violation_error_message="XP cannot be negative"
            ),
        ]

Model Validation Pattern

class Human(Character):
    def clean(self):
        super().clean()
        if self.temporary_willpower > self.willpower:
            raise ValidationError({
                'temporary_willpower': f"Cannot exceed permanent willpower ({self.willpower})"
            })

Field Validator Pattern

from django.core.validators import MinValueValidator, MaxValueValidator

class AttributeBlock(models.Model):
    strength = models.IntegerField(
        default=1,
        validators=[MinValueValidator(1), MaxValueValidator(10)]
    )

Detailed Patterns

For detailed implementation patterns including:

• Full XP spending transaction implementation
• Scene XP award transactions
• All attribute/ability constraints
• Status state machine validation
• JSON schema validation for spent_xp
• Migration strategies for adding constraints

See references/validation-patterns.md

Priority Guidelines

Testing Validation

from django.test import TestCase
from django.core.exceptions import ValidationError
from django.db import IntegrityError

class TestCharacterValidation(TestCase):
    def test_xp_cannot_be_negative_db_constraint(self):
        character.xp = -100
        with self.assertRaises(IntegrityError):
            character.save()

    def test_xp_cannot_be_negative_model_validation(self):
        character.xp = -100
        with self.assertRaises(ValidationError):
            character.full_clean()