[Django] #37349: Add note about object key order in JSONField docs

[Django]

#37349: Add note about object key order in JSONField docs
-------------------------+------------------------------------------------
Reporter: Lincoln | Type: Cleanup/optimization
Status: new | Component: Documentation
Version: dev | Severity: Normal
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------+------------------------------------------------
Using JSONField with PostgreSQL, storing a `dict` in the field and then
later retrieving it, will not preserve the key order,

because PostgreSQL `jsonb` type "does not preserve the order of object
keys" (https://www.postgresql.org/docs/current/datatype-json.html).

This behavior can be surprising, because python `dict` does preserve key
order, and storing/retrieving `dict`s with `json.dumps`/`json.loads` will
preserve key order.

So, I am proposing to add a note to the `JSONField` docs explaining that
key order may not be preserved. This could go in either the current
"PostgreSQL users" note, or a new note. This probably depends on if the
other DB backends preserve key order. I haven't checked if any of the
others do.
--
Ticket URL: <https://code.djangoproject.com/ticket/37349>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37349: Add note about object key order in JSONField docs

-------------------------------------+-------------------------------------
Reporter: Lincoln | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Comment (by David Sanders):

I believe the docs policy is not to document other systems, rather refer
to them.

Other than key order there are other items that some folks may find
interesting:

> Because the json type stores an exact copy of the input text, it will
preserve semantically-insignificant white space between tokens, as well as
the order of keys within JSON objects. Also, if a JSON object within the
value contains the same key more than once, all the key/value pairs are
kept. (The processing functions consider the last value as the operative
one.) By contrast, jsonb does not preserve white space, does not preserve
the order of object keys, and does not keep duplicate object keys. If
duplicate keys are specified in the input, only the last value is kept.
--
Ticket URL: <https://code.djangoproject.com/ticket/37349#comment:1>

[Django]

#37349: Add note about object key order in JSONField docs

--------------------------------------+------------------------------------
Reporter: Lincoln | Owner: (none)
Type: Cleanup/optimization | Status: new

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

Comment:

I think adding a link to the Postgres docs considering we already have a
section on the `jsonb` vs `json` types makes sense. I am also ok with a
small note about the key order.
I agree with David that we try not to document other systems, but as we
already have a section on this, I am comfortable with making that section
slightly more informative.

My suggestion would be:
{{{#!diff
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -1508,8 +1508,12 @@ To query ``JSONField`` in the database, see :ref
:`querying-jsonfield`.
queried. PostgreSQL's ``json`` field is stored as the original string
representation of the JSON and must be decoded on the fly when
queried
based on keys. The ``jsonb`` field is stored based on the actual
structure
- of the JSON which allows indexing. The trade-off is a small
additional cost
- on writing to the ``jsonb`` field. ``JSONField`` uses ``jsonb``.
+ of the JSON, which allows indexing but doesn't preserve the order of
object
+ keys. The trade-off is a small additional cost on writing to the
``jsonb``
+ field. ``JSONField`` uses ``jsonb``.
+
+ For more details, see PostgreSQL's `documentation on JSON types
+ <https://www.postgresql.org/docs/current/datatype-json.html>`_.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/37349#comment:2>

[Django]

#37349: Add note about object key order in JSONField docs

-------------------------------------+-------------------------------------
Reporter: Lincoln | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by SnippyCodes):

* owner: (none) => SnippyCodes
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/37349#comment:3>

[Django]

#37349: Add note about object key order in JSONField docs
-------------------------------------+-------------------------------------
Reporter: Lincoln | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by SnippyCodes):

I will take this on! I will apply Sarah's suggested wording to
docs/ref/models/fields.txt and ensure the paragraph is wrapped to 80
characters.
--
Ticket URL: <https://code.djangoproject.com/ticket/37349#comment:4>

[Django]

#37349: Add note about object key order in JSONField docs
-------------------------------------+-------------------------------------
Reporter: Lincoln | Owner:
Type: | SnippyCodes
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by SnippyCodes):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/37349#comment:5>