開発者ツール · JSON フォーマッタおよびバリデータ
有効 JSON とスキーマに対して有効: 「有効」の 2 つの意味
· 背景
json 規格 検証
JSON が有効であるというバリデーターは、解析することだけを意味します。この投稿では、有効性のレベル (構文、構造、セマンティクス) と、文法を超えたすべてのものに対して JSON スキーマが存在する理由について説明します。
有効ですが拒否されました
リクエストは完璧な JSON であっても、API では受け入れられない場合があります。 `{"username":"nori","plan":"gold"}` には、バランスの取れた区切り文字、引用符で囲まれた名前、および正当な値が含まれていますが、現在の状態では、サービスで電子メールが必要になったり、プラン名が拒否されたり、アカウントの作成が禁止されたりする場合があります。パーサーとアプリケーションは異なる質問に答えているため、どちらの結果も正しい可能性があります。
ToolAcre は、最初の質問のみに答えます。このテキストは入力制限内で厳密な JSON として解析できますか?スキーマのロード、必要なプロパティのチェック、形式の検証、データベースへの接続、ビジネス ルールの評価は行いません。ツールに「有効」と表示されている場合は、値を使用するシステムからの承認としてではなく、「整形式の JSON 構文」として解釈してください。
レベル 1: 整形式の構文
構文検証では、JSON 文法 (1 つのトップレベルの値、正しくペアになったコンテナ、引用符で囲まれたオブジェクト名、有効なカンマとコロン、有効な文字列、有効な数値、および正確なリテラル) がチェックされます。 `NaN` および `Infinity`、コメント、末尾のカンマ、および一重引用符で囲まれた文字列は拒否されます。単独の数字や見慣れないフィールドを持つオブジェクトなど、文法的に有効なあらゆる形状を受け入れます。
不正なソースにはテキストの障害点があるため、ToolAcre は最初の不可能な文字の行と列をレポートできます。カンマが欠落していると、次の引用符が報告される可能性があります。末尾のカンマにより、終了区切り文字が報告される場合があります。構文を修正すると、解析可能な値が作成されますが、その値が別のプログラムで期待される形状や意味を持つことは確立されません。
レベル 2: 形状
形状検証では、解析された値が宣言されたコントラクトと一致するかどうかが尋ねられます。ユーザー スキーマでは、`email` を要求し、`age` を少なくとも 18 の整数に制限し、`tier` を `free` または `pro` に制限し、不明なプロパティを禁止する場合があります。 `{"email":false,"tier":"gold"}` は有効な JSON 構文ですが、値の型と許可される選択肢が間違っているため、これらの構造規則に違反します。
JSON スキーマはそのような制約を表現する方法の 1 つですが、ToolAcre はそれを実行しません。スキーマ検証ツールは通常、パーサー キャレットではなく、`/tier` などのインスタンス パス、`enum` などのキーワード、および説明メッセージを報告します。このレベルを診断するときは、スキーマ バージョンと API コントラクトをペイロードの横に保持してください。句読点を変更しても、正しく解析された間違った形状の値は修復されません。
レベル 3: 意味
意味は、文書の静的な形状を超えた事実と規則に依存します。 `accountId` は、アカウントに名前を付けていなくても、正しい文字列パターンを持つことができます。開始日は、終了日以降であっても ISO スタイルの形式と一致できます。数量はプラスであっても、現在の在庫を超える場合があります。これらの障害には、アプリケーション コンテキスト、保存された状態、またはフィールド間の関係が必要です。
一部のセマンティック制約はスキーマ内で近似できますが、多くは信頼できるデータとトランザクション状態が利用可能なサービス ロジックに属します。このレベルのエラー応答は、JSON テキストが不正であるかのように装うことなく、関連するフィールドまたはルールを識別する必要があります。 ToolAcre はコントラクトを認識しておらず、ビジネス ルールを所有するアプリケーションに入力を送信しないため、これらの決定を再現できません。
作業例: 3 つのチェックによる 1 つのペイロード
`{"sku":"A-19","quantity":3,"warehouse":"north"}` から始めます。 ToolAcre はそれを受け入れます。すべての名前と値は JSON 文法に従います。スキーマでは、オブジェクト、空ではない文字列 SKU、正の整数の数量、および文書化されたウェアハウス コードの 1 つが必要になります。このペイロードがこれらの制約も通過するとします。どちらのチェックでも、SKU A-19 が存在すること、または北に 3 つのユニットがあることは確認されていません。
インベントリ サービスは、現在のレコードに対して 3 回目のチェックを実行し、要求を使用不可として拒否する場合があります。インデントを変更しても結果を変えることはできません。 `quantity` が `03` として記述された場合、構文は最初に失敗します。 `"3"` の場合、解析は成功しますが、スキーマ タイプのチェックは失敗します。数値 `3` を使用すると、ライブストック ルールのみが残ります。したがって、同じフィールドが 3 つの異なる層で 3 つの異なる理由で失敗する可能性があります。
各チェックが属する場所
解析されないテキストに対しては後のチェックを確実に行うことができないため、編集中はできるだけ早く構文検証を実行してください。クライアントがすでにそうしていると想定するのではなく、信頼できないアプリケーションの各境界で宣言された形状を強制します。特に要求間で応答が変わる可能性がある場合、必要な状態を所有するコンポーネント内のビジネス不変条件を評価します。
クライアント側のチェックはフィードバックを改善しますが、サーバー側の強制に代わるものではありません。逆に、「無効な JSON」というサーバー応答は、拒否されたリクエストごとに使用するのではなく、解析失敗のために予約しておく必要があります。明確な分離により、構文については行と列、構造上の制約についてはインスタンス パス、セマンティックの競合についてはドメイン固有のコードまたはメッセージなど、有用な診断が生成されます。 ToolAcre は最初のカテゴリーのみを提供します。
これでカバーされない内容
このフォーマッタは、JSON スキーマの作成や評価、スキーマ ドラフトの選択、スキーマ参照の解決、デフォルトの挿入や数値への文字列の強制は行いません。また、API の OpenAPI ドキュメントやカスタム検証規則も認識しません。このツールにはスキーマ処理ステップがないため、入力とともにスキーマを指定しても、ToolAcre の結果は変わりません。
ここでは、構文検証でも重複したオブジェクト名は検出されません。 `JSON.parse` は、フォーマット前の最後の出現を保持します。また、数値の精度、正規のバイト数、安全なレンダリングや認証も保証しません。これらの懸念事項にはそれぞれ独自の契約と実装が必要です。単一の緑色の「有効な」バッジに圧縮することは避けてください。圧縮すると、どの証拠が収集され、どの質問が尋ねられなかったのかが隠されてしまうからです。
要点: 「有効」には修飾子が必要です
すべての検証クレームを認定します。 「有効な JSON」は、テキストが文法に従っていることを意味します。 「このスキーマに対して有効」とは、解析された値が名前付き構造契約を満たすことを意味します。 「サービスによって承認された」とは、現在のアプリケーション ルールが操作を許可していることを意味します。多くのワークフローでは、あるレイヤーを通過させることが次のレイヤーに必要ですが、それは後のすべてのレイヤーが通過したという証拠にはなりません。
ToolAcre を使用して、`NaN` や `Infinity` などの非 JSON リテラルの拒否など、厳密な構文の書式設定とチェックを行います。次に、実際にペイロードを管理するスキーマとアプリケーションを使用します。それでもリクエストが失敗する場合は、正しい JSON を繰り返し再フォーマットするのではなく、独自のレイヤーでエラーを読み取ります。このツールにはスキーマ チェックがありません。その明示的な境界は、有効性を広範に約束するよりも役立ちます。