json-indent 2.7.1

Simple Python-based JSON parser/indenter/formatter

json-indent

This is a simple Python-based tool for parsing/indenting/formatting JSON.

Python's json module actually contains such a tool; it's even simpler and is missing twiddles for specifying the amount of indent, whether to (re)compact, and whether to sort keys when parsing.

json-indent can be useful:

• On the command-line
• From within Vim or similar editors
• As a pre-commit hook

(js-beautify is another such tool; it can parse JavaScript as well as JSON, but it has no built-in pre-commit hook).

Contents

• Requirements
• Installing
• How to Use
  • Quickstart
• Command-line Autocompletion
• Advanced Topics
  • Pre-Commit Hook
  • Integration with Vim
• Developing json-indent
• References

Requirements

• A Python interpreter, version 3.7 or later (version 2.7 support is deprecated, but may still work)

Installing

It is recommended to install json-indent either:

• In its own virtual environment (for example, using uv), or
• As a pre-commit hook

To install with uv:

uv tool install json-indent

How to Use

For a summary of all the available options:

uv tool run json-indent --help

Or, with the uvx shortcut:

uvx json-indent --help

Or, if you prefer to call the script directly:

/path/to/json-indent --help

[!TIP]

There are a number of different ways to run tools that are delivered as Python modules. For the remainder of this document, we will use uvx json-indent to mean whichever one you prefer for your Python installation and operating environment.

See How to Run Your Python Scripts for more details.

Quickstart

To read JSON from a file, parse it, and write it to the standard output:

uvx json-indent input.json

To write to a file instead:

uvx json-indent -o output.json input.json

To read from the standard input, you can use - as the filename:

uvx json-indent -o - -

Or simply:

uvx json-indent

To modify a file in place:

uvx json-indent --inplace input.json

To display json-indent's version:

uvx json-indent --version

See the command-line help for more options, including:

• Indent size
• "Compact" mode
• Key sorting

Command-line Autocompletion

json-indent provides command-line autocompletion for the Bash command-line shell and compatible shells, using the argcomplete Python package.

For instructions on how to enable completion:

uvx json-indent --completion-help

Advanced Topics

Pre-Commit Hook

json-indent has support for the pre-commit framework for running tools before committing to your git project. The hook will:

1. Parse your JSON files and emit messages about any errors it encounters.
2. Format and indent your JSON files according to the --indent, --compact, and --sort-keys options you supply (or their default values if you don't supply one).

To add a hook for json-indent to your project, use the following YAML in your project's .pre-commit-config.yaml:

  - repo: https://github.com/jmknoble/json-indent
    rev: v2.4.0
    hooks:
      - id: json-indent

[!NOTE]

HOW IT WORKS:

Under the hood this uses a .pre-commit-hooks.yaml file in the root of the Git project to define the parameters of the pre-commit hook.

Key info:

• json-indent must accept multiple input files on the command line.
• The --inplace option is needed in order to automatically indent JSON source files.

Integration with Vim

You can use json-indent from within Vim to format JSON directly in your editing session.

To enable this functionality, you can add the following to your vimrc file:

""""""""""""""""""""""""""""""""""""""""
" JSON parsing/indenting
" https://github.com/jmknoble/json-indent
"
" Normal mode
"
" Compact JSON stanza starting at current character (uses '%' to move to matching brace)
nmap <Leader>jc :%!json-indent -c
nmap <Leader>JC <Leader>jc
"
" Parse/indent JSON stanza contained in current line
nmap <Leader>jp 0!$json-indent<CR>j
nmap <Leader>JP <Leader>jp
"
" Parse/indent JSON stanza contained in current line with sorted keys
nmap <Leader>js 0!$json-indent -s<CR>j
nmap <Leader>JS <Leader>js
"
" Visual mode
"
" Compact JSON stanza contained in current selection
vmap <Leader>jc !json-indent -c<CR>j
vmap <Leader>JC <Leader>jc
"
" Parse/indent JSON stanza contained in current selection
vmap <Leader>jp !json-indent
vmap <Leader>JP <Leader>jp
"
" Parse/indent JSON stanza contained in current selection with sorted keys
vmap <Leader>js !json-indent -s<CR>j
vmap <Leader>JS <Leader>js
""""""""""""""""""""""""""""""""""""""""

[!TIP]

This uses the !command feature to run an external command as a filter.

Use the Vim command :help mapleader (or see mapleader) for an explanation of <Leader>.

Developing json-indent

See DEVELOPING.

References

• Python:
  • How to Run Your Python Scripts
  • argcomplete on PyPI and GitHub
• pre-commit
• Vim:
  • Intro to vimrc
  • Vim filters
  • Vim's Leader key
• js-beautify