Django JSONField

Warnings

• deprecated The `jsonfield` package is deprecated. Django 3.1 and newer versions provide a native `django.db.models.JSONField` that is recommended for all new projects and migrations. The native field offers better database-agnostic support and enhanced querying capabilities, especially with PostgreSQL's JSONB.
  Fix: Migrate to `django.db.models.JSONField`. For existing projects, this generally involves swapping the field class in your models and running `makemigrations` and `migrate`. Complex data structures or older migrations might require manual data migration strategies.
• breaking Version 3.0.0 introduced significant breaking changes, including dropping support for Django versions older than 2.0 and Python versions older than 3.5. It also reworked field serialization/deserialization, moved form fields (e.g., `JSONFormField` was renamed to `forms.JSONField` and moved), and removed South migration support.
  Fix: Before upgrading to `jsonfield` 3.0.0+, ensure your Django project is on version 2.0+ and Python on 3.5+. Carefully review the `CHANGES.rst` for `v3.0.0` on the GitHub repository to adapt to changes in import paths for form fields and serialization logic.
• breaking Version 1.0.0 (and related pre-1.0.0 releases) introduced a breaking change by removing direct native PostgreSQL JSON data type support. If your project relied on PostgreSQL's native JSON features with `jsonfield` versions prior to 1.0.0, upgrading to 1.0.0+ can be a breaking change as data might subsequently be stored as plain text.
  Fix: Consult the specific migration guidance for PostgreSQL users upgrading from `<1.0.0`, particularly `https://github.com/dmkoch/django-jsonfield/issues/57`. For native PostgreSQL JSON features (like JSONB indexing), it is strongly recommended to use Django's built-in `django.db.models.JSONField` instead.
• gotcha There are multiple Python packages on PyPI that are named 'jsonfield' or 'django-jsonfield'. This entry specifically refers to the `jsonfield` package (on PyPI, `rpkilby/jsonfield` on GitHub, formerly `bradjasper/django-jsonfield`). Be cautious not to confuse it with other packages, such as `django-jsonfield` (on PyPI, `adamchainz/django-jsonfield` on GitHub).
  Fix: Always verify the correct package is installed and imported by checking `pip show jsonfield` and confirming the source URL matches `https://github.com/rpkilby/jsonfield`.
• gotcha While `jsonfield` stores JSON, its querying capabilities are limited to basic text lookups (e.g., `exact`, `regex`) because values are stored as serialized JSON strings. It is not designed to provide advanced, database-native JSON querying functionalities like those offered by `django.db.models.JSONField` (especially when used with PostgreSQL's JSONB type).
  Fix: For complex querying or leveraging native JSON database features (such as key lookups, containment, or indexing), migrate to `django.db.models.JSONField` and ensure you are using a PostgreSQL database.

Install

• pip install jsonfield Install latest version

Imports

• JSONField

  from jsonfield import JSONField

  This package's JSONField is distinct from Django's native JSONField (located at `django.db.models.JSONField` or older `django.contrib.postgres.fields.JSONField`).

Quickstart

Define a model with `jsonfield.JSONField`. It's recommended to use a callable for mutable defaults (like `dict` or `list`) to avoid shared state issues.

from django.db import models
from jsonfield import JSONField

class MyModel(models.Model):
    name = models.CharField(max_length=100)
    data = JSONField(default=dict) # Use a callable for mutable defaults

# Example usage:
# obj = MyModel.objects.create(name='Example', data={'key': 'value', 'number': 123})
# print(obj.data['key'])