ujson5

Documentation

CI/CD
Coverage / Codspeed
Package
Meta

ujson5 is a Python that encodes and decodes JSON5, a superset of JSON that supports many human-friendly features such as comments, trailing commas, and more!

Why use JSON5?

Direct quote from the JSON5 website:

JSON5 was started in 2012, and as of 2022, now gets >65M downloads/week, ranks in the top 0.1% of the most depended-upon packages on npm, and has been adopted by major projects like Chromium, Next.js, Babel, Retool, WebStorm, and more. It's also natively supported on Apple platforms like macOS and iOS.

Why use ujson5?

• Gentle learning curve - If you know how to use the json module in Python, you already know how to use ujson5. ujson5 API is almost identical to the json module with some additional features.
• Robust test suite - ujson5 is tested against the most famous JSON5 test suite to ensure compatibility. See the testing section for more information.
• Speed - ujson5 tokenizer and parser implement DFA-based algorithms for fast parsing, which is only slightly slower than the built-in json module.
• Pythonic - Comments in python are directly encoded into JSON5 comments. Magic!
• Quality code base - ujson5 is linted with flake8, formatted with black, and type-checked with mypy. What's more? 100% test coverage with pytest and codecov!
• Friendly Error Messages - ujson5 provides detailed error messages to help you debug your JSON5 files, including the exact location of the error.
• Type hints - ujson5 provides type hints for all public functions and classes.

Installation

pip install ujson5

Quick Start

You can use ujson5 just like the built-in json module. Here is a quick example:

from typing import TypedDict
import ujson5

# Decode JSON5
json5_str = """
{
  // comments
  key: 'value', // trailing comma
}
"""

data = ujson5.loads(json5_str)
print(data)  # {'key': 'value'}


# Encode JSON5
class Data(TypedDict):
    # multiple long comments
    # are supported
    key: str  # inline comment


data = {"key": "value"}
json5_str = ujson5.dumps(data, Data, indent=2)
print(json5_str)
# {
#   // multiple long comments
#   // are supported
#   "key": "value",  // inline comment
# }

CLI Usage

After installing ujson5, you can use the ujson5 command-line interface to convert JSON5 files to JSON files or simply validate JSON5 files. The CLI interface is the same as the official JSON5 CLI.

Installation

Make sure you have installed the package in these three ways to use the CLI:

• Install using pipx (recommended): pipx install ujson5
• Install to the global interpreter: pip install ujson5
• Install to a virtual env and activate it.

Usage

ujson5 module can be used as a console script. The basic usage is:

ujson5 <infile> <outfile> [options]

If the optional infile and outfile arguments are not specified, sys.stdin and sys.stdout will be used respectively:

echo '{"json": "obj"}' | ujson5
{
    "json": "obj"
}

Options:

• infile: The JSON5 file to be validated or converted to JSON. If not specified, read from sys.stdin.

• outfile: The JSON file to output the converted JSON. If not specified, output to sys.stdout.

• -v, --version: Print the version number.

• -i, --info: Print the version number and system information.

• --sort-keys: Sort the output of dictionaries alphabetically by key.

• --no-ensure-ascii: Disable escaping of non-ascii characters, see [ujson5.dumps()][ujson5.dumps] for more information.

• --indent, --no-indent, --compact: Mutually exclusive options for whitespace control.

• -h, --help: Output usage information

Testing

ujson5 is tested against fixtures in the JSONTestSuite, nativejson-benchmark, and json5-tests repositories. It is tested to not crash against the Big List of Naughty Strings.

Changelog

v1.0.1 (2025-03-19)

GitHub release

What's Changed

• Makefile automation by @austinyu in #13
• Fixed incorrect comments extraction by @austinyu in #18
• Trunk quality compliance by @austinyu in #19
• Release pipeline done by @austinyu in #21

Full Changelog

v1.0.0a (2025-03-07)

GitHub release

What's Changed

• Fixed wrong wheel name generated by shallow clone repo in CI by @austinyu in https://github.com/austinyu/ujson5/pull/7
• Migrating to uv and hatch as project management tool and build tool. by @austinyu in https://github.com/austinyu/ujson5/pull/8
• Improve on package metadata by @austinyu in https://github.com/austinyu/ujson5/pull/10

New Contributors

• @austinyu made their first contribution in https://github.com/austinyu/ujson5/pull/7

Full Changelog