---
title: バージョニングと後方互換
sidebar:
  order: 8
---

## パスバージョニング

API バージョンは URL パスに含まれます（`/v1/...`）。**同一バージョン内では、レスポンス構造およびリクエスト契約に対する破壊的変更を行いません。**

この保証の対象は API の契約（フィールドの有無・名前・型、パラメータの仕様）です。配信されるデータの値そのもの（訂正・再集計にともなう変化）は対象に含みません。

## 非破壊的変更（予告なく行うことがある）

- レスポンスへのフィールド追加
- 任意リクエストパラメータの追加
- enum への値追加（利用側の分岐を壊さないもの）
- **データの訂正・再計算による値の変化**（一次情報の訂正、集計ロジックの不具合修正、遡及的な再計算を含む）

**利用側は未知のフィールドを無視する実装にしてください。**

## 破壊的変更（新バージョンで行う）

- フィールドの削除・リネーム・型変更
- 必須パラメータの追加
- 既定の挙動（ソート順・パラメータの既定値）の変更
- エンドポイントの削除

## 例外

法令・データ提供元との契約・セキュリティ上の要請により、同一バージョン内であっても変更が必要になる場合があります。この場合は原則として変更履歴で事前に告知し、可能な限り移行期間を設けます。ただし、脆弱性対応など緊急を要する場合は、変更を先行して適用し、変更履歴ですみやかに告知します。

また、**提供実体を持たないフィールド**（全対象・全期間にわたって値が存在せず、上流に算出・収集の実装が無いもの）は、同一バージョン内で提供項目から削除することがあります。利用者が受け取る値（常に `null`）は変わらないためです。削除にあたっては、事前に実データで全期間・全対象にわたり値が存在しないことを確認し、変更履歴で告知します。

**ベータ期間中の単位の統一**も、同一バージョン内で行うことがあります。フィールド名・型は保ったまま値のスケールが変わり、そのフィールドをしきい値として受け取るパラメータ（`/screening` の `filters`）の解釈も同時に変わります。対象・変更前後の単位・移行方法は変更履歴に記載します（実施例: [金額をすべて円単位で返すように変更](/changelog/amounts-in-jpy)）。ベータ終了後は行いません。

## 非推奨化（deprecation）

バージョンを廃止する場合は、ドキュメントと変更履歴で事前に告知し、移行期間を設けます。