Fixed #12990, Refs #27694 -- Added JSONField model field.

Thanks to Adam Johnson, Carlton Gibson, Mariusz Felisiak, and Raphael
Michel for mentoring this Google Summer of Code 2019 project and
everyone else who helped with the patch.

Special thanks to Mads Jensen, Nick Pope, and Simon Charette for
extensive reviews.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

1 files changed, 54 insertions, 0 deletions

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index 3d228e88ad..58db957512 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -776,6 +776,60 @@ For each field, we describe the default widget used if you don't specify
 
     These control the range of values permitted in the field.
 
+``JSONField``
+-------------
+
+.. class:: JSONField(encoder=None, decoder=None, **kwargs)
+
+    .. versionadded:: 3.1
+
+    A field which accepts JSON encoded data for a
+    :class:`~django.db.models.JSONField`.
+
+    * Default widget: :class:`Textarea`
+    * Empty value: ``''`` (an empty string)
+    * Normalizes to: A Python representation of the JSON value (usually as a
+      ``dict``, ``list``, or ``None``), depending on :attr:`JSONField.decoder`.
+    * Validates that the given value is a valid JSON.
+    * Error message keys: ``required``, ``invalid``
+
+    Takes two optional arguments:
+
+    .. attribute:: encoder
+
+        A :py:class:`json.JSONEncoder` subclass to serialize data types not
+        supported by the standard JSON serializer (e.g. ``datetime.datetime``
+        or :class:`~python:uuid.UUID`). For example, you can use the
+        :class:`~django.core.serializers.json.DjangoJSONEncoder` class.
+
+        Defaults to ``json.JSONEncoder``.
+
+    .. attribute:: decoder
+
+        A :py:class:`json.JSONDecoder` subclass to deserialize the input. Your
+        deserialization may need to account for the fact that you can't be
+        certain of the input type. For example, you run the risk of returning a
+        ``datetime`` that was actually a string that just happened to be in the
+        same format chosen for ``datetime``\s.
+
+        The ``decoder`` can be used to validate the input. If
+        :py:class:`json.JSONDecodeError` is raised during the deserialization,
+        a ``ValidationError`` will be raised.
+
+        Defaults to ``json.JSONDecoder``.
+
+    .. note::
+
+        If you use a :class:`ModelForm <django.forms.ModelForm>`, the
+        ``encoder`` and ``decoder`` from :class:`~django.db.models.JSONField`
+        will be used.
+
+    .. admonition:: User friendly forms
+
+        ``JSONField`` is not particularly user friendly in most cases. However,
+        it is a useful way to format data from a client-side widget for
+        submission to the server.
+
 ``GenericIPAddressField``
 -------------------------