- JSONデータを人が読みやすく整形しながら、圧縮された形も維持するフォーマットユーティリティ群
- 配列とオブジェクトを可能な限り1行で表現し、構造が似ている場合はテーブル形式で整列
- コメント保持機能をサポートし、JSON標準にはないものの実運用でよく使われるコメントもそのまま維持
- .NETライブラリ、JavaScript/TypeScriptパッケージ、VS Code拡張機能、ブラウザフォーマッタなど、さまざまな環境で利用可能
- 既存のJSONフォーマッタの可読性の限界を改善し、開発者やデータアナリストの視覚的理解を高めるツール
FracturedJson 概要
- FracturedJsonは、人が読みやすく、かつ比較的コンパクトなJSONフォーマットを生成するユーティリティ群
- 配列とオブジェクトは、長すぎたり複雑すぎたりしなければ1行で出力
- 構造が似ている複数行は、フィールドを揃えてテーブル形式で表示
- 長い配列は複数行にまたがって、1行に複数項目を配置
- さまざまな設定で出力形式を制御でき、多くの場合はデフォルト設定だけでも見やすい結果を生成
- ブラウザベースのフォーマッタページ、.NETライブラリ、JavaScript/TypeScriptパッケージ、VS Code拡張機能として提供
- Python向けのオプションも別途案内されている
Motivation
- ほとんどのJSONライブラリは2つの形式しか提供しない
- Minified JSON: 効率的だが人には読みにくい
- Beautified/Indented JSON: 横に広がりすぎていて、素早い把握が難しい
- FracturedJsonは、人が直接書いたようにデータをフォーマット
- 複雑すぎたり長すぎたりする場合を除き、コンテナを1行に維持
- 類似した配列やオブジェクトはテーブル形式で整列
動作方式 (How It Works)
- FracturedJsonは4つのフォーマットタイプを使用
- Inlined: 短く単純なオブジェクトや配列を1行で表現
MaxInlineComplexity設定で許容されるネストレベルを制御
- Compact Multiline Array: 複数項目を1行に配置しつつ、複数行に分けて表示
MaxCompactArrayComplexityでネスト許容度を調整し、-1で無効化可能
- Table: 似た構造の項目を列揃え形式で整列
- 内部コンテナが複雑すぎる場合は一部のみ縮約
MaxTableRowComplexityとTableCommaPlacementで制御可能
- Expanded: 上記条件に合わない場合、各項目を複数行にインデントして表示
コメント処理
- JSON標準はコメントを許可しないが、FracturedJsonはコメント保持機能をサポート
- コメントは関連する要素とともに維持され、複数行コメントとインラインコメントの両方を処理可能
Discussions
- ユーザーの質問、フィードバック、提案などのためのGitHub Discussionsスペースを提供
- プロジェクトに関する議論や改善提案が可能
1件のコメント
Hacker News のコメント
現在、このプロジェクトには保守されている実装が 2 つある。
1 つは C# 版（FracturedJson .NET Library）、もう 1 つは TypeScript/JavaScript 版（FracturedJsonJs）。
以前は純粋な Python 版もあったが、今は保守されておらず、代わりに C# コードをラップした Python ラッパー（fractured-json）に置き換えられている。
この Python 版は .NET ランタイムが必要だと明記されているため、pip install だけでは導入しづらいのが欠点。
こういう状況は、言語非依存の conformance suite を作る良い機会だと思う。つまり、複数の実装が同じように動作するかを検証できるデータ駆動型のテストセットのこと。
ちなみに以前の Python 版は、すでにこの形式のテストを使っていた（compact-json のテストデータ）。
元のコメントに追記してもよさそう。
詳しくは fracturedjson-rs GitHub と crates.io パッケージ を参照。
関連する説明コメントは こちら。
html5lib-tests や、私が作った xss-bench もその例。
Rust に移植した版を作っており、CLI ツール経由で JSON をこのフォーマットに整形できる。
fracturedjson-rs と crates.io パッケージ からインストール可能（
cargo install fracturedjson）。さまざまなオプションを備えており、コメント処理方式、インデントスタイル、行幅制限 などを細かく制御できる。
このプロジェクトは本当に素晴らしい。
JSON をより 人間が読みやすく する方向性が良い。
私は逆に JSON をより 機械向け にした bonjson を開発中。
JSON と完全に同じ機能と制約を持ちつつ、35 倍高速に読み書きできる。
新しい型や機能はなく、JSON ができることだけを正確に実行する。
たとえば数値のビット幅や整数／浮動小数点の区別が明示されていない。
こうしたモデルがあれば、表現間の 1:1 マッピングが可能になるはず。
関連する話題として この記事 を書いている。
たとえば
"a\u0000b"のような文字列は有効な JSON だが、これをシリアライズできないなら、その主張は完全には成り立たない。私は JSON とバイナリファイルを共通インターフェースで保存・読み込みする シリアライザ を作ったことがある。
私の経験では、JSON は 制約が多く利点が少ない フォーマットだった。
そのため、カンマ、コロン、引用符を省略できて、複数行文字列とコメントを許す緩いフォーマットに変えた。
JSON が常に「人間に読みやすい」フォーマットであるかのように扱うのは、もうやめてほしい。
非 JSON 中心の環境向けに標準的な代替手段が必要。
驚いた。
私も似たような機能を Python で 200 行ほどで実装したが、すでにこういうライブラリがあるとは知らなかった。
jq のように パイプ入力 を受け取れるオプションがあるのか気になる。
JavaScript 版と Python ラッパーも同じ CLI ツールを提供している。
rcl eで RCL フォーマットを、rcl jeで JSON 出力を見られる。FracturedJson のようなテーブル整列はないが、Philip Wadler の A Prettier Printer アルゴリズムに基づいて幅に合わせて自動改行する。
<()のプロセス置換で一時ファイルを作って処理することもできる。-を指定すれば stdin から読める。私は Virtuous という JSON フォーマッタを作ったのだが、これを見て自分のフォーマッタを捨てようかと思うほど感銘を受けた。
本当に 見事な仕事 だ。
私は「mommyjson」という Groovy スクリプト を作った。
JSON のフォーマットを保つというより、各要素の 親子関係（配列インデックス、オブジェクト名など）を 1 行に表示して、データの位置を直感的に把握できるようにするもの。
コードを見る
Groovy は人気がないので、Python ポートが出るといいのだが。
代表例として gron と、私が作った jstream がある。
使用例の出力 を追加すると、さらに分かりやすくなりそう。
JSON が本当に 人間が読みやすいよう改善する必要 のあるフォーマットなのか疑問。
ユーザーにデータを見せるもっと良い方法はいくらでもあるし、JSON はシステム間のデータ転送に使うのが本来だと思う。
複雑にネストしたデータを素早く把握しなければならないデバッグ状況で役立つ。
特に外部システムとの統合コードに取り組むときによく起こる。
python -m json.toolをよく使う。こうしたツールがそれよりうまく見せてくれるなら、十分価値がある。
結局 JSON の利点は 人間にも機械にも読めること にあるので、デバッグ用途では依然として意味がある。
このアイデアは本当に気に入った。
現在採用が遅い理由は、ほとんどの言語や パッケージマネージャー（homebrew など） のサポートが不足しているからだと思う。
.NET ライブラリを C 互換の共有ライブラリとしてコンパイルすれば、さまざまな言語から簡単に使えるはず。
興味深いアプローチ。
コードフォーマッタもこういうふうに動いてくれるといい。
今のフォーマッタはあまりに 硬直的で構造を把握しにくい。
コメントは右揃えにしてきれいに配置される。
この構造のおかげで、switch-case ブロックやマクロテーブルも簡単に 2D 整列できる。
基本レイヤーは 1 時間で書けて、LSP とコード観察を組み合わせてブロックを自動検出する設計を進めている。
理想を言えば XML を捨てるべきだったが、レガシーの制約 のせいでそうもいかなかった。