バージョニングとは？セマンティック/APIバージョニングの意味と運用設計を実装者向けに解説【2026年】

バージョニングとは、ソフトウェアやAPI、データベーススキーマなどの成果物に一意の版番号を割り当て、変更の履歴と互換性を管理する取り決めです。番号の付け方が曖昧だと、依存関係の解決が壊れたり、APIの利用側が予期せず動かなくなったりします。この記事の主題は、代表的なセマンティックバージョニング（MAJOR.MINOR.PATCH）の規則、APIバージョニングの3方式、データベースやコンテナイメージの版管理、そして「どこまで作り込むべきか・いつ番号を上げるか」という実装現場の判断基準です。公式仕様と実サービスの具体例で、対象別に整理していきます。

まとめ：バージョニングの目的と対象別の版設計・後方互換の要点整理

バージョニングの目的は、版番号そのものを増やすことではありません。変更が利用側にどう影響するかを、番号だけで一目で伝えることにあります。番号の増え方に意味を持たせれば、依存を更新する側は差分の危険度を数字から判断できます。

実装で押さえる要点は4つあります。第一に、公開する成果物（ライブラリ・公開API）はセマンティックバージョニングで後方互換の破壊をMAJORに集約する。第二に、APIは版を乱発せず、後方互換を保てる変更なら版を上げずに追加する。第三に、データベーススキーマとコンテナイメージは番号付きのマイグレーションと明示タグで再現性を担保する。第四が、破壊的変更は避けるのが基本で、やむを得ず出すときだけMAJORを上げ、旧版の廃止時期を先に告知することです。番号運用を軽く見て後方互換を崩すと、利用側の障害対応と自社の保守コストが同時に膨らみます。

バージョニングの定義と版番号が担う識別・比較・互換の3つの役割

バージョニングは「同じ成果物の異なる状態を、比較・特定できる識別子で区別する仕組み」です。識別子には連番、日付、ハッシュ、そして意味を持たせた番号などがあり、対象によって使い分けます。

版番号が担う識別・比較・互換という3つの役割と設計上の意味合い

版番号の役割は3つに整理できます。ひとつめが識別で、どのビルドを指すかを一意に決める働きです。ふたつめの比較では、1.4.0 と 1.10.0 のどちらが新しいかを機械的に判定できることが求められます。みっつめが互換の伝達で、番号の増え方から「安全に更新できるか」を読み取れる状態を指します。単なる連番は識別と比較には足りますが、互換の情報を持ちません。セマンティックバージョニングが広く使われる理由は、この3つ目を番号そのものに埋め込んだ点にあります。

バージョニングの対象——ソース・ライブラリ・API・スキーマ

版管理の対象は一種類ではありません。実務で番号付けの設計が要るのは、次のような対象です。

• ソースコード：コミット単位の履歴とリリースタグ（Gitのハッシュとタグ）
• 配布ライブラリ・パッケージ：npmやPyPIに公開する版（依存解決の基準になる）
• Web API：外部が呼び出すエンドポイントの仕様変更
• データベーススキーマ：テーブル定義の変更履歴（マイグレーション）
• コンテナイメージ・成果物：デプロイする実体のタグ

対象が違えば、向いている番号体系も変わります。ライブラリはセマンティックバージョニング、スキーマは連番のマイグレーション、イメージはコミットハッシュや日付タグ、というように対象ごとに適した方式を選ぶのが実務の基本です。全対象に同じ体系を強いる必要はありません。

セマンティックバージョニングのMAJOR・MINOR・PATCHの増減規則

セマンティックバージョニング（SemVer）は、版番号を MAJOR.MINOR.PATCH の3つの数値で表す仕様です。公式仕様は 2.0.0系（semver.org）が広く参照され、npmやCargoなど主要なパッケージエコシステムの依存解決がこの規則を前提にしています。

MAJOR・MINOR・PATCHの3数値が示す変更の意味と上げる条件

3つの数値は、それぞれ変更の性質と対応します。番号を上げる条件は仕様で明確に定義されています。

