スキーマのバージョン管理と検証

JSON Schema にはドラフトバージョンがあります。ドラフトは、どのキーワードが存在し、バリデーターがどう解釈すべきかを定義します。モダンスキーマは Draft 2020-12 をよく使いますが、古いエコシステムは Draft 7 をまだ期待している場合があります。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

$schema フィールドは、ツールにどの方言を使うかを伝えます。バリデーター、エディター、API ツールがサポートするドラフトを選んでください。

検証エラーは契約の一部

有用なスキーマは、問題を指し示すエラーで失敗します。

• 必須プロパティの欠落
• 型の不一致
• 最小値未満の値
• 形式に一致しない文字列
• ポリシーにより拒否された余分なプロパティ

スキーマをレビューするとき、有効な例と無効な例の両方をテストしてください。無効な fixture は、バリデーターが重要なミスを捕捉することを証明するため、しばしばより価値があります。

互換性規則

スキーマの変更はクライアントを壊す可能性があります。スキーマの進化を API の進化と同様に扱ってください。

• オプションプロパティの追加は通常安全。
• 必須プロパティの追加は既存のプロデューサーを壊す可能性がある。
• 列挙の狭め化は保存データとクライアントを壊す可能性がある。
• 型の変更は通常破壊的変更。
• フィールドの削除はコンシューマーを壊す可能性がある。

実践でのドラフト選択

Draft 2020-12 は新しいローカルワークフローの妥当なデフォルトです。古いツールが要求する場合、Draft 7 は依然有用です。最良のドラフトは、本番バリデーターが実際にサポートする最新のものです。

スキーマは生きた契約です。例、テスト、リリースノートの近くに置き、データ契約がシステムから乖離するのではなく、システムとともに進化するようにしてください。