Skip to main content

A reusable Django field that allows you to store validated JSON in your model.

Project description

https://github.com/rpkilby/jsonfield/actions/workflows/main.yml/badge.svg https://codecov.io/gh/rpkilby/jsonfield/graph/badge.svg https://img.shields.io/pypi/l/jsonfield.svg https://img.shields.io/pypi/v/jsonfield.svg https://img.shields.io/pypi/pyversions/jsonfield.svg

jsonfield is a reusable model field that allows you to store validated JSON, automatically handling serialization to and from the database. To use, add jsonfield.JSONField to one of your models.

Deprecation & Migration to Django’s native JSONField

Django 3.1 introduced a native JSONField that supports all database backends. As such, this package is considered deprecated and will be archived in the future. Existing projects should migrate to Django’s implemenation.

Migrating from jsonfield.JSONField to models.JSONField should generally be straightforward. After swapping field classes, python manage.py migrate will generate AlterField operations that should correctly migrate your field data. However, if this does not work for your case, you will instead need to create a data migration. The process will roughly look like:

  • Rename <field> to old_<field>, create migration.

  • Add a nullable <field> = models.JSONField(null=True, ...), create migration.

  • Create an empty migration file, add RunPython operation that reserializes the old_<field> data into the new <field>.

  • Update <field> to not nullable, delete old_<field>, create migration.

  • Manually combine the operations into a single migration file.

Examples can be found in the migration-example project.

Installation

pip install jsonfield

Usage

from django.db import models
from jsonfield import JSONField

class MyModel(models.Model):
    json = JSONField()

Querying

As stated above, JSONField is not intended to provide extended querying capabilities. That said, you may perform the same basic lookups provided by regular text fields (e.g., exact or regex lookups). Since values are stored as serialized JSON, it is highly recommended that you test your queries to ensure the expected results are returned.

Handling null values

A model field’s null argument typically controls whether null values may be stored in its column by setting a not-null constraint. However, because JSONField serializes its values (including nulls), this option instead controls how null values are persisted. If null=True, then nulls are not serialized and are stored as a null value in the database. If null=False, then the null is instead stored in its serialized form.

This in turn affects how null values may be queried. Both fields support exact matching:

MyModel.objects.filter(json=None)

However, if you want to use the isnull lookup, you must set null=True.

class MyModel(models.Model):
    json = JSONField(null=True)

MyModel.objects.filter(json__isnull=True)

Note that as JSONField.null does not prevent nulls from being stored, achieving this must instead be handled with a validator.

Advanced Usage

By default python deserializes json into dict objects. This behavior differs from the standard json behavior because python dicts do not have ordered keys. To overcome this limitation and keep the sort order of OrderedDict keys the deserialisation can be adjusted on model initialisation:

import collections

class MyModel(models.Model):
    json = JSONField(load_kwargs={'object_pairs_hook': collections.OrderedDict})

Other Fields

jsonfield.JSONCharField

Subclasses models.CharField instead of models.TextField.

Running the tests

The test suite requires tox.

$ pip install tox

Then, run the tox command, which will run all test jobs.

$ tox

Or, to test just one job (for example Django 5.2 on Python 3.13):

$ tox -e py313-django52

Release Process

  • Update changelog

  • Update package version in setup.py

  • Check supported versions in setup.py and readme

  • Create git tag for version

  • Upload release to PyPI test server

  • Upload release to official PyPI server

$ pip install -U pip setuptools wheel twine
$ rm -rf dist/ build/
$ python setup.py sdist bdist_wheel
$ twine upload -r test dist/*
$ twine upload dist/*

Changes

Take a look at the changelog.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonfield-3.2.0.tar.gz (17.2 kB view details)

Uploaded Source

Built Distribution

jsonfield-3.2.0-py3-none-any.whl (8.3 kB view details)

Uploaded Python 3

File details

Details for the file jsonfield-3.2.0.tar.gz.

File metadata

  • Download URL: jsonfield-3.2.0.tar.gz
  • Upload date:
  • Size: 17.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for jsonfield-3.2.0.tar.gz
Algorithm Hash digest
SHA256 ca53871bc3308ae4f4cddc3b4f99ed5c6fc6abb1832fbfb499bc6da566c70e4a
MD5 258c3a673693f083dcb8ea74609aa899
BLAKE2b-256 fae9537e105246dba81d898853dbbe17eb3edd23d47a35074b99fd4add6f1662

See more details on using hashes here.

File details

Details for the file jsonfield-3.2.0-py3-none-any.whl.

File metadata

  • Download URL: jsonfield-3.2.0-py3-none-any.whl
  • Upload date:
  • Size: 8.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.5

File hashes

Hashes for jsonfield-3.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ca4f6bf89c819f293e77074d613c0021e3c4e8521be95c73d03caecb4372e1ee
MD5 f96e7738372863025ae93a4f7bc4988c
BLAKE2b-256 0a222e08e7b957f50e5eceefde018ce9ee88aceb5126231128d9c1cb8167c1c8

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page