この規則があるため、利用側は「1系のうち後方互換のある最新」といった依存指定で、破壊的変更を避けつつ修正だけを取り込めます。番号を「大きいほうが上等だから」と気分で上げてしまうと、この依存解決の前提そのものが崩れます。数字は宣伝文句ではなく、互換性の約束です。

0.y.z・プレリリース識別子・ビルドメタデータの扱いと比較順位

MAJORが0のあいだ（0.y.z）は初期開発フェーズと定義され、いつ何が壊れてもよい版として扱われます。安定版を約束する節目が 1.0.0 のリリースです。正式版の前段には 1.0.0-alpha や 1.0.0-rc.1 のように、ハイフンでプレリリース識別子を付けます。プレリリースは、対応する正式版より低い順位として比較される点に注意が必要です。ビルド情報は 1.0.0+20260711 のようにプラス記号で付与しますが、これは版の優先順位には影響しません。0系のまま長く運用して破壊的変更を繰り返すのは仕様上は正当な選択です。ただし外部に依存されているなら、早めに 1.0.0 で安定を約束したほうが利用側の負担は軽くなります。

APIバージョニングの3方式と後方互換を保つ実装設計の選び方

APIバージョニングは、公開したエンドポイントの仕様を変えるときに、既存の利用者を壊さず新旧を区別する手法です。ライブラリのSemVerと考え方は共通しますが、番号をどこに載せるかで運用の手触りが変わります。認証やCORSと合わせてエンドポイントを設計する段階で、版の載せ方も一緒に決めておくのが安全です。REST APIそのものの実装はSpring BootとReactを連携するREST API設計の手順が参考になります。

URIパス・クエリ・ヘッダーで版を指定する3方式の選択の基準

版の指定場所には、主に3つの流派があります。どれを選ぶかで、可読性と柔軟性のバランスが変わります。

実サービスの選択は割れています。Google Cloud API Design Guideはメジャー版のみをURIに含める方針を示し、GitHubのREST APIはAcceptヘッダーでの版指定を採ってきました。Stripeは 2020-08-27 のような日付ベースの版をヘッダーで扱い、アカウントごとに固定する運用をとっています。実務では「利用者に非エンジニアが含まれるか」を基準にすると選びやすいでしょう。外部ベンダーや取引先と仕様を突き合わせる機会が多いなら、URLを見れば版が分かるパス方式が扱いやすいです。

破壊的変更を避ける追加設計と旧版廃止（deprecation）の告知

APIバージョニングで最初に検討すべきは「版を増やさずに済ませられないか」という点です。フィールドの追加、任意パラメータの追加、新エンドポイントの追加は、既存の呼び出しを壊さないため版を上げる必要がありません。版を上げるべきなのは、フィールドの削除・型変更・必須化・レスポンス構造の変更といった、後方互換を壊す変更に限られます。新しいメジャー版を出したら、旧版の廃止（deprecation）予定日を先に告知し、移行期間中は両版を並行提供するのが原則です。告知なく旧版を止めれば、利用側のシステムが同時に停止します。版の乱発は、自社側で維持すべきコードパスをその数だけ増やす負債です。後方互換の維持を第一に置く設計が、結局は保守を軽くします。

データベーススキーマとコンテナイメージの版管理と再現性の担保

アプリ本体だけでなく、データの器とデプロイの実体にも版管理が要ります。ここを軽視すると、環境ごとにスキーマがずれたり、動いていたイメージを再現できなくなったりします。

スキーマのマイグレーション番号と適用履歴による前進のみの管理

データベーススキーマの変更は、番号付きのマイグレーションファイルで管理します。FlywayはSQLファイルを V1__init.sql、V2__add_index.sql のようにバージョンプレフィクスで並べ、適用済みの版を専用の履歴テーブルに記録して、未適用分だけを順に流す仕組みです。LiquibaseもXMLやYAMLのchangesetで同様の履歴を持ちます。アプリの起動時に自動で差分を当てる構成にしておくと、環境間のスキーマずれを避けられるのが利点です。基本は番号順に前進のみを積む運用で、適用済みの版を書き換えると履歴の整合が壊れます。実装の具体例はSpring BootとFlywayでMongoDBのマイグレーションを設定する手順が詳しいです。スキーマ更新を発注や投資の判断としてとらえたい場合はマイグレーションとは何かを整理した解説もあわせて参照してください。

