Django JSON Editor

Common errors

• ModuleNotFoundError: No module named 'jsoneditor'

  cause The `jsoneditor` application is either not installed in your Python environment or not correctly added to your `INSTALLED_APPS` in Django's settings.py.
  fix Verify that `pip install django-jsoneditor` completed successfully, and ensure `'jsoneditor'` is present in your `INSTALLED_APPS` list in `settings.py`.

• Changes made in the JSON Editor widget are not saved in Django Admin.

  cause This often occurs because the JavaScript editor's content isn't properly transferred back to the hidden form field (e.g., a `<textarea>`) that Django expects to receive the data upon form submission.
  fix This usually requires custom JavaScript to ensure the JSON Editor instance updates its associated form field before the form is submitted. The underlying `jsoneditor` library exposes an instance (e.g., `window['FIELD_ID_editor']` or `container.jsonEditor`) that can be used to `get()` the current value and `set()` it on the hidden form input.

• JSONEditor library not loaded in form assets / JavaScript errors related to JSONEditor not being defined on non-admin pages.

  cause The static files for the JSON Editor widget (JavaScript and CSS) might not be correctly served or included when using the widget outside of Django's admin interface, or due to incorrect `STATICFILES_FINDERS` configuration.
  fix Ensure `django.contrib.staticfiles` is configured correctly and `python manage.py collectstatic` has been run. If used in custom forms, you may need to manually include the widget's media assets in your template, or ensure your form renders its media correctly (e.g., `{{ form.media }}`).

Warnings

• gotcha This library only provides a widget for editing JSON data. It does NOT provide a `JSONField` itself. You must use Django's built-in `django.db.models.JSONField` (available from Django 3.1+, or with `django.contrib.postgres` for older versions) or a compatible third-party `JSONField` package.
  Fix: Ensure your model's JSON field is defined using `django.db.models.JSONField` or a compatible alternative like `django-jsonfield`.
• gotcha The underlying JavaScript JSON Editor library (which uses the Ace editor) is considered by some to be 'out-of-date' and can experience issues with very large JSON documents (e.g., crashing, reverting to `TextArea` in read-only mode). Newer alternatives like `django-svelte-jsoneditor` exist.
  Fix: For basic use cases, this may not be an issue. For highly interactive, large-document, or modern UI needs, consider evaluating `django-svelte-jsoneditor` or other alternatives.
• gotcha Customizing the JSON Editor's JavaScript initialization (e.g., setting default modes or options) requires copying the library's `init.js` file to your static storage and configuring `JSON_EDITOR_INIT_JS` in your Django settings to point to your modified copy.
  Fix: Refer to the GitHub README's 'Custom JSONEditor initialization' section for detailed steps on setting `JSON_EDITOR_INIT_JS` and modifying the `init.js` file.

Install

• pip install django-jsoneditor Install stable version from PyPI

Imports

• JSONEditor
  wrong:

  from django_jsoneditor.forms import JSONEditor

  correct:

  from jsoneditor.forms import JSONEditor

  The top-level package name in `INSTALLED_APPS` and imports is 'jsoneditor', not 'django_jsoneditor'.
• INSTALLED_APPS
  wrong:

  INSTALLED_APPS = [
      # ...
      'django_jsoneditor',
      # ...
  ]

  correct:

  INSTALLED_APPS = [
      # ...
      'jsoneditor',
      # ...
  ]

  The app name to register in Django settings is 'jsoneditor', not 'django_jsoneditor'.
• JSONField
  wrong:

  from jsoneditor.fields.postgres_jsonfield import JSONField # unless explicitly replacing the original

  correct:

  from django.db import models # then models.JSONField for formfield_overrides

  For `formfield_overrides`, you typically reference Django's native `JSONField` or the one from your model's source. The `jsoneditor.fields` module provides specific, 'fixed' JSONField implementations for older Django versions or third-party JSONFields, which is a less common direct import for basic usage.

Quickstart

To quickly integrate `django-jsoneditor` into your Django admin, add `jsoneditor` to your `INSTALLED_APPS` and then override the default widget for `JSONField` in your `admin.py` using `formfield_overrides`. Ensure you have an appropriate `JSONField` defined in your model, such as `django.db.models.JSONField` (for Django 3.1+ or with PostgreSQL) or a compatible third-party `JSONField`.

# settings.py
INSTALLED_APPS = [
    # ...
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'jsoneditor', # Add this line
    # ...
]

# models.py (Example using Django's native JSONField)
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=255)
    data = models.JSONField(default=dict)

    def __str__(self):
        return self.name

# admin.py
from django.contrib import admin
from django.db import models
from .models import MyModel
from jsoneditor.forms import JSONEditor

@admin.register(MyModel)
class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.JSONField: {'widget': JSONEditor},
    }