開発者ツール · JSON フォーマッタおよびバリデータ
JSON にコメントがない理由: 設計上の決定とその回避策
· 背景
json 規格 検証
コメントは JSON から意図的に削除されました。この投稿では、その理由、追加し直そうとするたびに新しい形式が作成される理由、構成ファイルに本当にメモが必要な場合のオプションについて説明します。
ビルドを中断したコメント
ビルドを中断したコメント — JSON 構成に追加された役立つメモと、最初のスラッシュで停止したパーサー。デプロイメント ツールは厳密な JSON を使用しますが、作成者は JavaScript または JSONC 対応エディターからパターンをコピーした可能性があります。構文の強調表示により、消費者が最初のコメント マーカーを拒否した場合でも、メモが正当であるかのように見せることができます。
スラッシュは、スキャナーが値またはメンバーを予期する JSON トークンではないため、コメントは拒否されます。 ToolAcre は、JSONC または JSON5 構文を暗黙的に削除しません。従来のコメント形式のプロパティは通常のデータであり、厳密な JSON 構文で受け入れられる場合でも、アプリケーション スキーマに違反する可能性があります。 JSON の設計に関する裏付けのない歴史的主張は、一次証拠や検証に利用できる追跡可能な標準ソースなしに確立された事実として提示されるのではなく、省略または修正されます。
Crockford 氏がコメントを削除した理由
Crockford がコメントを削除した理由 — 後の説明では、コメントは解析ディレクティブを運ぶために使用され、実装間の相互運用性を損なっていたと述べています。関連する設計上の結果として、標準の JSON にはコメント トークンがありません。個人的な動機、正確な年表、または業界全体の対応に関する主張には、このリポジトリが提供していない歴史的ソースが必要です。
したがって、サポートされていない過去の主張はここでは省略または修正されます。監視可能な標準とパーサーの動作は十分です。厳密な JSON は、アノテーション チャネルを使用せずに、6 つの値の型と 2 つのコンテナーを通じてデータを交換します。この制約により、ある受信者が別の受信者が無視するテキストに操作上の意味を割り当てることができなくなりますが、JSON を手作業で管理する構成の快適性も低下します。
バリデーターがコメントに関して報告する内容
バリデーターがコメントについて報告する内容 — `//` と `/* */` は文法にないため、エラーは行と列を含む最初のスラッシュで発生します。スキャナーはメモの言葉に異議を唱えていません。その位置で、有効な JSON 値、メンバー名、または区切り文字を `/` で始めることはできません。
`{"port":8080, // local only "secure":false}` の場合、コンマは有効であり、次の有効なトークンは引用符で囲まれたプロパティ名または右中括弧である必要があります。スラッシュはその期待に反します。メモのみを削除すると、有効な区切り文字と次のメンバーが残ります。近くの句読点を削除すると、2 番目のエラーが発生する可能性があります。編集するたびに、正確な厳密な出力を再検証します。
コメントを追加した形式
コメントを追加した形式 — JSONC では、おなじみの JSON 構文の周囲にコメントを許可しますが、JSON5 では、引用符で囲まれていない識別子キーや末尾のカンマなどの便利な機能が追加されています。 Hjson は、追加の緩和された構文を使用して人間による編集を重視しています。 YAML には、コメントを含む独自の文法があり、単に注釈が追加された JSON ではありません。
受け入れはコンシューマによって異なります。エディタ設定と TypeScript 構成ではコメント許容パーサーが使用される場合がありますが、パッケージ マニフェストまたは API 本体では厳密な JSON が必要になる場合があります。 Kubernetes は通常、そのツールに応じて YAML または JSON を使用します。ドキュメントやファイル処理における実際の形式に名前を付けます。拡張機能を削除したり、すべてのオブジェクト表記「JSON」を呼び出したりすると、互換性の境界が隠蔽されます。
厳密な JSON 内の回避策
厳密な JSON 内の回避策 — 従来の `_comment` または `//` キーは、説明を通常の文字列メンバーとして保存します。キーと値の両方が標準トークンを使用するため、厳密な解析に耐えられます。重複したメンバー名は信頼性が低く、パーサーによって折りたたまれる可能性があるため、複数のノートには一意のキーまたは配列が必要です。
回避策では、データ モデルが変更されます。 `additionalProperties: false` を持つスキーマはアノテーションを拒否でき、アプリケーションはそれを実際の構成として永続化または送信できます。多くの場合、外部ドキュメント、隣接する README、またはスキーマ `description` が、より安全な説明チャネルを提供します。コメント形式のメンバーは、すべてのコンシューマーが明示的に許可し、無視する場合にのみ使用してください。
作業例: 注釈付き設定ファイル
実用的な例: 注釈付き設定ファイル — `"timeout":30` の上に `// seconds before retry` を含む JSONC ソースから始めます。宛先が JSON のみを受け入れる場合は、JSONC を理解するパーサーを使用してデータを生成し、そのデータを厳密な JSON としてシリアル化します。デプロイされたアーティファクトは `{"timeout":30}` になりますが、維持されるソースにはその説明が保持されます。
正規表現を使用してコメントを削除しないでください。スラッシュ シーケンスは URL などの文字列内に正当に出現する可能性があり、ブロック コメント パターンはテキストの置換が誤って処理される方法で複数の行にまたがる場合があります。ソースと生成されたアーティファクトを区別し、厳密な結果を検証して、ビルドでの再生成を調整します。これにより、受信パーサーが作成者のメモをサポートしているかのように装うことなく、作成者のメモが保存されます。
これでカバーされない内容
ここで説明しないこと — コメントを受け入れるように個々のパーサーを構成する方法。これはツール固有であり、頻繁に変更されます。あるライブラリの許可オプションは、JSON 文法を変更したり、別のサービスが同じテキストを受け入れることを保証したりするものではありません。エディターの表示に頼るのではなく、パーサー、バージョン、宛先を確認してください。
この記事では、コメントがいつ削除されたのか、各回避策を誰が最初に採用したのか、または JSON の人気の原因が 1 つの設計上の決定のみであるかどうかについて、サポートされていない主張も避けています。このような歴史的主張には独立した一次資料が必要です。ここでは省略または修正されています。サポートされている結論は、現在の厳密な構文、リポジトリの動作、および名前付き形式間の操作上の違いに限定されています。
要点: JSON はデータ交換形式であり、構成言語ではありません
要点: JSON はデータ交換形式であり、コメントが豊富な構成言語ではありません。また、バリデーターは、メモが厳密な文法を破っている場所を正確に示します。人間が注釈を必要とする場合は、使用ツールが公式にサポートする形式を選択するか、別の厳密なアーティファクトを生成する注釈付きソースを維持します。コメントが無害に無視されるとは考えないでください。
厳密な JSON が必須の場合は、説明をドキュメントに移すか、スキーマで承認されたメタデータを使用してから、最終ドキュメントを検証します。 ToolAcre は、サイレント変換によって文字列が変更されたり、形式の不一致が隠蔽されたりする可能性があるため、マテリアルをサイレントに削除するのではなく、意図的に最初のスラッシュを報告します。歴史的文脈は同様に規律を保つべきであり、サポートされていない主張は省略または修正されますが、観察可能な構文とパーサーの動作は結論を伝えます。