JSONField

This class provides a specialized field for handling JSON-encoded data, extending the functionality of a standard character field. It automatically manages the conversion between JSON strings and Python data structures like lists or dictionaries using customizable encoders and decoders. The field also includes built-in validation to ensure input data conforms to valid JSON syntax.

Attributes

Attribute	Type	Description
default_error_messages	dict = {"invalid": _("Enter a valid JSON.")}	A dictionary containing the error message templates used by the field, specifically defining the 'invalid' message for malformed JSON input.
widget	[Widget](../widgets/widget.md?sid=django_forms_widgets_widget) = Textarea	The form widget class used to render the field in the UI, defaulting to a multi-line text input area.

---

Constructor

Signature

def JSONField(
    encoder: class = None,
    decoder: class = None,
    **kwargs: dict
)

Parameters

Name	Type	Description
encoder	class = None	A custom JSON encoder class to use for serialization.
decoder	class = None	A custom JSON decoder class to use for deserialization.
**kwargs	dict	Additional keyword arguments passed to the parent CharField constructor.

---

Methods

---

to_python()

@classmethod
def to_python(
    value: string|object
) - > object

Converts the input value into a Python object by parsing it as JSON. This method handles raw strings, existing Python structures, and ensures invalid JSON strings raise a ValidationError.

Parameters

Name	Type	Description
value	`string	object`

Returns

Type	Description
object	The deserialized Python representation of the JSON data, or a JSONString wrapper for string values.

---

bound_data()

@classmethod
def bound_data(
    data: string,
    initial: object
) - > object

Returns the Python representation of data bound to the form field, handling potential decoding errors gracefully. It returns an InvalidJSONInput marker if the data cannot be parsed.

Parameters

Name	Type	Description
data	string	The raw data submitted via the form for this field.
initial	object	The initial value provided to the field when the form was instantiated.

Returns

Type	Description
object	The decoded Python object or an InvalidJSONInput instance if parsing fails.

---

prepare_value()

@classmethod
def prepare_value(
    value: object
) - > string

Serializes the Python object into a JSON-formatted string suitable for display in a form widget. It preserves non-ASCII characters and handles previously invalid input markers.

Parameters

Name	Type	Description
value	object	The Python object or data structure to be serialized for the widget.

Returns

Type	Description
string	A JSON-encoded string representation of the value.

---

has_changed()

@classmethod
def has_changed(
    initial: object,
    data: string|object
) - > boolean

Determines if the field data has changed by comparing the initial and current values as serialized JSON. This ensures that key ordering and type differences (like 1 vs True) are handled correctly during comparison.

Parameters

Name	Type	Description
initial	object	The original value of the field before user modification.
data	`string	object`

Returns

Type	Description
boolean	True if the data has changed from its initial state, False otherwise.

---