Core - Custom Fields Documentation

Location: api/nextango/apps/core/fields.py Last Updated: 2026-07-09

Overview

Core defines one custom Django field: EncryptedJSONField, which stores JSON data encrypted at rest. It is a TextField subclass; the encrypted payload is stored as text, not in a native JSON column.

EncryptedJSONField

Stores a Python dict encrypted at rest, decrypting transparently on read. Used for sensitive configuration such as payment processor credentials.

from nextango.apps.core.fields import EncryptedJSONField

class PaymentProcessorConfig(models.Model):
    credentials = EncryptedJSONField()  # default: dict

Behavior

  • get_prep_value(value): encrypts a dict to a base64 string before it is written to the database. Raises ValidationError if value is not a dict. An empty dict is stored as an empty string rather than an encrypted empty payload.
  • from_db_value(value, expression, connection): decrypts the stored string back to a dict on read. Returns {} if the stored value is None or decryption fails.
  • to_python(value): returns the value unchanged if already a dict; otherwise decrypts. Returns {} on None or failure.
  • value_to_string(obj): serialization support (Django's dumpdata/loaddata path); delegates to get_prep_value.

Encryption and decryption go through nextango.apps.core.utils.encryption.get_encryption_service(), documented in Utilities. The encryption key comes from the CONFIGURATION_ENCRYPTION_KEY setting; a missing key raises ImproperlyConfigured at encrypt/decrypt time, not at field definition time.

instance.credentials = {'api_key': 'secret-value'}
instance.save()  # encrypted before the write

instance.refresh_from_db()
instance.credentials  # {'api_key': 'secret-value'}, decrypted transparently

Was this page helpful?