Add note about object key order in JSONField docs

[Lincoln]

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 dicts 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.

[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.

[Sarah Boyce]

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:

docs/ref/models/fields.txt

@@ -1508 +1508 @@
     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>`_.

[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.