JSONSchemaField

JSON Schema is a standardized format for defining the structure, required fields, data types, and validation rules for JSON data. It enables consistent validation and documentation of JSON objects.

This field's functionality is based on jedison, a library for integrating JSON Schema validation and dynamic form generation into Django model fields. By leveraging jedison, JSONSchemaField provides robust schema-based validation and seamless admin/editor integration.

Note: The jsonschema package is optional but highly recommended. Without installing jsonschema, backend validation for JSONSchemaField will not work.

uv add jsonschema

JSONSchemaField is an advanced field type for Django models, built on top of Django's native JSONField. In addition to all the features of JSONField, it provides powerful schema-based validation using the JSON Schema specification.

The most important addition is the required schema parameter, which must be provided as a Python dict. This schema defines the expected structure, data types, requirements, and validation rules for the JSON data stored in the field. The field will use this schema both to validate input and, with jedison/editor integration, to generate dynamic forms and inputs in the Django admin or custom editors.

By enforcing the schema at the model level, JSONSchemaField ensures consistency and validity of all stored JSON data, making it an ideal choice for situations where you want strongly typed and well-validated structured data inside your models.

# models.py

from django.db import models
from unfold.models.fields import JSONSchemaField


class MyModel(models.Model):
    specification = JSONSchemaField(
        schema={
            "title": "Contact",
            "type": "object",
            "additionalProperties": False,
            "properties": {
                "name": {
                    "title": "Name",
                    "type": "string",
                    "minLength": 1,
                },
            },
        },
        verbose_name=_("specification"),
        null=True,
        blank=True,
        default=dict,
    )

In addition to providing a static Python dictionary for the field schema, JSONSchemaField also allows you to specify the schema using a callback function. This can be accomplished by passing the Python dotted path (as a string) to a callable that returns a dictionary representing the JSON schema. When Django initializes the field, it will import and execute this function to retrieve the schema definition.

This approach is especially helpful when you need to generate the schema dynamically based on settings, environment variables, or other application-level context that might change at runtime. For example, you might switch schema structure depending on your site’s configuration, feature flags, or external integration states. However, note that the callback does not have access to per-request data such as the current user or request object, since the schema is resolved statically when the model is loaded or migrated, rather than on each form render. As such, dynamic schema logic should be general to the application or project as a whole, rather than user-specific or request-specific.

By leveraging schema callback functions, you can make your model fields adaptive to evolving requirements while maintaining robust validation and editor support.

# models.py

from django.db import models
from unfold.models.fields import JSONSchemaField


class MyModel(models.Model):
    json_schema = JSONSchemaField(
        # Create schema from callback function
        schema="app.utils.jsonschema_callback",
        verbose_name=_("JSON schema"),
        null=True,
        blank=True,
        default=dict,
    )

# app.utils.py
def jsonschema_callback():
    return {
        "title": "Contact",
        "type": "object",
        "additionalProperties": False,
        "properties": {
            "name": {
                "title": "Name",
                "type": "string",
                "minLength": 1,
            },
        },