コードで語るマニフェスト：自治体APIのスキーマとバージョン戦略を設計する

どうも〜おかむーです！今日は自治体・政府が公開するAPIやダッシュボードの“契約” — 要するにスキーマとバージョニング — について、エンジニア視点でガチに話しますよ〜

• この話、APIの公開方法で自治体データの再利用性と信頼度が決まります
• スキーマ契約（OpenAPI/JSON Schema）とセマンティックバージョン管理が欠かせない
• CIで契約テストを回すだけで開発負担は下がり、市民向けサービスも安定する

結論

自治体・政府のオープンデータは「公開するだけ」では再利用されにくいです。エンジニア的に言うと、APIのスキーマ（契約）を明文化して自動テスト（契約テスト・スキーマ検証）をCIに組み込み、セマンティックバージョニングで後方互換を保証する運用に移すべきです。これがあればダッシュボード（Japan Dashboardや都庁の可視化サービス）や二次利用アプリが安心してビルドできますよね！

レポート本文

現状観察：何が起きてるか

これ見てくださいよ。デジタル庁やGovTech東京がダッシュボード整備や自治体システム標準化を進めている（参考：デジタル庁の地方公共団体ページ、GovTech東京のデータ利活用サービス）けど、公開データの多くは「スキーマが曖昧」だったり、CSV／PDF混在でAPIの仕様がないことがあります。結果、利用者側は都度解析ロジックを作り替えるハメになるんです。

要するに：スキーマがない＝契約がない＝互換性がない、ということです。

なぜスキーマとバージョンが重要か（エンジニア的観点）

• スキーマ（OpenAPI / JSON Schema）があれば自動生成でクライアントやサーバの型が作れる
• セマンティックバージョニング(vMAJOR.MINOR.PATCH)で互換性ポリシーを明示すると破壊的変更を回避できる
• 契約テスト（Consumer-Driven Contract）でAPI提供側と利用側の期待差をCIで捕まえられる

具体例：給与支給データのフィールド名を突然変えたら、予算系ダッシュボードが死ぬ。APIにv1→v2の明示的移行ルールがあれば、クライアントは段階的に対応できる。

技術要素と実践例

1) OpenAPIで契約を書く

openapi: 3.0.3
info:
title: City Services API
version: 1.0.0
paths:
/facilities:
get:
summary: 公共施設一覧
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FacilityList'
components:
schemas:
Facility:
type: object
properties:
id:
type: string
name:
type: string
lat:
type: number
lon:
type: number
required: [id, name]
FacilityList:
type: array
items:
$ref: '#/components/schemas/Facility'

2) JSON Schemaでバリデーション（CIで自動チェック）

# example: jsonschemaでAPIレスポンスを検証
import requests
from jsonschema import validate
spec = load_json_schema('facility_schema.json')
r = requests.get('https://api.city.example.jp/v1/facilities')
validate(instance=r.json(), schema=spec)

3) セマンティックバージョニング運用

• MAJOR: 後方互換を壊す変更（フィールド削除など）
• MINOR: 後方互換を保つ追加（新フィールド追加）
• PATCH: バグ修正

APIは少なくともMAJORの変化時に/v1→/v2のエンドポイントを用意し、移行期間（例：1年）を定義するべき。

4) デプロイとCIの仕組み

• スキーマ差分検出ツールで破壊的変更を検出
• PactやSpring Cloud Contractのような契約テストを導入
• ドキュメントはOpenAPIから自動生成（Swagger UIなど）

政策目標と実績のギャップ（設計で埋める）

デジタル庁は自治体の標準化を進めていますが、現場は多様なシステムと人員制約がある。そこで提案するのは“段階的導入”：

• フェーズ1：OpenAPI最低限テンプレートを配布（必須エンドポイントとメタを定義）
• フェーズ2：CIテンプレート（GitHub Actions等）を自治体向けに配布し、スキーマテストを自動化
• フェーズ3：地域ごとの互換性レポートを自動生成してダッシュボードに表示（外部開発者向けの互換性通知）

これで「公開はしたけど壊れた」事態を減らせます。

実用的改善提案（短期から長期まで）

• 短期（1〜3ヶ月）：OpenAPIテンプレ配布＋サンプルCI（jsonschema検証）
• 中期（3〜12ヶ月）：契約テスト導入、デprecationヘッダの運用ルール化
• 長期（1年〜）：APIカタログ（Japan Dashboard連携）と互換性メトリクスの公開

これらは技術的にはシンプルで、運用ルール化が肝です。エンジニアが1回コードを書けば、以降は自動化で安定性がぐっと上がります！

まとめ

• スキーマ（OpenAPI/JSON Schema）とセマンティックバージョニングは自治体APIの基礎契約
• CIで契約テストを回し、破壊的変更を自動検出するだけで市民サービスの安定性が劇的に改善
• デジタル庁やGovTechの取り組みと組み合わせて、段階的・現場配慮型の導入計画を作ろう

おかむーから一言

テクノロジーで公共をアップデートするには“約束ごと”が必要なんです。仕様をコード化して、みんなが同じ土俵で戦える環境を作りましょう！