從 consumer contract 開始
先定義下一個系統真正需要的最小 object。官方指南支援依特定 JSON Schema 功能約束輸出,也記錄較寬鬆的 JSON mode;下游程式依賴欄位時,應優先使用精確 schema。
用 description 說明語意,用 constraint 限制形狀。控制 schema 大小;過深、描述不足的 object 會讓評估與遷移都更困難。
同時驗證形狀與意義
Schema conformance 可保證 required key 與 type 符合支援的 constraint,卻無法證明日期真的存在、引用支持主張,或某項商業決策已獲授權。
先解析到 runtime validator,再套用 domain rule。語意無效時,透過有限路徑拒絕或修復;絕不默默轉換高影響值。
- Schema check:型別、必填 key、允許值。
- Domain check:範圍、referential integrity、authorization。
- Evidence check:引用來源確實支持欄位。
為邊界做版本管理
若輸出會保存或跨 service 傳遞,加入 schema version。新增欄位可能相容;欄位改名或語意改變則需要 migration。
建立 valid、boundary 與刻意不可能的 fixture。模型設定改變時,同時比較 conformance rate 與 semantic accuracy。