複数の問いを投げかけている可能性のあるスキーマプロパティを見つけ、競合する解釈を並べて確認し、データを収集する前に各プロパティの意味を1つに固定します。
Entity Enricher は LLM を問い合わせ可能な知識ベースとして扱い、プロパティ名はそこで投げかける問いそのものです。名前が複数の解釈を許す場合、各モデルは黙ってそのうち1つを選びます。たとえば企業の size は、あるモデルからは従業員数、別のモデルからは収益額、さらに別のモデルからは床面積として返ってきます。モデルは事実について食い違ったわけではありません。異なる問いに答えたのです。その結果、列には下流の利用者が見分けられない回答の寄せ集めが入ることになります。
意味を確定させることで、エンリッチメントはモデル間で比較可能になり、時間が経っても安定します。後続の処理もすべて整理されます。マルチモデルフュージョンは、実際には2つの問いにすぎない衝突を検出しなくなり、ベンチマーク比較は、参照とは異なるスキーマ解釈をしたモデルを不当に減点しなくなります。
単に時間とともに変化する事実は、曖昧性ではありません。スキーマは長期にわたる契約であるため、単純に ceo と名付けられたプロパティは「エンリッチメント実行時点のCEO」を意味し、来年同じスキーマを再実行すれば新しいCEOが返るはずです。このチェックが名前に日付を固定するよう提案することはありません。そうすれば今後のすべての実行が壊れてしまうからです。
このチェック全体は、すべてのプロパティに対して問う1つの問いです。親オブジェクトの文脈でその名前を読んだとき、いくつの異なる対象を求めうるか。その数が判定になります。
| 解釈 | 判定 | 意味するもの |
|---|---|---|
| ちょうど1つ | クリア | すべてのモデルが同じものを調べます。チップは表示されず、修正も不要です。 |
| 2つ以上 | あいまい | 各モデルはそれぞれ独自の解釈に落ち着くため、列の中に異なる問いへの回答が気づかないうちに混在します。このチェックは競合する解釈を列挙し、そのうち1つだけを残す表現を提案します。 |
| なし | マッピング不可 | その名前は親オブジェクトが持つ何も指していないため、モデルは値を参照できず、値を作り出してしまいます。列挙されている解釈はアナライザーが検討したうえで却下したものであり、対処法は名前の変更か削除です。エンティティが持っていないプロパティを、説明文で与えることはできません。 |
ちょうど1つのものを指すプロパティであっても、値の枠組みが定まっていなければ指摘されることがあります。読み手は何が問われているかは分かっても、どのような形で返ってくるかが分からないためです。よくあるパターンは次のとおりです。
| サブケース | 例 | 未解決の論点 |
|---|---|---|
| 指示対象が不明確 | Companysize | その名前は、親が実際に持つ複数の異なる事実（従業員数、収益、床面積）を指しています。名前だけではどれを指すのか決まりません。 |
| 測定対象または単位が不明確 | Companyannual_revenue | 事実は1つですが、通貨も期間も総額／純額の区分も示されていません。もっともらしい回答が3桁ずれていても「正しい」ことになり得ます。 |
| 尺度または方向が不明確 | Supplierrisk_score | 範囲も方向性も明示されていません。0〜10なのか0〜100なのか、そして数値が高いほど安全なのか危険なのか。2つのモデルが正反対の解釈をすることもあります。 |
| 範囲や境界が不明確 | Companyemployees | どの部分集合か、どの集計レベルか、誰の視点か — グループ全体かこの拠点か、人数か常勤換算か、業務委託を含めるか除くか。 |
| マッピング不可 | Authorrelease_year | 著者に発売年はありません。発売年を持つのはその著書です。モデルはこれを調べられないため、内容を捏造します。親エンティティが持つ属性へ名前を変更するか、その属性を持つオブジェクトへ移してください。 |
文章形式のプロパティ（description、summary、notes、bio）が指摘されることはありません。表現がモデルごとに異なるのは当然ですが、問われている内容は明確であり、このチェックが判定するのはその点だけです。曖昧性とは問いに関するものであり、回答同士がどれだけ似ているかは関係ありません。
判定だけ（「これは不明確です」）では、アナライザーが何を想定していたかを推測するしかありません。そのため、すべての指摘には interpretations（解釈）が付随します。これは、そのプロパティが許容する2〜4個の短く明確に異なる解釈で、可能性の高いものから順に並びます。このリストこそが指摘の本体です。アナライザーが2つの解釈を挙げられない場合、その指摘はノイズとして破棄され、表示されません。
annual_revenue Company 上それらと併せて、解釈を1つだけに絞る 説明の候補 が提示されます。ここでは「直近の完了した会計年度におけるグループ全体の収益（米ドル建て、返品控除前）」です。適用にコストはかかりません。説明は名前とまったく同様にエンリッチメントを行うモデルへ渡りますが、プロパティ名はそのまま維持されるため、データ契約は一切変わりません。名前そのものが誤解を招いている場合は、指摘に 名前の候補 も含まれます。
解釈が書き出されているのを見れば、どんな説明よりも早くそのプロパティの意味が定まります。意図していた解釈がすぐに分かり、残りは知らないうちに受け取っていた内容だからです。
サンプルが生成されると、アナライザーはそのプロパティ名を検査し、曖昧性レポートを返します。曖昧さのない名前変更は、AIが考案したキーに対して自動的に適用されるため（ご自身で名付けたフィールドには決して適用されません）、確認するサンプルは最初から読みやすくなっています。また、過度に特殊化されたプロパティ（例示インスタンスから紛れ込み、サブタイプにしか当てはまらない特徴。汎用的な Person に付いたアスリートのメダルなど）も指摘し、より狭いエンティティタイプを提案します。同一性スコープのチェックは、その直後に独立した呼び出しとして実行され、サンプルを確認する前に関連項目の形を確定します。添付ファイルに基づくサンプルはスキップされます。その値はモデルの記憶ではなく、ソース文書から得られているためです。
生成されたスキーマが保存されると、後処理パスがすべてのプロパティに曖昧性の判定を注釈として付け、未解決のものには名前の変更を提案します。リレーションシップ箇所はその時点ですでに注釈済みです（生成処理が自らのステップの1つとしてスコープを判定するため）。そのため後処理パスが対象とするのはプロパティ名だけです。このステップはベストエフォートで、失敗しても生成自体には影響しません。
「再チェック」ボタンは、プロパティ名とリレーションシップ箇所という2つのチェックを、並行した2回の呼び出しとして実行します。名前の変更ではなく説明文の書き直しを提案するのは、ここだけです。まだ注釈のない部分だけを解析し、すべてに注釈が付いた時点で全体の再解析に切り替わります。
スキーマ作成のために貼り付けたサンプル JSON は、ステートレスに解析できます。何も変更されることなく、曖昧またはマッピングできないプロパティ名と、エンティティの事実とペアリングの事実が混在している関連要素についてのレポートが得られます。
同じ指摘でも、ある場所では名前の変更を、別の場所では説明文を提案します。その理由は知っておく価値があります。生成時点では説明文はまだ独立して存在せず、名前から書き起こされるため、曖昧性を繰り返すことしかできません。修正できるのは名前だけであり、まだ何もそれに依存していません。だからこそ、サンプル生成とスキーマ生成の後処理パスはどちらも名前の変更を提案します。
スキーマが稼働した後にプロパティ名を変更すると、列が移動し、クエリが壊れ、同期済みテーブルのキーが振り直されます。一方、説明文を明確にすれば、同じように直接モデルへ伝わり、他には何も影響しません。つまりルールはシンプルです。スキーマに依存するものが何もないうちは名前を変更し、稼働後は説明文で意味を確定させる — そして名前そのものが問題である場合に備えて、名前の変更は切り札として取っておきます。
このチェックは参考情報にすぎません。保存済みスキーマがバックグラウンドで解析されることはありません。実行されるのは生成時と、「再チェック」を押したときだけです。生成をブロックすることも、エンリッチメントを拒否することもなく、その注釈はエンリッチメントを行うモデルへ送られるすべてのプロンプトから除去されます。伝える相手は AI ではなく、あなたです。
指摘されたプロパティには、ワークフローエディター上に 「ambiguous」チップ が表示されます。解釈がおおむね重なり、境界的なケースだけが異なる場合は琥珀色、競合する解釈が実質的に異なるデータをもたらす場合は赤色です。明確と判定されたプロパティにチップは付きません。チップにカーソルを合わせると、アナライザーの注記、見つかった競合する解釈、そして説明または名前の候補が表示されるため、判断と修正を同じツールチップ内で確認できます。
判定はプロパティの名前と説明を合わせて下されるため、プロパティ名を変更したり説明を編集したりすると、その注釈は破棄されます。エディターはそうしたプロパティを古い状態として強調表示し、再チェックを提案します。再チェックでは不足している部分だけが分析されます。これは、提案された修正を適用した後にまさに必要な操作です。新しい表現が本当に単一の解釈に絞り込めているかを、再チェックが確認します。
アイデンティティのスコープ設定は2つ目のチェックで、曖昧性チェックと並行して独立したモデル呼び出しとして実行され、結果はまとめて報告されます。関連配列の各項目やネストされたオブジェクトなど、すべてのリレーション箇所を検査します。関連エンティティ自身に関する情報(名前や国など)と、組み合わせに関する情報(この親に対して持つ役割、親ごとの呼称など)が1つの項目に混在していると、両者が同一のアイデンティティを共有することになり、再エンリッチメント時に組み合わせ側の情報が親をまたいで上書きされてしまいます。そうした箇所には琥珀色の「情報の混在」チップが付き、ツールチップに推奨される構造(エンティティ自身のフィールドはサブオブジェクトにネストし、組み合わせのフィールドは項目側に残す)が表示されます。項目にすでにそうしたサブオブジェクトがある場合、修正はより小さく済み、置き場所を誤ったフィールドを既存のサブオブジェクトへ移すだけです。
分割はサンプル生成の際、サンプルを承認いただく前に適用されます。構造は最初のサンプルで確定し、再構成された箇所はすべて生成時の警告に一覧表示され、バッチ内の他のサンプルは確定した構造に沿って生成されます。そのため、新しいサンプルから生成したスキーマは通常クリーンな状態になります。添付ファイルに基づくサンプルは元の文書が示す構造のまま残され、代わりにチップが付きます。
スキーマ生成自体が、承認済みのサンプルを再構成することはありません。同じ箇所を判定し、検出内容を報告するだけです。そのため既存のスキーマや手書きのスキーマでは、修正はチップから行います。チップはワンクリックの分割を提供し、サンプルを再構成してそこからスキーマを再生成します。構造は契約であるため、新しいサンプルからの再生成によって変更され、その場でパッチが当てられることはありません。分割しないことを選んだ箇所もそのまま動作します。1 つのアイデンティティを共有したままとなり、チップが残るだけです。アイテムのフィールド構成が変わると、チップは自動的に消えます。
このチェックは、Workflow Editor のオーバーフローメニューからスキーマごとに無効にできます。無効にすると、生成後のパスはスキップされ、チップ、「再チェック」ボタン、古い注釈の警告は非表示になり、解析エンドポイントは ambiguity_check_disabled エラーを返します。既存の注釈は保持され（非表示になるだけ）、一度も解析されていないスキーマでチェックを再び有効にすると、自動的に実行されます。
生成されるスキーマはすべて、チェックが有効の状態で始まります。添付ドキュメントから生成されたスキーマも同様です。曖昧性はスキーマの文言の書き方に関する性質であり、ある実行の値がどこから来たかとは関係ありません。ドキュメントはその値を一度確定させるだけで、スキーマはその後も、ドキュメントが扱っていないエンティティに対して繰り返し再利用されます。ドキュメントが実際に変えるのはサンプルの段階です。サンプルのプロパティ名は元のドキュメント自身の語彙に由来するため、コード上でリネームされることはなく、代わりにそこから構築されたスキーマがチェックを引き継ぎます。
「会社の年間収益」という説明は、名前がすでに示している以上の情報を何も加えないため、アナライザーはそのような説明を存在しないものとして扱い、名前だけで判断します。説明は、単位・期間・規模・範囲を明示してこそ意味を持ちます。
アナライザーの注記と解釈は、インターフェースの言語で記述されます。フランス語のユーザーにはフランス語の解釈が、日本語のユーザーには日本語の解釈が表示されます。提案されるプロパティ名は、スキーマの命名規則に合わせて英語のままです。
各分析は実際の（低コストな）モデル呼び出しです。スコープを定める関連箇所もある場合は、2件が並列で実行されます。それぞれはレコード上に独立したプロンプトとして ambiguity_analysis タイプで記録され、他の AI 利用と同様にクレジットから差し引かれます。増分的な再チェックでは、実際に分析されたプロパティと箇所の分だけが課金されます。
サンプル生成とスキーマ生成には、プロパティごとに1つの対象だけを指す名前を付け、単位・尺度・境界を明記した説明文を書くよう指示されています。また、判断の分かれるリストについては、件数を無理に名前へ含めるのではなく、説明文で上限を示すよう指示されています。そのためほとんどのスキーマは問題なく生成され、アナライザーは取りこぼしを拾うだけで済みます。
このチェックはプログラムからも利用できます。
| 検出 | 説明 |
|---|---|
POST /api/schema/analyze-sample | 貼り付けたサンプル JSON を解析します — 1 リクエストで両方のチェックを並列実行、ステートレスなレポート、変更は一切行いません |
POST /api/schema/saved/{id}/analyze | 保存済みスキーマを解析し、両方のチェックの注釈を書き込みます — 既定は増分実行、force=true ではすべてを再解析します |
POST /api/schema/scoping-split | サンプルセットに「混在した事実」の分割を 1 件適用します — 決定的、無料、保存なし。返されたサンプルをスキーマ生成に再投入してください |
analyze_sample | MCP ツール — Claude や任意の MCP クライアントから、両方のチェックを含む同じステートレスなサンプルレポートを取得します |
analyze_schema | MCP ツール — 保存済みスキーマに注釈を付けます。update_schema と組み合わせると、提案された説明文や名前の変更を適用できます |
指摘は、kind（ambiguous または unmappable）、level、注記、interpretations のリスト、そして修正案とともに返されます。保存済みのスキーマでは各プロパティ上に ambiguity として保存され、サンプル生成では ambiguity_report の下に返されます。
認証と全ツールカタログについては、APIリファレンスとMCP Serverガイドをご覧ください。