コンテンツにスキップ

known_gaps 仕様 — 「収録範囲内で不在」を機械可読にする field

jpcite の全応答に共通する 8 field (source_url / source_published_at / fetched_at / excerpt / record_id / name_match_key / match_confidence / known_gaps) のうち、最も重要なのが known_gaps です。本ページがその正式仕様です。

定義

known_gaps は、「この応答が確認していない範囲」を明示する配列です。no-hit を「問題なし」ではなく「指定ソースの収録範囲内で検出なし」として返すために使います。

  • known_gaps が空でない応答は、「確認できた範囲」と「確認できていない範囲」の境界を宣言しています。
  • no-hit は不在証明ではありません。 収録範囲・収録時点の外側 (未収録ソース、直近の公表、非公的文脈) は known_gaps に列挙されます。

型

{
  "known_gaps": [
    {
      "gap_type": "source_not_covered | period_not_covered | field_unavailable | identity_unresolved",
      "description": "string (人間可読の 1 行)",
      "scope": "string (どのソース / どの期間 / どの field か)"
    }
  ]
}

一部の endpoint は簡略形 (known_gaps: ["string", ...]) を返します。いずれの形でも「空配列 = 既知の欠落なし (収録範囲内)」であり、「空配列 = 世の中に存在しない」ではありません。

3 つの結果型と読み方

型 known_gaps の例 AI agent の正しい扱い
HIT (該当あり) ["財務・登記実体・連絡先は非保有"] 該当 record の receipt (source_url + fetched_at + excerpt) を引用しつつ、gaps に挙がった範囲は別途確認と明示
NO_HIT (検出なし) ["処分の不在は不存在証明ではない", "収録: 会計検査院/中企庁 2026-04 時点"] 「指定ソースの収録範囲内で検出なし」とそのまま提示。「問題なし」「クリーン」と言い換えない
AMBIGUOUS (同定不能) ["同名複数法人 — 法人番号で弁別必須"] match_confidence と name_match_key を提示し、法人番号の提供をユーザーに求める

なぜこの field が必要か (空配列との違い)

一般的な公的情報 API は、該当なしの時に空配列を返します。空配列は「不在」と「未収録」を区別できないため、AI がそのまま「問題ありません」と回答すると誤りになり得ます。known_gaps は確認済み範囲を機械可読で固定するため、AI の回答側で「どこまで確認し、どこからは未確認か」を引用できます。

AI agent 側の義務 (推奨実装)

  1. known_gaps が空でない場合、最終回答にその内容を必ず反映する (省略しない)。
  2. NO_HIT を肯定的断定 (「処分はありません」) に変換しない。「収録範囲内で検出なし」を保つ。
  3. match_confidence が低い場合は同定根拠 (name_match_key) を提示して追加情報を求める。

関連