django-jsonform

2.23.2 · active · verified Wed Apr 15

django-jsonform is a Django library that provides a user-friendly form interface for editing JSON data directly within the Django admin. It leverages JSON schema to define the structure of the JSON data, automatically generating dynamic forms for creating and editing. The library also supports PostgreSQL's ArrayField with multiple levels of nesting. As of version 2.23.2, it maintains an active development pace with several releases per year, addressing bugs and introducing new features.

Warnings

gotcha After installing or upgrading, you must run `python manage.py collectstatic` in your production environment (and often development) to ensure the necessary JavaScript and CSS files are available. Failure to do so will result in the JSON form not rendering correctly or at all.
Fix: Run `python manage.py collectstatic` after installation or any upgrade.
gotcha Changing the JSON schema for an existing `JSONField` can lead to discrepancies with pre-existing JSON data. `django-jsonform` does not provide an automatic data migration mechanism; you'll need to manually migrate or transform old JSON data to conform to the new schema, typically from a Django shell.
Fix: Manually update existing JSON data in the database to match the new schema structure, or implement custom data migration scripts.
deprecated The `JSONFORM_UPLOAD_HANDLER` setting for file uploads was deprecated in version 2.11. It is kept for backward compatibility but will be removed in future versions. You should now use the `FILE_HANDLER` key within the main `DJANGO_JSONFORM` settings dictionary.
Fix: Update your `settings.py` to use `DJANGO_JSONFORM = {'FILE_HANDLER': 'your_app.views.your_handler_view_url'}` instead of `JSONFORM_UPLOAD_HANDLER`.
breaking When implementing custom validation (e.g., using `JSONSchemaValidationError`), from version 2.15.0 onwards, you should use the `ErrorMap` helper class to construct the `error_map` object. This change was introduced to properly support schema object keys (field names) containing hyphens.
Fix: Refactor custom validation logic to utilize `django_jsonform.utils.ErrorMap` for building error dictionaries.
gotcha Versions prior to 2.21.5 had a bug due to a missing UUID import, which could cause a `NameError` exception when using UUID-related fields.
Fix: Upgrade to `django-jsonform` version 2.21.5 or newer.
gotcha In versions prior to 2.21.3, there were layout issues in Django 4.x, causing the form to render very narrowly in the admin interface.
Fix: Upgrade to `django-jsonform` version 2.21.3 or newer to resolve Django 4.x layout problems.

Install

pip install django-jsonform Install stable version

Imports

JSONField

from django_jsonform.models.fields import JSONField

JSONFormWidget
```
from django_jsonform.widgets import JSONFormWidget
```
Primarily used internally by JSONField, but can be imported for custom form setups.
JSONSchemaValidationError
```
from django_jsonform.exceptions import JSONSchemaValidationError
```
Required for advanced custom validation to provide field-specific error messages.
ErrorMap
```
from django_jsonform.utils import ErrorMap
```
Used in advanced custom validation for mapping errors to specific schema paths.

Quickstart

To quickly integrate `django-jsonform`, define a `JSONField` in your Django model with a corresponding JSON schema. Then, register your model with the Django admin. The library will automatically render a dynamic form based on your schema. Remember to add `django_jsonform` to your `INSTALLED_APPS` and run `collectstatic` for the JavaScript assets to load correctly.

from django.db import models
from django.contrib import admin
from django_jsonform.models.fields import JSONField

# models.py
class ShoppingList(models.Model):
    name = models.CharField(max_length=255)
    items = JSONField(
        schema={
            'type': 'array',
            'title': 'Shopping Items',
            'items': {
                'type': 'dict',
                'keys': {
                    'item_name': {'type': 'string', 'title': 'Item Name'},
                    'quantity': {'type': 'integer', 'title': 'Quantity', 'minimum': 1}
                }
            }
        },
        help_text='A list of items for shopping.'
    )

    def __str__(self):
        return self.name

# admin.py
# Ensure 'django_jsonform' is in INSTALLED_APPS in settings.py
@admin.register(ShoppingList)
class ShoppingListAdmin(admin.ModelAdmin):
    list_display = ('name',)

# To see the form in action:
# 1. Add 'django_jsonform' to INSTALLED_APPS in your settings.py
# 2. Run 'python manage.py makemigrations' and 'python manage.py migrate'
# 3. Run 'python manage.py createsuperuser' and log in to the Django admin.

view raw JSON →