Skip to content

gh-136216: Updated mentioned RFC in json module#149322

Open
Viicos wants to merge 1 commit intopython:mainfrom
Viicos:gh-136216
Open

gh-136216: Updated mentioned RFC in json module#149322
Viicos wants to merge 1 commit intopython:mainfrom
Viicos:gh-136216

Conversation

@Viicos
Copy link
Copy Markdown
Contributor

@Viicos Viicos commented May 3, 2026

@bedevere-app bedevere-app Bot added the docs Documentation in the Doc dir label May 3, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs May 3, 2026
Comment thread Doc/library/json.rst
Comment on lines +853 to +854
.. [#rfc-errata] As noted in `the errata for RFC 8259
<https://www.rfc-editor.org/errata_search.php?rfc=8259>`_,
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the errata for RFC 7159 wasn't really solved in 8259, but another errata (with different wording) also exists for RFC 8259.

The footnote is referenced here:

`JSON (JavaScript Object Notation) <https://json.org>`_, specified by
:rfc:`7159` (which obsoletes :rfc:`4627`) and by
`ECMA-404 <https://ecma-international.org/publications-and-standards/standards/ecma-404/>`_,
is a lightweight data interchange format inspired by
`JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax
(although it is not a strict subset of JavaScript [#rfc-errata]_ ).

Is it really relevant for the Python documentation? Should we remove this sentence entirely?

@read-the-docs-community
Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #32516119 | 📁 Comparing 15d725c against main (836fbda)

  🔍 Preview build  

13 files changed · ± 13 modified

± Modified

Comment thread Doc/library/json.rst
Comment on lines 655 to 656
The RFC requires that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the recommended default for maximum interoperability.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is a bit ambiguous, and doesn't really match the last RFC which, as discussed in #136216 (comment), was updated to state:

JSON text exchanged between systems that are not part of a closed ecosystem MUST be encoded using UTF-8.

The documentation sentence is thus outdated, but also doesn't mention that thus us related to exchange between systems (which is out of scope of the json module, again as per #136216 (comment)). I see a couple options:

  • Remove this sentence entirely.

  • Update it with something like:

    Suggested change
    The RFC requires that JSON, when exchanged between systems, must be represented using UTF-8.
    The :mod:`!json` module doesn't handle the string encoding of JSON produced by the :func:`dump`
    and :func:`dumps` functions. However, for maximum interoperability, :func:`load` and :func:`loads
    will guess the encoding for :term:`binary file`, :class:`bytes` and :class:`bytearray` inputs.

Comment thread Doc/library/json.rst

Other than the *ensure_ascii* parameter, this module is defined strictly in
terms of conversion between Python objects and
:class:`Unicode strings <str>`, and thus does not otherwise directly address
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had #136215 opened to remove the Unicode reference. Should I include it here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

The referenced RFC for the json module should be corrected to rfc8259

1 participant