Microsoft developer platformのJSON Schema対応とは？PR #566の変更点と移行確認ポイント

Microsoft developer platformでスキーマ登録まわりを使っている場合、今回まず確認すべき結論は 「従来のPython .py スキーマではなく、JSON Schema .json を前提に運用する必要がある」 という点です。特にSchema Vault、スキーマ登録API、デプロイスクリプト、既存スキーマ資産を管理しているチームは、アップロード形式・Content-Type・既存レコードの移行確認を早めに行うべきです。PR #566はGitHub上で2026年5月6日にdevブランチへマージされ、JSON Schema対応とPythonスキーマ廃止を含む変更として整理されています。(GitHub)

Microsoft developer platformで何が変わったのか

今回の「Microsoft developer platform documentation update: feat: Support JSON Schema uploads and update related deployment scripts」は、Microsoftのcontent-processing-solution-acceleratorにおけるスキーマ管理方式の変更です。

これまでの流れでは、スキーマをPythonのPydanticクラスとして.pyファイルで扱う経路がありました。今回の更新では、スキーマを実行可能なコードではなく、宣言的なJSON Schemaドキュメントとして登録・管理する方向に切り替わっています。PRの説明では、Pythonコードをアップロード・実行する必要をなくし、スキーマ作成と登録を簡素化しつつ、リモートコード実行リスクを下げる目的が示されています。(GitHub)

実務上の見方としては、「ドキュメント更新」だけではなく、API、ワーカー、サンプル、テスト、デプロイスクリプトまで影響する変更です。単に拡張子を.pyから.jsonに変えるだけでは不十分で、登録手順や既存SchemaSetとの紐付けまで確認する必要があります。

変更点の要点

確認項目	変更前の考え方	変更後の考え方	実務で見るべきポイント
スキーマ形式	Python `.py`のPydanticクラスを使う経路があった	JSON Schema `.json`が前提	既存の`.py`ファイルを棚卸しする
アップロード	Pythonスキーマを登録できる場合があった	`.json`のみ受け付ける	API・スクリプト・CIの送信ファイルを確認
Content-Type	形式ごとに分岐していた	JSON Schemaは`application/json`	multipart送信時のMIMEタイプを確認
実行時処理	アップロードされたPythonコードを扱う経路があった	JSONを読み取り、メモリ上でPydanticモデル化	コード実行前提のカスタム処理は見直し
既存レコード	Python形式のSchemaが残っている可能性	JSONとして再登録が必要になる可能性	Cosmos DBのSchemaメタデータを確認

PR内では、APIが.pyアップロードをHTTP 415で拒否し、ワーカー側もPython形式のスキーマ処理を拒否するため、既存のCosmos DBレコードはJSON Schemaとして再登録する必要がある旨が示されています。(GitHub)

影響を受ける人

既存のPythonスキーマを使っている開発者

最も影響が大きいのは、過去に.py形式でPydanticスキーマを作成し、Schema Vaultへ登録していたチームです。

たとえば、請求書、保険請求、修理見積、本人確認書類などの文書タイプごとにPythonクラスを作り、フィールド定義や説明文を管理していた場合、そのままでは新しいJSON Schema前提の運用に合わない可能性があります。

確認すべきことは次の3つです。

確認対象	見るべき内容	対応の目安
スキーマファイル	`.py`が残っていないか	`.json`へ置き換える
登録済みSchema	`FileName`や`Format`が旧形式でないか	JSON Schemaとして再登録する
SchemaSet	古いSchema IDを参照していないか	新しいSchema IDをSchemaSetへ追加する

特に注意したいのは、ファイルだけをJSON化しても、既存のSchemaSetが古いSchema IDを参照したままだと処理時に期待どおり動かない点です。移行作業では「スキーマ変換」「再登録」「SchemaSetへの追加」「実処理テスト」までを1セットで確認してください。

デプロイ自動化を管理している担当者

今回の更新では、BashとPowerShellのデプロイスクリプトもJSON Schema前提に更新されています。post_deployment.shでは.json以外の拡張子をスキップし、アップロード時のContent-Typeをapplication/jsonにしています。(GitHub)