イメージタグの明示指定と、latestタグ運用に潜む落とし穴

コンテナイメージのタグ付けは、再現性を大きく左右します。latest タグは「その時点の最新」を指すため、同じ latest でも、昨日と今日で中身が変わりえる不安定なタグです。本番デプロイでは myapp:1.4.2 のようにSemVerタグを付けるか、myapp:sha-a1b2c3d のようにコミットハッシュを埋め込み、どのソースから作られたイメージかを一意に辿れるようにします。ソース側のコミットとイメージタグを対応づけておけば、障害時に「どの版が動いていたか」を即座に特定できます。latest だけで運用してロールバック先を見失う事故は、版設計の甘さが表面化した典型例です。

バージョンを上げる判断基準と、破壊的変更かどうかの切り分け方

番号を上げるかどうかの迷いは、ほぼ「この変更は後方互換を壊すか」という一点に集約されます。ここを明確な基準で切り分けられれば、SemVerもAPIバージョニングも運用がぶれません。

後方互換を壊す変更と壊さない変更を、利用側の視点で判別する基準

判別は利用側の視点で行います。「既存の呼び出しコードを一切変えずに、これまでどおり動くか」を問い、動くなら後方互換あり、動かなくなるなら破壊的変更という切り分けです。

• 壊さない（MINOR/PATCH）：フィールド追加、任意引数の追加、新エンドポイント追加、内部実装の改善、バグ修正
• 壊す（MAJOR）：フィールドや引数の削除・改名、型の変更、任意だった項目の必須化、デフォルト値の変更、エラー形式の変更

判断に迷う代表例が、レスポンスに項目を「追加」する変更です。多くの場合は後方互換ですが、利用側が未知の項目でエラーにする厳格なパースをしていると壊れます。契約（スキーマ）で「未知項目は無視する」と定めておけば、追加を安全なMINORとして扱えます。ここを曖昧にしたまま項目を足すと、追加のたびに利用側が壊れかねません。

版の不整合（バージョンスキュー）が生む障害と回避する更新順序

分散したコンポーネントが別々の版で動くと、版の不整合による障害が起きます。クライアントとサーバー、あるいは複数のマイクロサービスがローリング更新の途中で新旧混在すると、旧クライアントが新サーバーの変更を解釈できずに失敗するのです。回避策は、後方互換を保った変更設計と、更新順序の制御にあります。サーバー側を先に後方互換で更新してから、クライアントを進める順序が基本です。破壊的変更を一度に全体へ適用しようとすると、この混在期間が事故の温床になります。現象の詳細はVersion Skew（バージョンスキュー）の意味と発生シナリオの解説が参考になります。

どこまでバージョニングを作り込むかの公開範囲別の採用判断と見送り

版管理は、成果物の公開範囲に応じて作り込みの度合いを変えるべきものです。あらゆる対象にフルのSemVerと多版並行提供を課すのは、過剰投資になります。ここでは条件を付けて言い切ります。

公開範囲別の推奨——社内ツール・公開ライブラリ・外部公開API

判断の軸は「壊れて困るのが誰か」です。困る相手が誰かで、必要な作り込みは大きく変わります。

• 社内限定のツール・バッチ：利用者を把握でき、まとめて更新できるなら、SemVerのフル運用は過剰です。0.y.z や日付タグ、コミットハッシュで十分に足ります。
• 外部公開ライブラリ・パッケージ：見知らぬ利用者が依存解決するため、SemVerを厳守し、破壊的変更は必ずMAJORに集約します。ここでの手抜きは他社のビルドを壊します。
• 外部公開API：版の乱発を避け、後方互換の維持を最優先にします。版を上げるのは互換を壊すときだけに限り、旧版の廃止は移行期間を設けて先に告知します。

