プロダクト境界としてのスキーマ検証
· 7分で読める
スキーマを、プロダクト意図と実装ドリフトを分ける契約として扱いましょう—モデル、パートナー、サービスが圧力下でフィールドを発明するときに特に。
契約はコードに書かれたプロダクト決定である
スキーマは型チェッカー向けの書類ではありません。どのフィールドが存在し、どれが必須で、列挙が何を意味し、ペイロードが誤ったときに何が起きるかに関するプロダクトの公開約束です。その約束を暗黙のままにするチームは、クライアントがnullを送り、パートナーが同義フィールドを足し、モデルがほぼ正しいキーを発明したときに本番で発見します。
スタッフ級のオーナーシップは契約を境界に置きます：クライアントからの入口、パートナーへの出口、エージェントへのツール結果、ビジネスロジックに触れる前の構造化モデル出力。境界の内側では自由にリファクタできます。境界を越える変更は意図的で、版管理され、測定可能です。
一度検証し、fail-closedで、出所を保つ
エッジでパースし、無効入力が半処理状態になる前に拒否します。型を推測したり未知フィールドを落としたりして「助ける」強制変換は、顧客に見えるまでプロダクトバグを隠します。静かな修復より、安定したコード付きの明示的エラーを好みます。
AI機能が構造化JSONを出すとき、モデルを信頼できない生産者として扱います。システムの残りと同じスキーマで検証します。失敗したら再試行、確認、または決定的フォールバックへ—近似オブジェクトに基づく楽観的な業務書き込みへは決して。
- 実用的な範囲でAPI・ワーカー・クライアントが共有する正規スキーマパッケージ
- 未知フィールド方針を区別：書き込み経路は拒否、読み取りアダプタはログ
- 保存イベントと監査ログにスキーマ版を付与
- リリース後の検証失敗率スパイクにアラート
信頼を壊さず進化させる
追加のオプションフィールドは安く、改名・意味の狭小化は高いです。互換方針を公開します：何が加法か、何が新版を要するか、二重読みがどれだけ続くか。マルチテナントSaaSでは、テナント固有拡張は検証を破る自由なbagオブジェクトではなく、明確な名前空間の後ろに置きます。
スキーマテストはプロダクトと共に旅すべきです。ハッピーパスと敵対ケースのゴールデンペイロード—余分フィールド、誤った列挙、過大文字列、必須キー欠落—はCIに属します。変更がパートナー連携やAIツール契約を壊すなら、スイートは顧客より先に失敗すべきです。
境界を観測可能にする
検証結果をプロダクト健全性として追跡します：受入率、失敗上位パス、パース遅延、AI構造化出力が修復を要する頻度。モデルやクライアント更新後の失敗率上昇はログの好奇心ではなくリリース信号です。
目標は官僚制ではありません。「これが私たちのプロダクト言語」と「これは他人の即興」の間の鋭い線です。スキーマ検証は、システムが成長する間もエンジニアリングがその線を執行可能に保つ方法です。
2026年9月5日、Berktug Berke Ates が公開。