PowerShell版のpost_deployment.ps1でも同様に、.jsonのみを受け付け、レガシーな.py形式はRCE対策の一環として除外されています。(GitHub)

そのため、azd up後の自動登録、CI/CD内の後処理、独自の初期化スクリプトを組んでいる場合は、次の観点で見直してください。

チェック項目	失敗しやすい例	修正方針
manifestのファイル名	`invoice_schema.py`を参照している	`invoice_schema.json`に変更
multipartのContent-Type	`text/x-python`のまま送っている	`application/json`に変更
スクリプトの拡張子判定	`.py`も許可している	`.json`のみ許可
デプロイ後登録	API起動前に登録処理が走る	API readinessチェック後に実行
重複登録	毎回同じSchemaを新規登録する	既存ClassName確認を入れる

JSON Schema登録で守るべき主なルール

更新後のドキュメントでは、Schema Vaultが受け付けるのはJSON Schemaドキュメントであり、Draft 2020-12、ルートの"type": "object"、"properties"ブロックが必要とされています。アップロードできるサイズは最大1MBです。(GitHub)

最低限、次のような構造にしておくと移行時の確認がしやすくなります。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "InvoiceSchema",
  "description": "請求書から請求番号、請求日、支払期日、金額、取引先情報を抽出するためのスキーマ",
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": ["string", "null"],
      "description": "請求書番号。例: INV-2026-001"
    },
    "invoice_date": {
      "type": ["string", "null"],
      "description": "請求日。YYYY-MM-DD形式で返す"
    },
    "total_amount": {
      "type": ["number", "null"],
      "description": "税込または合計として記載された請求金額"
    }
  }
}

ここで重要なのは、descriptionを単なる説明ではなく、AI抽出の指示として書くことです。公式ドキュメントでも、フィールド説明がLLMの抽出品質に直接影響するため、明確で具体的な説明と例を含めることが推奨されています。(GitHub)

ClassNameの扱いに注意する

JSON Schema移行で見落としやすいのがClassNameです。

新しい登録処理では、JSON Schema内にtitleがある場合、そのtitleがSchema Vault上のClassNameとして使われます。titleがない場合は、リクエスト本文のClassNameまたはファイル名がフォールバックとして使われます。(GitHub)

つまり、次のようなズレが起きる可能性があります。

{
  "title": "InvoiceSchemaV2",
  "type": "object",
  "properties": {}
}

一方で登録リクエスト側が次のようになっている場合です。

{
  "ClassName": "InvoiceSchema",
  "Description": "Invoice extraction schema"
}

この場合、titleが優先されるため、登録後のClassNameはInvoiceSchemaV2になる可能性があります。移行後に既存の自動処理がClassNameで検索・照合している場合は、意図しない重複登録やSchemaSetへの追加漏れにつながります。

ClassNameを安定させる判断基準

状況	推奨対応
既存処理がClassNameを参照している	JSON Schemaの`title`を既存ClassNameに合わせる
新バージョンとして分けたい	`InvoiceSchemaV2`のように明示的に変える
ファイル名ベースで管理したい	`title`を省略するのではなく、運用ルールを決めておく
複数チームで編集する	manifest、JSON Schema、登録結果のClassNameをレビュー対象にする

`.py`から`.json`へ移行する手順

移行作業は、次の順番で進めると手戻りを減らせます。

手順	作業	確認ポイント
1	既存スキーマを棚卸しする	`.py`ファイル、Blob Storage、Cosmos DBのSchema情報を確認
2	JSON Schemaを作成する	`type: object`、`properties`、`description`を入れる
3	manifestを更新する	`schema_info.json`の`File`を`.json`にする
4	Schema Vaultへ登録する	`POST /schemavault/`で`application/json`として送る
5	SchemaSetへ追加する	新しいSchema IDを既存または新規SchemaSetに紐付ける
6	実データで処理する	Mapステップ、抽出結果、バリデーション結果を確認
7	旧Schema参照を外す	古い`.py`参照や不要なSchema IDを整理する

