{"id":4593,"library":"jsonfield","title":"Django JSONField","description":"A reusable Django model field that allows you to store validated JSON, automatically handling serialization to and from the database. The package is currently at version 3.2.0. This package is in maintenance mode and is considered deprecated in favor of Django's native JSONField (introduced in Django 3.1) which offers superior database-agnostic support and querying capabilities.","status":"deprecated","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/rpkilby/jsonfield","tags":["django","json","database-field","orm","deprecated"],"install":[{"cmd":"pip install jsonfield","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Django model field and requires a Django project to be used. The `requires_python` is `>=3.10`.","package":"Django","optional":false}],"imports":[{"note":"This package's JSONField is distinct from Django's native JSONField (located at `django.db.models.JSONField` or older `django.contrib.postgres.fields.JSONField`).","wrong":"from django.contrib.postgres.fields import JSONField","symbol":"JSONField","correct":"from jsonfield import JSONField"}],"quickstart":{"code":"from django.db import models\nfrom jsonfield import JSONField\n\nclass MyModel(models.Model):\n    name = models.CharField(max_length=100)\n    data = JSONField(default=dict) # Use a callable for mutable defaults\n\n# Example usage:\n# obj = MyModel.objects.create(name='Example', data={'key': 'value', 'number': 123})\n# print(obj.data['key'])\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions of `jsonfield` when used with Django 3.1+."},{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0 and later."},{"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.","message":"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.","severity":"breaking","affected_versions":"1.0.0 and later."},{"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`.","message":"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).","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}