採用しない場面も明示します。利用者が自分たちだけで、リリースのたびに全員が同時に上がる内製ツールに、多版の並行提供と厳格なSemVerを持ち込むのは見送るべきです。維持すべき版とテスト対象を無用に増やし、保守の手間だけが残ります。過剰な版管理は、丁寧さではなく負債です。

版管理を軽視した場合に運用フェーズで生じる保守コストと運用体制

版設計の甘さは、公開直後ではなく運用フェーズで請求書として届きます。番号に意味がないと、利用側は更新のたびに全機能を回帰テストせざるを得ません。自社は「どの版に何を入れたか」を毎回調べ直すことになります。後方互換を崩す変更を告知なく出せば、取引先のシステムが止まり、緊急対応に追われる事態にもなりかねません。既存システムの版管理設計の見直しや、後方互換を保った改修の体制づくりは、保守運用・内製化支援として外部の知見を入れながら進めると、事故の起きにくい運用に寄せられます。番号を増やす前に、増やさずに済む後方互換の設計を先に検討すること。それが結果として最も保守コストを下げます。

バージョニングの実装と運用の現場でよくある質問への実務的な回答

バージョニングの実装でつまずきやすい点を、検索されやすい疑問に沿って答えます。

バージョニングとバージョン管理（Git）は同じ意味ですか？

重なりますが同一ではありません。バージョン管理（バージョンコントロール）はGitに代表される、ソースコードの変更履歴を記録・分岐・統合する仕組みを指すことが多い語です。バージョニングはより広く、成果物に版番号を割り当てて互換性を伝える取り決め全般を指します。Gitのコミットやタグはソースのバージョニングの一手段で、日常のコマンドは用途別のGitコマンド一覧で確認できます。

セマンティックバージョニングで1.9.0の次は2.0.0ですか？

いいえ、各位置は独立した整数で、桁上がりはしません。1.9.0の次に後方互換のある機能追加をするなら1.10.0になります。2.0.0へ上がるのは、後方互換を壊す変更（破壊的変更）を入れたときだけです。1.9から1.10を「小さい」と誤解して番号を飛ばすと、依存解決の比較がずれます。

APIバージョニングはURLとヘッダーのどちらが良いですか？

利用者層で選ぶのが実務的です。外部ベンダーや非エンジニアと仕様を確認する機会が多いなら、URLを見れば版が分かるパス方式が扱いやすいでしょう。API利用者がエンジニアに限られ、URLの汚れを避けたいならAcceptヘッダー方式が向きます。どちらの方式でも、版を増やす前に後方互換で追加できないかを先に検討する原則は変わりません。

プレリリース版とビルドメタデータの違いは何ですか？

両者は順位への影響が異なる点に注意が必要です。1.0.0-rc.1 のようなプレリリース識別子（ハイフン以降）は、対応する正式版 1.0.0 より低い版として比較されます。1.0.0+build.5 のようなビルドメタデータ（プラス以降）は、ビルドの識別情報にすぎず、版の優先順位の比較では無視されます。

データベースのスキーマ変更はどう版管理しますか？

番号付きのマイグレーションファイルで前進のみを積む方式が基本です。FlywayやLiquibaseで V1、V2 と連番のファイルを用意し、適用済みの版を履歴テーブルに記録して未適用分だけを順に流します。適用済みのファイルを後から書き換えると履歴の整合が崩れるため、修正は必ず新しい番号のマイグレーションを追加して行います。

関連記事

• Version Skew（バージョンスキュー）とは何か：版の不整合が起こす障害と、後方互換を保った更新順序の考え方を掘り下げます。
• Gitコマンド一覧｜用途別早見表：ソースコードのバージョニングを支えるGitの基本操作を用途別に確認できます。
• Spring BootとReactを連携する方法（REST API・CORS・JWT認証）：APIバージョニングを設計する土台となる、REST APIの実装手順を解説します。
• Spring BootとFlywayでMongoDBのマイグレーション設定：データベーススキーマのバージョニングを実装する具体例です。
• マイグレーションとは？リプレイス・モダナイゼーションとの違い：スキーマや基盤の版更新を、発注・投資判断の視点から整理します。