データ形式の変換を正気で乗り切る方法

こんな経験ありませんか。データベースのエクスポートはCSVで出てくる。新しいAPIはJSONを要求する。デプロイ設定はYAMLが必要。レガシーシステムはXMLしか受け付けない。そして気がつけば、全部つなぐのは自分の仕事になっている。

データ形式の変換は、実際にやるまでは簡単に見えます。崩壊しない実践的なパイプラインの作り方を解説します。

シナリオ：実際のマイグレーション

旧システムから新システムへユーザーデータを移行するとします。状況はこうです：

• ソース：旧データベースのCSVエクスポート（10,000行、15列）
• APIレイヤー：新システムはREST API経由でJSONを受け付ける
• 設定ファイル：デプロイ設定はYAML
• レガシー連携：パートナーシステムがXMLフィードを要求

4つの形式。1つのデータセット。始めましょう。

ステップ1：CSV → JSON — エクスポートからAPI対応へ

CSVはこんな感じです：

id,name,email,plan,created
1,Alice,alice@example.com,pro,2024-03-15
2,Bob,bob@example.com,free,2024-06-22

JSONに変換すると、APIが消費できる構造化されたデータになります：

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "plan": "pro",
    "created": "2024-03-15"
  }
]

注意点：内部にカンマを含む引用フィールド、nullであるべき空の値が空文字列になるケース、行ごとに異なる日付形式。こうしたバグは「うまくいっている」と思った時に4,738行目で現れます。

ステップ2：JSON → YAML — 設定ファイル用

デプロイにYAML設定が必要です。データ構造は同じで、構文が違うだけです：

users:
  - id: 1
    name: Alice
    email: alice@example.com
    plan: pro
    created: "2024-03-15"

YAMLは設定ファイルの可読性が高いです。Kubernetes、Docker Compose、CI/CDパイプラインが全て使っている理由です。ただし、空白文字に敏感で、1つのインデントミスで深夜2時にデプロイが壊れます。

ステップ3：JSON → XML — レガシーシステム用

2015年のあのパートナーシステムがXMLを要求します。いいえ、API更新はしません。はい、それでもサポートする必要があります。

<users>
  <user>
    <id>1</id>
    <name>Alice</name>
    <email>alice@example.com</email>
  </user>
</users>

変換自体は直感的ですが、XMLには独自の特性があります — 属性vs要素、名前空間の要件、スキーマ検証。XML変換ツールが構造的な変換を処理し、ビジネスロジックはあなたが処理します。

ステップ4：JSONフォーマッターで全てを検証

各ステージでJSONをフォーマットして検証してください。括弧1つ、末尾のカンマ1つ、エスケープされていない引用符1つ — それだけでインポートが静かにレコードを落とすか、完全にクラッシュします。

変換済みデータをAPIに送信する前に、フォーマットして構造を目視確認しましょう。5秒のフォーマットが「なぜ200件のレコードが消えたのか」のデバッグ5時間を節約します。

データマイグレーションでよくある落とし穴

エンコーディング問題：Windows ExcelからのCSVはUTF-8ではなくWindows-1252かもしれません。日本語の顧客名が文字化けします。まずエンコーディングを確認してください。

型変換：CSVは全てを文字列として扱います。CSVの001がJSONで1になります。郵便番号、電話番号、先頭ゼロのあるIDフィールドが主な被害者です。

ネストされたデータ：CSVはフラット、JSONはネスト構造。CSVのaddress_street、address_city、address_zipをJSONのaddressオブジェクトにどうマッピングするか決める必要があります。

Null vs 空値：空のCSVセルはnullか、""か、キー自体を省略すべきか？バグを見つけた時ではなく、始める前に定義してください。

パイプラインパターン

データマイグレーションのワークフロー：

1. エクスポート — ソースシステムから（通常CSVまたはSQLダンプ）
2. 変換 — 作業形式へ（CSV → JSON）
3. 変形 — 構造変更（フィールド名変更、オブジェクトのネスト、型修正）
4. 検証 — 出力確認（フォーマットと検査）
5. 変換 — 対象形式へ（YAMLまたはXML）
6. インポート — 対象システムへ

ツールがステップ2、4、5を処理します。ステップ1、3、6はあなたのコードです。「変換」と「変形」を分離すると管理が楽になります。

---

データマイグレーションは計画書で見えるほど単純ではありません。しかし、各ステップで信頼できる変換ツールがあれば、形式の構文と格闘する代わりに、本当の問題 — ビジネスロジック、エッジケース、データ品質 — に時間を使えます。