From 348ca845385beaddc7c862ff8ec369f041a5088d Mon Sep 17 00:00:00 2001
From: Clifford Gama <cliffygamy@gmail.com>
Date: Fri, 24 Oct 2025 23:38:52 +0200
Subject: Refs #35381 -- Deprecated using None in JSONExact rhs to mean JSON
 null.

Key and index lookups are exempt from the deprecation.

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>
---
 docs/releases/6.1.txt      |  7 +++++++
 docs/topics/db/queries.txt | 14 ++++++++++++++
 2 files changed, 21 insertions(+)

(limited to 'docs')

diff --git a/docs/releases/6.1.txt b/docs/releases/6.1.txt
index 412ec692e3..dba26cca05 100644
--- a/docs/releases/6.1.txt
+++ b/docs/releases/6.1.txt
@@ -360,6 +360,13 @@ Miscellaneous
   is deprecated. Pass an explicit field name, like
   ``values_list("pk", flat=True)``.
 
+* The use of ``None`` to represent a top-level JSON scalar ``null`` when
+  querying :class:`~django.db.models.JSONField` is now deprecated in favor of
+  the new :class:`~django.db.models.JSONNull` expression. At the end
+  of the deprecation period, ``None`` values compile to SQL ``IS NULL`` when
+  used as the top-level value. :lookup:`Key and index lookups <jsonfield.key>`
+  are unaffected by this deprecation.
+
 Features removed in 6.1
 =======================
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index 788a418e4f..b3b6ec125d 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -1069,6 +1069,11 @@ as JSON ``null``.
 When querying, :lookup:`isnull=True <isnull>` is used to match SQL ``NULL``,
 while exact-matching ``JSONNull()`` is used to match JSON ``null``.
 
+.. deprecated:: 6.1
+
+    Exact-matching ``None`` in a query to mean JSON ``null`` is deprecated.
+    After the deprecation period, it will be interpreted as SQL ``NULL``.
+
 .. versionchanged:: 6.1
 
     ``JSONNull()`` expression was added.
@@ -1080,6 +1085,12 @@ while exact-matching ``JSONNull()`` is used to match JSON ``null``.
     <Dog: Max>
     >>> Dog.objects.create(name="Archie", data=JSONNull())  # JSON null.
     <Dog: Archie>
+    >>> Dog.objects.filter(data=None)
+    ...: RemovedInDjango70Warning: Using None as the right-hand side of an
+    exact lookup on JSONField to mean JSON scalar 'null' is deprecated. Use
+    JSONNull() instead (or use the __isnull lookup if you meant SQL NULL).
+    ...
+    <QuerySet [<Dog: Archie>]>
     >>> Dog.objects.filter(data=JSONNull())
     <QuerySet [<Dog: Archie>]>
     >>> Dog.objects.filter(data__isnull=True)
@@ -1087,6 +1098,9 @@ while exact-matching ``JSONNull()`` is used to match JSON ``null``.
     >>> Dog.objects.filter(data__isnull=False)
     <QuerySet [<Dog: Archie>]>
 
+.. RemovedInDjango70Warning: Alter the example with the deprecation warning to:
+  <QuerySet [<Dog: Max>]>.
+
 Unless you are sure you wish to work with SQL ``NULL`` values, consider setting
 ``null=False`` and providing a suitable default for empty values, such as
 ``default=dict``.
-- 
cgit v1.3