Microsoft Azure documentation updateとして確認すべき今回の変更は、Azure Data API builder（DAB）の実行動作を変えるものではなく、設定スキーマ上の誤解を招く entities.*.source.description を削除し、MCPで使われる説明文は主に entities.*.description に書くべきだと明確化する修正です。すでにDABでMCP連携、JSONスキーマ検証、CI/CDによる設定チェックを行っている管理者・開発者は、構成ファイル内に古い source.description が残っていないかを確認してください。PR #3612は、元PR #3552の変更を main から release/2.0 へ反映するCherry-pickで、GitHub上では2026年5月20日にマージされています。(GitHub)
Microsoft Azure documentation update #3612の変更点
今回の「Cherry-pick: fix: remove extraneous source.description schema property (#3552)」は、Azure/data-api-builderリポジトリの schemas/dab.draft.schema.json に対するスキーマ整理です。PR #3612では、release/2.0 ブランチに対して1ファイルの変更が入り、差分は1行追加・5行削除と小さいものです。(GitHub)
変更の中心は次の2点です。
| 変更箇所 | 変更内容 | 実務上の意味 |
|---|---|---|
entities.*.source.description | スキーマから削除 | source 配下に description を書いても、DABの実行時モデルには結び付かず、MCP出力に反映されない |
entities.*.description | 説明文に「MCP tool discovery」にも表示される旨を追加 | MCPクライアントやAIエージェントに見せたいエンティティ説明は、エンティティ直下の description に書く |
元コミットでは、entities.*.source.description はJSONスキーマには存在していたものの、C#側の EntitySource モデルに対応フィールドがなく、実行時には無視されていたと説明されています。そのため、これは機能追加やAPI挙動の変更ではなく、利用者が誤った設定項目に説明文を書いてしまう問題を防ぐためのスキーマ修正です。(GitHub)
影響を受けるのはData API builderのMCP・スキーマ検証まわり
Data API builderは、SQL Server、Azure SQL、Azure Cosmos DB、PostgreSQL、MySQLなどのデータソースに対して、REST APIやGraphQL APIを設定ファイルベースで生成するオープンソースのエンジンです。DAB 1.7以降ではModel Context Protocol（MCP）もサポートされており、AIエージェント向けのデータアクセス基盤として使われるケースが増えています。(Microsoft Learn)
今回の変更で注意すべきなのは、Azureポータルの設定やAzureリソースそのものではありません。主な確認対象は、DABの設定ファイル、JSONスキーマ検証、MCPのツール検出、エージェント向けの説明文です。
| 対象 | 影響度 | 確認すべきこと |
|---|---|---|
| DABの実行時動作 | 低 | PR上ではスキーマのみの変更で、ランタイム挙動の変更はないと説明されている |
| JSONスキーマ検証 | 中 | 更新後のスキーマで source.description が不正または不要な項目として扱われないか確認する |
| MCPツール検出 | 高 | AIエージェントに見せたい説明文が entities.<name>.description に書かれているか確認する |
| REST/GraphQLドキュメント | 中 | エンティティ説明が生成ドキュメントやGraphQLコメントとして期待通り表示されるか確認する |
| Azure App Service、Container Apps、AKSなどのホスティング | 低 | DAB設定ファイルを更新した場合のみ、通常の再デプロイや構成反映が必要になる |
source.description と description の違い
今回もっとも混乱しやすいのは、DAB設定ファイルに複数の「description系プロパティ」が存在する点です。特に source.description、description、source.object-description は役割が異なります。
| プロパティ | 書く場所 | 用途 | 今回の扱い |
|---|---|---|---|
entities.<Entity>.description | エンティティ直下 | エンティティそのものの説明。MCP tool discovery、生成APIドキュメント、GraphQLコメントで使われる説明として明確化 | 使うべき項目 |
entities.<Entity>.source.description | source 配下 | 以前スキーマに存在したが、実行時モデルに結び付いていなかった説明 | 削除対象。使わない |
entities.<Entity>.source.object-description | source 配下 | 元となるデータベースオブジェクトの人間向け説明。Microsoft LearnではMCPツール検出にも表示される説明として案内されている | 目的が合う場合に使う |
runtime.mcp.description | runtime.mcp 配下 | MCPサーバー全体の説明 | エンティティ説明とは別物 |
Microsoft LearnのDAB構成スキーマでは、entities.{entity-name}.source.object-description は元のデータベースオブジェクトの説明として扱われ、MCPツール検出中に表示されると説明されています。一方、今回削除されたのは object-description ではなく、source.description です。ここを取り違えないことが重要です。(Microsoft Learn)
修正前と修正後の設定例
MCPでAIエージェントに分かりやすい説明文を渡したい場合、source の中ではなく、エンティティ直下に description を置きます。
修正前：避けるべき書き方
{
"entities": {
"Todo": {
"source": {
"object": "dbo.Todos",
"type": "table",
"description": "To-do items managed by users"
},
"permissions": [
{
"role": "authenticated",
"actions": [ "read" ]
}
]
}
}
}この例では、description が source 配下にあります。今回のスキーマ修正では、この entities.*.source.description は不要なスキーマ項目として削除されています。元PRでも、このプロパティは実行時にデシリアライズされず、MCP出力にもつながらないと説明されています。(GitHub)
修正後：MCPに見せたい説明はエンティティ直下に置く
{
"entities": {
"Todo": {
"description": "User to-do items with title, due date, completion status, and owner information.",
"source": {
"object": "dbo.Todos",
"type": "table"
},
"permissions": [
{
"role": "authenticated",
"actions": [ "read" ]
}
]
}
}
}エンティティ直下の description には、AIエージェントやAPI利用者が「このエンティティをいつ使うべきか」を判断できる説明を書きます。単に「Todos table」ではなく、「期限、完了状態、所有者情報を持つユーザーのTo-do項目」のように、用途が分かる表現にするとMCPのツール選択にも役立ちます。Microsoft Learnでも、説明文はAIエージェントがスキーマを理解し、適切なデータを選ぶためのセマンティックメタデータとして位置付けられています。(Microsoft Learn)
source.object-description を併用する場合
データベースオブジェクト自体の説明も残したい場合は、source.object-description を使います。エンティティの業務上の意味と、物理的なデータベースオブジェクトの説明を分けて書くと、後から見ても意図が分かりやすくなります。
{
"entities": {
"Todo": {
"description": "User-facing task items used by the application and MCP clients.",
"source": {
"object": "dbo.Todos",
"object-description": "SQL table that stores each task record, including owner, due date, and completion flag.",
"type": "table"
}
}
}
}判断基準はシンプルです。AIエージェントやAPI利用者に「このエンティティは何か」を説明したいなら entities.<Entity>.description、物理的なテーブルやビューの補足説明を書きたいなら source.object-description を使います。
管理者・開発者が確認すべきポイント
DAB設定ファイルに source.description が残っていないか確認する
まず、DABの構成ファイルを検索します。単一の dab-config.json だけでなく、複数構成ファイルを使っている環境では、参照先の子ファイルも確認してください。DABは複数の構成ファイルに対応しており、各構成ファイルに data-source と entities または autoentities が必要とされています。(Microsoft Learn)
Linux、macOS、WSLでは次のように確認できます。
grep -R -n '"description"[[:space:]]*:' ./dab-config*.json ./configs 2>/dev/nullWindows PowerShellでは、次のようにJSONファイル内の description を横断検索できます。
Get-ChildItem -Recurse -Filter "*.json" |
Select-String -Pattern '"description"\s*:'検索結果を見て、source ブロックの中に description がある場合は修正候補です。すべての description が問題というわけではありません。エンティティ直下、フィールド、パラメーターなどの説明は用途に応じて有効です。
source.description の内容をどこへ移すか判断する
見つかった説明文は、機械的にすべて同じ場所へ移すのではなく、説明の内容で移行先を決めます。
| 既存の説明文の内容 | 移行先 | 例 |
|---|---|---|
| API利用者やAIエージェント向けに、エンティティの役割を説明している | entities.<Entity>.description | 「顧客の注文履歴。注文日、配送状態、合計金額を含む」 |
| 物理的なテーブル、ビュー、ストアドプロシージャの説明をしている | entities.<Entity>.source.object-description | 「dbo.Orders table storing order header records」 |
| 権限、認可、内部運用ルールを書いている | permissions や運用ドキュメントへ分離 | 「管理者のみ更新可」などは説明文ではなくアクセス制御で扱う |
| 機密情報、内部システム名、接続先情報を含む | 削除または一般化 | 接続文字列、内部コード名、個人情報は書かない |
特にMCP連携では、説明文がAIエージェントの判断材料になります。説明文に内部向けの略語だけを書いても効果は薄く、逆に機密性の高い業務情報を書きすぎると公開範囲の管理が難しくなります。
スキーマURLとCI/CD検証を見直す
DABの設定ファイルは $schema プロパティでJSONスキーマを指定でき、Microsoft Learnでは最新スキーマのURLと、特定バージョンのスキーマURLの使い分けが案内されています。(Microsoft Learn)
開発環境では最新スキーマを使うと変更に早く気付けますが、本番向けCIで常に releases/latest を参照していると、スキーマ更新により急に検証結果が変わる可能性があります。安定運用を優先するなら、リリース済みの特定バージョンのスキーマURLに固定し、DAB本体やコンテナイメージの更新タイミングと合わせてスキーマも更新する運用が安全です。
確認すべきCI/CD項目は次のとおりです。
| 確認項目 | 見るべきポイント |
|---|---|
| JSONスキーマ検証 | 更新後スキーマで source.description が検出されないか |
| DAB CLIのバージョン | 開発、検証、本番でDABのバージョン差が大きくないか |
| コンテナイメージ | DAB更新と設定ファイル更新が同じリリース単位で管理されているか |
| MCPテスト | describe_entities などで説明文が期待どおり返るか |
| ロール別確認 | MCPで見えるエンティティが権限設定どおりに制限されているか |
MCP連携で特に注意したい設定
MCPで使う説明文は、単なるコメントではありません。Microsoft Learnでは、説明文はAIエージェントがエンティティ、フィールド、パラメーターを理解し、より適切なクエリやツール選択を行うためのメタデータとして説明されています。また、説明文は describe_entities MCPツールを通じて公開されるとされています。(Microsoft Learn)
そのため、MCP向けの説明文では次の3点を意識してください。
| 観点 | 悪い例 | 良い例 |
|---|---|---|
| 用途が分かるか | Orders table | Customer purchase orders, including order date, payment status, and shipment status. |
| エージェントが選びやすいか | Data for app | Use this entity when answering questions about customer order history and fulfillment progress. |
| 機密情報を含まないか | Internal VIP fraud watch table | Customer risk review records. Access is restricted by role-based permissions. |
説明文は、権限制御の代わりにはなりません。エンティティをMCPに公開するか、どの操作を許可するかは、permissions やMCP関連の実行時設定で制御します。DAB 2.0 preview CLIでは、runtime.mcp.enabled や runtime.mcp.dml-tools.describe-entities などのMCP関連オプションも用意されています。(Microsoft Learn)
展開時の注意点
今回の変更はスキーマ修正が中心のため、Azureリソースの大規模な移行は通常必要ありません。ただし、DABをAzure App Service、Azure Container Apps、Azure Kubernetes Service、Azure Container Instancesなどで動かしている場合、設定ファイルの修正を本番へ反映するには、通常のデプロイ手順に沿って再起動や再デプロイが必要になることがあります。DABはAzure上だけでなく、コンテナやオンプレミスでも実行できるため、ホスティング先ごとの反映手順を確認してください。(Microsoft Learn)
展開前には、次の順序で確認すると失敗を減らせます。
| 手順 | 作業 | 失敗しやすいポイント |
| -: | ———————————————– | ——————————————– |
| 1 | 既存設定から source.description を検索 | 複数構成ファイルや環境別ファイルを見落とす |
| 2 | 説明文を description または object-description へ移す | すべてを object-description に移して、エンティティ説明が不足する |
| 3 | JSONスキーマ検証を実行 | IDEの古いスキーマキャッシュで誤判定する |
| 4 | ステージング環境でDABを起動 | 本番とDABバージョンが違い、結果が再現しない |
| 5 | MCPクライアントでツール検出を確認 | 説明文は直したが、MCP自体や対象ロールの権限が無効になっている |
| 6 | 本番へ反映 | 設定ファイルだけ更新し、コンテナやホスト側に反映されていない |
特に本番環境では、「スキーマ修正だから影響なし」と判断して確認を省略しないほうが安全です。ランタイム挙動が変わらなくても、CIのスキーマ検証、エディターの補完、MCPツール検出の見え方は開発者体験やエージェントの精度に直結します。
よくある誤解と対処法
source.description を残しても動くなら、そのままでよい？
短期的にはDABが起動する環境もあり得ますが、残すメリットはありません。元PRでは、source.description は実行時に無視されていた項目と説明されています。MCPに説明文を出したいなら、エンティティ直下の description に移すべきです。(GitHub)
source.object-description に移せば十分？
目的によります。データベースオブジェクトの説明なら source.object-description が適しています。しかし、AIエージェントやAPI利用者に「このエンティティをどう使うか」を伝える説明なら、エンティティ直下の description を使うほうが自然です。両方に同じ文章を重複して書くより、役割を分けて短く具体的に書くと運用しやすくなります。
これはセキュリティ修正？
今回のPR自体は、セキュリティ修正というよりスキーマとドキュメントの整合性修正です。ただし、MCPで説明文が表示されることを考えると、説明文に機密情報を書かないという運用上の注意は重要です。
DAB 2.0を使っていない環境も対応が必要？
DAB 2.0系や release/2.0 のスキーマを参照している環境は、特に確認が必要です。一方、異なる安定版スキーマを固定している環境では、すぐにCI結果が変わらない場合もあります。ただし、将来のアップグレード時に同じ問題が出る可能性があるため、今のうちに source.description をなくしておくと移行が楽になります。
まず実施すべきアクション
今回のMicrosoft Azure documentation updateで実務上もっとも重要なのは、MCPに見せたい説明文を source.description に書かず、entities.<Entity>.description に置くことです。変更自体は小さいものの、AIエージェントがDABのエンティティをどう理解するかに関わるため、MCP連携を使っている環境では早めに確認する価値があります。
まずはDAB設定ファイルを検索し、source 配下に description がないか確認してください。見つかった場合は、説明の内容に応じて entities.<Entity>.description または source.object-description へ整理します。その後、更新後のスキーマで検証し、ステージング環境でMCPの describe_entities 出力を確認してから本番へ反映する流れが安全です。
コメント