平素よりmicroCMSをご利用いただき、誠にありがとうございます。
この度、今後マネジメントAPIからAPIの作成を行えるようにするにあたり、APIスキーマの出力値を一貫した形式に整理するため、APIスキーマエクスポートおよびマネジメントAPIの一部レスポンスについて仕様変更を行います。
本変更には、空の値の出力形式の調整、初期値に関するキー名の統一、カスタムフィールド等に関する一部キーの変更・削除が含まれます。
APIスキーマエクスポート機能で出力されたJSON、またはマネジメントAPIのレスポンスを独自に解析・利用されている場合は、事前にご確認をお願いいたします。
なお、管理画面上でAPIスキーマを設定・編集するなど、通常の利用においては基本的に影響はありません。
対象機能
以下2つの機能が対象となります。
- APIスキーマエクスポート（管理画面からのJSON形式でのエクスポート）
- マネジメントAPI - API情報取得
※ マネジメントAPIは現在ベータ版として提供している機能です。今回のアップデートは破壊的変更を含みますが、今後の機能改善に向けた仕様整理の一環として、事前に告知した上で変更を実施いたします。
アップデート内容
今回のアップデートでは、APIスキーマの出力値について、以下の変更を行います。
- 空の値の出力形式を一部変更
- 初期値に関するキー名を統一
- カスタムフィールド等に関するキーを変更・追加
- カスタムフィールド内の一部キーを変更・削除
1. 空の値の出力形式を一部変更
一部のフィールド設定において、詳細設定の値が未設定の場合の出力形式を変更します。
これまで、設定内容によっては対象のキー自体が出力されない場合や、空の値の表現が項目ごとに異なる場合がありました。今回の変更では、APIスキーマの出力値をプログラムから扱いやすくするため、以下の方針で空の値の表現を整理します。
- 設定項目として存在する値については、原則としてキーを出力します
- 値が未設定の場合は、値の種類や項目の意味に応じた形式（
null、[]、false、"DEFAULT"など）で出力します
変更後の出力内容の詳細は、変更後のサンプルJSONファイルをご確認ください。
2. 初期値に関するキー名を統一
真偽値フィールドおよびセレクトフィールドの初期値に関するキー名を統一します。
これまで、フィールドの種類に応じて booleanInitialValue（真偽値フィールド）、selectInitialValue（セレクトフィールド） として出力されていたキー名を、initialValue に統一します。
真偽値フィールド
【変更前】
"booleanInitialValue": true【変更後】
"initialValue": trueセレクトフィールド
【変更前】
"selectInitialValue": ["gJOFOB0dnp"] // 内部キーの配列【変更後】
"initialValue": ["gJOFOB0dnp"]3. カスタムフィールド等に関するキーを変更・追加
カスタムフィールド、繰り返しフィールド、コンテンツ参照フィールドなどにおいて、一部キーの変更および追加を行います。
3-1. 【カスタムフィールド／繰り返しフィールド】フィールドを識別するキーを変更
カスタムフィールドおよび繰り返しフィールドにおいて、参照先カスタムフィールドを識別するキーを、作成日時からフィールドIDに変更します。
カスタムフィールドの場合
customFieldCreatedAt（作成日時）から customFieldId（フィールドID）に変更します。
【変更前】
"customFieldCreatedAt": "2026-03-31T02:01:55.61Z"【変更後】
"customFieldId": "foo"繰り返しフィールドの場合
customFieldCreatedAtList（作成日時の配列）から customFieldIds（フィールドIDの配列）に変更します。
【変更前】
"customFieldCreatedAtList": ["2026-03-31T02:01:55.611Z"]【変更後】
"customFieldIds": ["bar"]3-2. 【コンテンツ参照／複数コンテンツ参照／カスタムフィールド】一覧表示項目に関するキーを listViewFieldId に変更
「コンテンツ参照」「複数コンテンツ参照」「カスタムフィールド」の各フィールドにおいて、管理画面の「一覧画面に表示する項目」で指定したフィールドのIDを示すキーを、listViewFieldId に統一します。
- コンテンツ参照／複数コンテンツ参照：
referenceDisplayItem→listViewFieldId - カスタムフィールド：
customFieldDisplayItem→listViewFieldId
【変更後の例】（カスタムフィールドの場合）
{
"fieldId": "author",
"name": "著者",
"kind": "custom",
"customFieldId": "author",
"listViewFieldId": "name"
}補足：APIスキーマエクスポートにおける referencedApiEndpoint の出力
コンテンツ参照／複数コンテンツ参照フィールドにおいて、APIスキーマエクスポートの出力にも、参照先APIのエンドポイント名を示す referencedApiEndpoint が含まれるようになります。
※なお、マネジメントAPIのレスポンスには、すでに referencedApiEndpoint が含まれています。
4. カスタムフィールド内の一部キーを変更・削除
カスタムフィールド本体に関するレスポンスについて、一部キーの変更および削除を行います。
4-1. レイアウトに関するキーを変更
カスタムフィールドの1カラム／2カラムレイアウトを表すキーについて、キー名を position から fieldOrderByColumn に変更します。
また、値についても、内部生成される idValue から、ユーザーが定義する fieldId に変更します。
【変更前】
"position": [["jhbYIfMgLX", "NkeLwyo2x0", "z2zFDhNpS3"]]【変更後】
"fieldOrderByColumn": [["foo", "bar", "test"]]4-2. 一部キーを削除
カスタムフィールドに関するレスポンスから、以下のキーを削除します。
- createdAt
- updatedAt
- idValue
- viewerGroup
これらのキーは、APIスキーマの出力値として不要な情報、または今回のキー変更によって不要となる情報であるため、レスポンスに含まれないよう変更します。
なお、viewerGroup の削除はAPIスキーマエクスポートのみが対象です。マネジメントAPIでは、すでに削除済みです。
影響範囲
本変更は、APIスキーマエクスポート機能で出力されたJSON、またはマネジメントAPIのAPI情報取得のレスポンスを、独自のシステムやツール等で解析・利用している場合に影響する可能性があります。
特に、以下のような処理を行っている場合は、変更後の出力値に合わせた確認・修正が必要となる可能性があります。
- 特定のキー名を参照している処理
- キーの有無をもとに分岐している処理
- 空の値の出力形式を前提にしている処理
一方で、管理画面上で通常どおりAPIスキーマを設定・編集しているのみの場合や、APIスキーマエクスポートおよびマネジメントAPIのAPI情報取得のレスポンスを独自に利用していない場合は、基本的に影響はありません。
なお、APIスキーマインポートについては、変更後の形式でインポートできるよう対応予定です。あわせて、従来の出力形式でのインポートについても、後方互換を担保する方針です。
推奨される対応
以下のようなご利用がある場合は、事前にご確認をお願いいたします。
- APIスキーマエクスポートで出力したJSONを、独自のシステムやツールで読み込んでいる
- マネジメントAPIのAPI情報取得のレスポンスをもとに、APIスキーマを解析・変換している
特に、以下のキーを参照している場合は、変更後の形式に合わせて修正が必要となる可能性があります。
customFieldCreatedAt→customFieldIdcustomFieldCreatedAtList→customFieldIdsposition→fieldOrderByColumnbooleanInitialValue→initialValueselectInitialValue→initialValuecreatedAt/updatedAt/idValue/viewerGroup：削除
また、空の値に関するキーの有無や、null、[]、false などの値を前提にした処理がある場合も、変更後の出力値をご確認ください。
なお、上記に該当するご利用がない場合は、特別な対応は不要です。
変更予定日
2026年7月7日（火）
※ 不具合や想定外の事項があった場合、リリース日は変更となる可能性がございます。
本件に関するお問い合わせ先
本件に関してご不明点がございます場合は、お問い合わせフォームよりご連絡ください。
今後もより使いやすいサービスになるよう改善を続けてまいります。
今後とも、microCMSをご愛顧賜りますようお願い申し上げます。
