JSON5

はじめに

JSON5は、人間が読み書きしやすいように設計されたJSONの拡張フォーマットです。2012年に開発が開始され、2022年時点で週間6500万ダウンロードを超える人気を誇り、Chromium、Next.js、Babel、Retoolなどの主要プロジェクトで採用されています。

JSON5の特徴

JSON5は、ECMAScript 5.1の構文要素を取り入れたJSONのスーパーセットです。すべての有効なJSONファイルは有効なJSON5ファイルとなります。以下に主な特徴を示します。

オブジェクトの拡張

ECMAScript 5.1のIdentifierNameをキーとして使用できるようになり、より直感的な記述が可能です：

{
  unquoted: "値が使えます",
  with-dash: "ダッシュも可能",
  trailing-comma: "最後のカンマもOK",
}

文字列の柔軟性

シングルクォートとマルチライン文字列をサポートしています：

{
  singleQuotes: 'シングルクォートが使えます',
  multiline: 'この文字列は\
             複数行に\
             わたります',
  quotes: 'シングルクォート内では"ダブルクォート"が使えます'
}

数値表現の拡張

16進数や特殊な数値表現をサポートしています：

{
  hex: 0xdecafe,
  infinity: Infinity,
  negativeInfinity: -Infinity,
  leadingPoint: .123,
  trailingPoint: 123.,
  positiveSign: +1,
  notANumber: NaN
}

コメントのサポート

設定ファイルの可読性を高めるコメントを記述できます：

{
  // 一行コメント
  key: "value",
  
  /* 複数行
     コメント */
  another: "value"
}

実践的な使用例

設定ファイル

JSON5は設定ファイルとして特に有用です：

{
  // サーバー設定
  server: {
    port: 8080,
    host: 'localhost',
    timeout: 30000,
  },

  // データベース設定
  database: {
    host: 'db.example.com',
    user: 'admin',
    /* パスワードは環境変数から
       読み込むことを推奨 */
    password: process.env.DB_PASSWORD,
    maxConnections: 100,
  },

  // ロギング設定
  logging: {
    level: 'info',
    file: '/var/log/app.log',
    rotate: {
      size: '10M',
      keep: 5,
    },
  },
}

プログラムでの使用

Node.jsでの使用

Node.jsでJSON5を使用する方法を示します：

const JSON5 = require('json5');

// パース
const data = JSON5.parse(`{
  // コメント
  key: 'value',
  number: 0xdecaf,
}`);

// 文字列化
const str = JSON5.stringify(data, null, 2);

ブラウザでの使用

ブラウザ環境でのJSON5の使用方法です：

<script src="https://unpkg.com/json5@2/dist/index.min.js"></script>
<script>
  const config = JSON5.parse(`{
    theme: 'dark',
    fontSize: 14,
  }`);
</script>

API リファレンス

JSON5.parse()

JSON5文字列をパースしてJavaScriptオブジェクトを生成します：

const result = JSON5.parse(text[, reviver])

パラメータ：

text: パースするJSON5文字列
reviver: （オプション）パース結果を変換するための関数

JSON5.stringify()

JavaScriptオブジェクトをJSON5文字列に変換します：

const text = JSON5.stringify(value[, replacer[, space]])

パラメータ：

value: 変換する値
replacer: （オプション）変換プロセスを制御する関数または配列
space: （オプション）出力を整形するための空白文字

ベストプラクティス

設定ファイルでの使用

設定ファイルを作成する際の推奨プラクティス：

{
  // 環境固有の設定
  development: {
    debug: true,
    apiUrl: 'http://localhost:3000',
    // 開発環境特有の設定をグループ化
    devTools: {
      enabled: true,
      port: 8080,
    },
  },

  // 共通設定
  common: {
    // 定数は大文字で記述
    MAX_RETRY: 3,
    TIMEOUT: 5000,
    
    // 関連する設定をグループ化
    auth: {
      tokenExpiry: '24h',
      refreshToken: true,
    },
  },
}

エラー処理

JSON5使用時の適切なエラー処理：

try {
  const config = JSON5.parse(configString);
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error('設定ファイルの構文エラー:', error.message);
  } else {
    console.error('予期せぬエラー:', error);
  }
}

トラブルシューティング

よくある問題と解決策

構文エラー

問題：

{
  key: 'value'   // 最後のカンマが必要な場合がある
}

解決策：

{
  key: 'value',  // トレイリングカンマを追加
}

文字列のエスケープ

問題：

{
  path: 'C:\path\to\file'  // バックスラッシュがエスケープされていない
}

解決策：

{
  path: 'C:\\path\\to\\file'  // バックスラッシュをエスケープ
}

附録

JSON5とJSONの比較

機能	JSON	JSON5
コメント	非サポート	サポート（一行・複数行）
クォート	ダブルクォートのみ	シングル・ダブルクォート
キー	クォート必須	識別子形式可
末尾カンマ	非サポート	サポート
16進数	非サポート	サポート