Expose nested JSON
as Django fields.

From document to model API

Use JSON values where Django expects fields

A plain JSONField gives you a dictionary. JSONStore gives selected values a type, validation, a form widget, an admin column and a query name.

Field types

Twenty-five field types, and the relations

Each field takes the same arguments as the equivalent field in django.db.models. This includes max_length, default, null, blank, choices, verbose_name and help_text. The field converts the value when it reads the document.

Keys and layout

Map any path to a field

class Person(models.Model):
    data = models.JSONField(default=dict)

    full_name = jsonstore.CharField(
        max_length=250,
        json_field_name="data",
        json_key="name")
    city = jsonstore.CharField(
        max_length=100,
        json_field_name="data",
        json_key=("address", "city"))
    zip_code = jsonstore.CharField(
        max_length=10,
        json_field_name="data",
        json_key=("address", "zip"))

Person(full_name="Ann", city="Paris",
       zip_code="75001").data
# {"name": "Ann",
#  "address": {"city": "Paris",
#              "zip": "75001"}}

Relations

A foreign key in the document

class Book(models.Model):
    data = models.JSONField(default=dict)
    title = jsonstore.CharField(max_length=250)
    author = jsonstore.ForeignKey(
        Author, null=True)

book = Book(title="Pale Fire", author=nabokov)
book.data     # {"title": …, "author_id": 1}
book.author   # <Author: Nabokov>

post.tags.set([python, django])
post.tags.count()      # 2
post.save()

# A join is not available. Use the key.
Book.objects.filter(
    data__author_id=nabokov.pk)

Embedded documents

Typed access to whole nested documents

class Money(jsonstore.EmbeddedModel):
    amount = jsonstore.IntegerField()
    currency = jsonstore.CharField(
        max_length=3, default="USD")

class Product(models.Model):
    data = models.JSONField(default=dict)
    price = jsonstore.EmbeddedField(
        Money, null=True)

product.price = Money(amount=100)
product.data
# {"price": {"amount": 100, "currency": "USD"}}
product.price.amount  # 100

order.lines.append(LineItem(sku="c", qty=3))
order.lines[0].qty = 5
order.save()

One table, several types

Polymorphic models without a second table

class User(PolymorphicModel, AbstractUser):
    data = models.JSONField(default=dict)

class Client(User):
    address = jsonstore.CharField(max_length=250)
    city = jsonstore.CharField(max_length=250)
    vip = jsonstore.BooleanField()

    class Meta:
        proxy = True

Install

One command, and no application to register

pip install django-jsonstore

Do not add an application to INSTALLED_APPS. The package needs Python 3.10 or later, and Django 5.2, 6.0 or 6.1. Add one models.JSONField to the model, then declare the virtual fields.

Databases

Every backend that Django supports for JSON

Django's own JSONField writes the data. Thus the requirements are the same as the requirements of Django. A query on a virtual field becomes a key transform, and the database must be able to read a key in the document. The suite passes on SQLite, PostgreSQL 17, MySQL 8.4, MariaDB 11 and Oracle 23ai.

Limitations

What the database no longer does for you

A value in a document is outside the reach of the schema. Read this list before you select a document over a column.

• No constraint. A jsonstore.ForeignKey can point to a row that no longer exists. on_delete has no effect, and an OneToOneField has no UNIQUE index.
• No reverse accessor, and no join. select_related, prefetch_related and filter(author__name=...) are not available.
• No index. A filter reads each document. To index a hot key, add a functional index on the JSON column.
• The relation manager and the embedded accessor change the document in memory. Call instance.save() after the change.
• Two backends sort a number as text. On MariaDB and Oracle, order_by() on a numeric field puts 10 before 2. PostgreSQL, MySQL and SQLite sort numerically.
• On Oracle, a string field longer than 4000 characters is not queryable. The document keeps the whole value, and an instance returns it. A filter() on that field matches no row, and values_list() gives an empty string, with no error. Keep long text in a column of its own. The measurements.
• No through model. EmbeddedListField keeps the order of the list, and ManyToManyField.all() returns the rows in database order.

FAQ

Questions