JSON ～ JSON スキーマ: サンプル ペイロードからコントラ

推論で見えるものと見えないもの

優れたコンバーターは、単一のドキュメントから型、ネスト、配列項目の形状、およびプロパティ名を正確に導き出します。導き出すことができないのは意図です。この特定のレコードにたまたまそのフィールドが含まれているためフィールドがオプションであること、文字列が電子メール アドレスであること、数値が正の整数であること、または値が固定セットからのものであることは認識されません。したがって、派生したものはすべて `required` とマークされます。これは契約草案の正しいデフォルトであり、未検査で出荷するのは間違っています。

生成されたスキーマの強化

1. 2 つまたは 3 つの実際のサンプルを比較します。サンプルに欠落しているキーは `required` からドロップされます。
2. 意味がわかっている場合は `format` を追加します（`date-time`、`email`、`uri`、`uuid`、`ipv4`）。
3. フィールドに実際にステータスや地域などの固定語彙がある場合、オープンセットを `enum` 値に変換します。
4. 数値を `minimum`、`maximum`、`multipleOf` で締めて、負の数量が検証できないようにします。
5. 不明なキーを拒否する必要がある場合にのみ `additionalProperties: false` を追加します。それ以外の場合は、前方互換性のためにスキーマをオープンのままにしておきます。

必要なのは観察ではなく約束です。 1 つのサンプルにフィールドが含まれているという理由でフィールドを必須としてマークすることは、推論されたスキーマによって実際の統合が中断される最も一般的な方法です。

スキーマが維持される場所

実際の価値は境界に現れます。Webhook ペイロードを信頼する前に検証すること、混乱を招く null エラーではなく不正なデータでテストが失敗するように CI 内のフィクスチャ ファイルをチェックすること、サーバー コードを決して読まない人のために API 応答を文書化すること、型指定されたクライアントを生成することです。 JSON スキーマは、バリデータが本番環境ではなくビルド時にそれをキャッチするため、構成変更によってパブリック応答がサイレントに変更されるのを阻止する最も安価な方法でもあります。

                {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "plan": { "type": "string", "enum": ["free", "pro", "team"] }
  }
}
              

バージョン管理に保管しておく

生成されたスキーマは、誰も所有しなくなった瞬間に漂流します。データを生成するコードの隣に強化されたファイルをコミットし、CI のバリデーターから参照し、コントラクトが本当に変更された場合にのみ再生成します。スキーマを形状の信頼できる情報源として扱い、サンプルを証拠として扱います。その逆ではありません。

ブラウザでの推論

実際のペイロードには識別子、電子メール、トークンがたくさん含まれているため、サンプルをアップロードする JSON から JSON へのスキーマ変換は、純粋に機械的な操作のための実稼働データを引き渡します。ローカルで推論すると、ペイロードがタブに保持され、何も考えずに顧客レコードを貼り付けることができ、ネットワークが切断されていても機能します。