公式ドキュメントでは、スキーマ登録後にSchemaSetを作成し、登録済みSchemaをSchemaSetへ追加する流れが示されています。Claim作成時にはSchemaSetが割り当てられ、実行時にはSchemaメタデータをCosmos DBから参照し、JSON SchemaをBlob Storageから読み込む構成です。(GitHub)

API登録時の確認ポイント

Schema Vault APIはPOST /schemavault/で新規登録、PUT /schemavault/で更新を行います。どちらもmultipart/form-dataで、JSONパートとファイルパートを送る形です。新しいルールでは、.jsonのみ受け付け、ファイルサイズは最大1MB、JSON Schemaとして不正な場合はエラーになります。(GitHub)

登録時の考え方は次のとおりです。

POST /schemavault/
Content-Type: multipart/form-data

data: { "ClassName": "InvoiceSchema", "Description": "Invoice extraction" }
file: invoice.json (application/json)

API側では、アップロードファイルの拡張子が.jsonでない場合はHTTP 415、サイズ超過時はHTTP 413、JSON Schemaとして不正な場合はHTTP 400が返る設計になっています。(GitHub)

エラーが出たときの切り分け

エラーの傾向	あり得る原因	確認する場所
HTTP 415	`.py`や別拡張子を送っている	ファイル名、スクリプトの拡張子判定
HTTP 413	スキーマが1MBを超えている	`$defs`の肥大化、不要な説明文
HTTP 400	JSON Schemaとして不正	`type`、`properties`、JSON構文
登録後にClassNameが違う	`title`が優先されている	JSON Schemaの`title`
実行時に旧スキーマエラー	SchemaSetが古いSchema IDを参照	SchemaSet内のSchema一覧

実行時の処理はどう変わるか

ワーカー側では、Blob StorageからJSON Schemaをダウンロードし、json.loadsで読み取り、Pydanticのcreate_modelを使ってメモリ上にモデルを作る処理が追加されています。アップロードされたコードをexec、compile、importlibなどで実行しないことが明記されています。(GitHub)

これはセキュリティ上の大きな意味があります。従来のように「スキーマ定義のために実行可能コードを受け入れる」設計では、登録権限を持つユーザーや侵害された経路から危険なコードが混入するリスクがあります。JSON Schema化により、スキーマは「実行するもの」ではなく「解釈するデータ」になります。

一方で、Python側のカスタムバリデーションに頼っていた場合は注意が必要です。ドキュメントでは、JSON Schemaは純粋なデータであり、Pydanticのfield_validatorのような命令的なカスタム検証は持てないため、必要な場合は抽出後の下流処理で実装する考え方が示されています。(GitHub)

移行時に失敗しやすいポイント

フィールド説明が抽象的すぎる

JSON Schemaのdescriptionは、単なる補足説明ではなく抽出品質に関わる重要な情報です。

悪い例:

"date": {
  "type": ["string", "null"],
  "description": "日付"
}

改善例:

"date_of_loss": {
  "type": ["string", "null"],
  "description": "事故発生日。書類上のDate of Loss、Loss Date、事故日などに該当する日付。YYYY-MM-DD形式で返す"
}

AIに抽出してほしい項目は、同義語、表記ゆれ、返却形式、見つからない場合の扱いまで書くと安定しやすくなります。

必須項目を増やしすぎる

JSON Schemaではrequiredを指定できますが、文書処理ではすべての書類に同じ項目が存在するとは限りません。現場では、必須扱いを強くしすぎると、抽出後の検証で失敗しやすくなります。

入力文書に存在しない可能性がある項目は、次のようにnullを許容する設計が現実的です。

"purchase_order_number": {
  "type": ["string", "null"],
  "description": "発注書番号。記載がない場合はnull"
}

`$ref`の使い方が広すぎる

バリデーション側では、サポートされる$refがローカル参照の#/$defs/...または#/definitions/...に限定されています。外部URLや別ファイルへの参照を前提にしたJSON Schemaは、そのままでは使えない可能性があります。(GitHub)

複雑なスキーマを作る場合も、まずは同一ファイル内の$defsでまとめるのが安全です。

{
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "postal_code": {
          "type": ["string", "null"],
          "description": "郵便番号"
        }
      }
    }
  }
}

既存環境で今日確認すべきチェックリスト

今回のMicrosoft developer platformのJSON Schema対応は、開発者だけでなく、運用・デプロイ担当にも影響します。以下を順番に確認してください。

優先度	チェック内容	完了条件
高	`.py`スキーマが残っていないか	リポジトリ、Blob Storage、manifestから`.py`参照を排除
高	`schema_info.json`が`.json`を参照しているか	登録対象ファイルがすべてJSON Schema
高	登録APIが`application/json`で送信しているか	multipartのfileパートが正しいContent-Type
高	SchemaSetが新しいSchema IDを参照しているか	Claim作成後に対象文書タイプを選べる
中	JSON Schemaの`title`とClassNameが一致しているか	登録後のClassNameが想定どおり
中	`description`が抽出指示として十分か	例、形式、null条件が書かれている
中	`$ref`がローカル参照のみか	`#/$defs/...`または`#/definitions/...`を使用
低	旧スクリプトやREADMEが残っていないか	チーム内ドキュメントもJSON Schema前提に更新

どう対応すべきか

今回の変更は、JSON Schemaを新たに「サポートした」だけではなく、最終的にはPython .pyスキーマを使う旧経路を外す方向の変更として見るべきです。特にSchema Vaultへスキーマを登録している環境では、既存スキーマの形式、SchemaSetの参照、デプロイ後の自動登録処理を確認しないと、移行後に文書処理のMapステップで失敗する可能性があります。

まずはリポジトリ内のschema_info.jsonとスキーマファイルを確認し、.py参照が残っていればJSON Schemaへ置き換えてください。次に、POST /schemavault/で登録し直し、新しいSchema IDをSchemaSetに追加します。最後に、実際のPDFや画像を使って抽出結果を確認し、descriptionの不足やClassNameのズレを調整するのが安全です。

この更新を単なる形式変更として扱うと、移行漏れが起きやすくなります。実務では「セキュリティ改善」「スキーマ作成の標準化」「デプロイ自動化の修正」を同時に進める変更として捉えると、影響範囲を見誤りにくくなります。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

Microsoft developer platformのJSON Schema対応とは？PR #566の変更点と移行確認ポイント

Microsoft developer platformで何が変わったのか

変更点の要点

影響を受ける人

既存のPythonスキーマを使っている開発者

デプロイ自動化を管理している担当者

JSON Schema登録で守るべき主なルール

ClassNameの扱いに注意する

ClassNameを安定させる判断基準

`.py`から`.json`へ移行する手順

API登録時の確認ポイント

エラーが出たときの切り分け

実行時の処理はどう変わるか

移行時に失敗しやすいポイント

フィールド説明が抽象的すぎる

必須項目を増やしすぎる

`$ref`の使い方が広すぎる

既存環境で今日確認すべきチェックリスト

どう対応すべきか

この記事を書いた人

コメント

コメントするコメントをキャンセル

Microsoft developer platformのJSON Schema対応とは？PR #566の変更点と移行確認ポイント

Microsoft developer platformで何が変わったのか

変更点の要点

影響を受ける人

既存のPythonスキーマを使っている開発者

デプロイ自動化を管理している担当者

JSON Schema登録で守るべき主なルール

ClassNameの扱いに注意する

ClassNameを安定させる判断基準

.pyから.jsonへ移行する手順

API登録時の確認ポイント

エラーが出たときの切り分け

実行時の処理はどう変わるか

移行時に失敗しやすいポイント

フィールド説明が抽象的すぎる

必須項目を増やしすぎる

$refの使い方が広すぎる

既存環境で今日確認すべきチェックリスト

どう対応すべきか

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

`.py`から`.json`へ移行する手順

`$ref`の使い方が広すぎる

コメントするコメントをキャンセル