CodexPluginStats
← Files microCMSARCHIVED FILE

skills/microcms-guide/references/content-modeling.md

18 KB · Oct 3, 2026 · 06:35 UTC

↓ Download file

# microCMS コンテンツモデリング

最終確認: 2026-09-08

仕様の根拠は末尾の公式情報を参照する。設計上の推奨・コード例は本Skillの提案であり、唯一の公式推奨構成を意味しない。

## 目次

- [このリファレンスの役割](#このリファレンスの役割)
- [設計の基本原則](#設計の基本原則)
- [リスト形式とオブジェクト形式](#リスト形式とオブジェクト形式)
- [APIを分ける基準](#apiを分ける基準)
- [コンテンツ参照を使う](#コンテンツ参照を使う)
- [カテゴリ・タグ・著者の設計](#カテゴリタグ著者の設計)
- [カスタムフィールドを使う](#カスタムフィールドを使う)
- [繰り返しフィールドを使う](#繰り返しフィールドを使う)
- [参照の深さとレスポンス](#参照の深さとレスポンス)
- [スキーマ変更に強い設計](#スキーマ変更に強い設計)
- [典型パターン](#典型パターン)
- [避けたい設計](#避けたい設計)
- [提案時のチェックリスト](#提案時のチェックリスト)
- [表示用の日時を選ぶ](#表示用の日時を選ぶ)
- [公式情報](#公式情報)

## このリファレンスの役割

microCMSのAPIスキーマを、フロントエンド実装だけでなく編集運用・再利用性・将来の変更も考慮して設計する。

目的は「フィールド数を最小化すること」ではない。編集者にとって理解しやすく、フロントエンドから安定して利用でき、必要以上に複雑でない構造を作る。

## 設計の基本原則

### 1. 管理したい情報の意味から設計する

画面のDOM構造や現在のReactコンポーネントを、そのままAPIスキーマへ写さない。

例:

- `leftColumnText` / `rightColumnText` のようにレイアウトへ強く依存する命名より、`summary` / `body` のようにコンテンツの意味を表すフィールドを優先する。
- ただしLPのように編集者がセクション単位のレイアウトを明示的に管理することが目的なら、カスタムフィールドや繰り返しフィールドで表示ブロックを表現してよい。

### 2. 編集単位と再利用単位を合わせる

別のコンテンツから繰り返し参照される情報は、独立したAPIにする価値がある。

例:

- 著者
- カテゴリ
- 商品ブランド
- 店舗

一方、一つの記事の中でしか意味を持たない短い補足情報をすべて別APIへ分割すると、編集作業と参照構造が過剰に複雑になる。

### 3. 将来の可能性だけで過度に抽象化しない

「いつか使うかもしれない」という理由だけで細かくAPIを分割しない。現在の編集要件と近い将来の明確な要件を満たす最小限の構成を優先する。

## リスト形式とオブジェクト形式

### リスト形式

同種のコンテンツを複数登録する場合に使う。

候補:

- 記事
- お知らせ
- 商品
- 事例
- FAQ
- 著者
- カテゴリ
- タグ

### オブジェクト形式

コンテンツが1件だけ存在する場合に使う。

候補:

- サイト共通設定
- 会社概要
- トップページ設定
- グローバルナビゲーション設定

「1件しか登録しないリスト形式」を常に否定する必要はないが、複数件にする予定がなく一覧・詳細の概念もない場合はオブジェクト形式を優先する。

## APIを分ける基準

次のいずれかが強く当てはまる場合、別APIへの分離を検討する。

- 複数のコンテンツから共通して参照する。
- 独立した編集権限・運用・更新頻度を持つ。
- 一覧ページや詳細ページなど、そのコンテンツ自体が独立した表示単位になる。
- 同じ情報を複数箇所へ重複入力したくない。

逆に、以下だけを理由に分離しない。

- JSONをきれいに見せたい。
- フロントエンドのコンポーネントが別ファイルだから。
- 将来再利用する可能性がゼロではないから。

## コンテンツ参照を使う

別APIで管理するコンテンツを1件紐付ける場合は「コンテンツ参照」を使う。

例:

```text
articles
├─ title
├─ body
├─ category -> categories
└─ author   -> authors
```

複数件を紐付ける場合は「複数コンテンツ参照」を使う。

例:

```text
articles
└─ tags -> tags[]
```

参照は、情報の共通化と編集の一元化に有効である。一方で、参照を深く連鎖させるほど取得・型定義・変更影響が複雑になるため、必要な関係だけを持たせる。

## カテゴリ・タグ・著者の設計

### カテゴリ

カテゴリ名以外の情報を持つ可能性、カテゴリ一覧ページを作る可能性、複数記事で共通利用する可能性があるため、一般的には別のリスト形式API + コンテンツ参照が扱いやすい。

```text
categories
├─ id
├─ name
└─ description (必要なら)
```

記事がカテゴリを1つだけ持つなら「コンテンツ参照」、複数カテゴリを許可するなら「複数コンテンツ参照」を使う。

### タグ

複数の記事から共通利用し、タグ一覧・タグ別ページなどを作るなら、別のリスト形式API + 複数コンテンツ参照を検討する。

固定の候補から選ぶだけなら、複数選択を有効にしたセレクトフィールドを検討する。自由入力を繰り返すなら、テキストフィールドを持つカスタムフィールドを繰り返しで使う方法があるが、返却値は `string[]` ではなくオブジェクトの配列になる。独立した管理・参照が必要ならAPI化を優先する。

### 著者

名前、アイコン、プロフィール、SNS URLなどを複数記事で共通利用するなら、著者APIとして分離する。

```text
authors
├─ name
├─ image
├─ description
├─ xUrl
└─ githubUrl
```

著者情報を記事ごとに直接入力すると、プロフィール変更時に複数記事を更新する必要が生じるため、再利用するなら参照にする。

## カスタムフィールドを使う

複数のフィールドを意味のある一つのブロックとしてまとめたい場合にカスタムフィールドを使う。

例:

```text
CTA
├─ title
├─ description
├─ link
└─ image
```

適するケース:

- 「画像 + テキスト」のような再利用可能な編集ブロック
- CTA
- リンクカード
- 料金プランの1要素

注意:

- カスタムフィールドの中に、さらにカスタムフィールドを直接ネストすることはできない。
- カスタムフィールドはAPIごとに設定する。APIを横断して同一のカスタムフィールド定義を共有する前提では設計しない。

## 繰り返しフィールドを使う

複数種類のカスタムフィールドを、編集者が好きな順序で繰り返し追加する場合に使う。

典型例はLPや柔軟な本文セクション。

```text
sections[]
├─ fieldId: heading
├─ fieldId: imageText
├─ fieldId: quote
└─ ...
```

繰り返しフィールドを使うには、事前にカスタムフィールドを定義する。

適するケース:

- ページビルダー的な編集
- 記事本文内の複数種類のブロック
- セクション順を編集者が変更したい

避けたいケース:

- すべてのページが同じ固定構造なのに、自由度だけを理由に繰り返しへする。
- フロントエンド側で多数の `fieldId` 分岐が必要になり、編集可能な組み合わせも整理されていない。

自由度と実装・運用コストの両方を説明する。

### カスタムフィールドの構造を複雑にしすぎない

公式ドキュメントにフィールド数・カスタムフィールド数の一律の制限値がなくても、任意の規模・構造での正常動作が保証されるわけではない。[制限事項／注意事項](https://document.microcms.io/manual/limitations)を確認し、繰り返しで利用するカスタムフィールドの設計をAPI全体で見直す。

特に、各カスタムフィールドの項目が多い、似た構造のカスタムフィールドが多数ある、繰り返しを介した入れ子が複雑な場合は、スキーマの複雑さを減らせないか検討する。繰り返し要素の登録件数と、定義するフィールドの種類・構造は別の観点で確認する。要素数を減らすだけでスキーマの問題が解決するとは判断しない。

設計時の判断基準:

- 見た目だけが異なるブロックを別々のカスタムフィールドへ複製しない。同じ意味・構造のものは、共通の定義と必要最小限の表示バリエーションで表せるか検討する。
- 一方、全種類の項目を詰め込んだ巨大な汎用ブロックにも統合しない。ブロックごとの責務を明確にし、使わない任意項目や将来用の予備項目を増やさない。
- 編集者が管理する必要のない余白・色・配置等はフロントエンド側で管理する。本文としてまとまる文章は、要件を満たせるならリッチエディタを使い、段落ごとの細かなフィールド化を避ける。
- 再利用する情報や独立して編集する大きな情報群は別API＋コンテンツ参照を候補にする。API数のプラン上限、編集時の画面移動、取得時の参照深度も評価し、分割だけで問題が必ず解消するとは約束しない。

例として、構造が同じ `imageTextLeft` / `imageTextRight` は `imageText` と配置の選択肢で表せる。一方、料金表と著者紹介のように意味も必要項目も異なるものを、項目数の多い単一ブロックに押し込まない。これは設計上の提案であり、内部マッピング数の削減量を保証するものではない。

大規模なページビルダーを実装する前に、想定するカスタムフィールドの種類・構造を含むスキーマと代表コンテンツを検証環境で試す。スキーマ保存、コンテンツの保存・公開、必要なAPI取得まで確認する。少ないフィールドだけの試作で通ったことを、本番規模の検証の代わりにしない。

### スキーマのバリデーションエラーが出た場合

エラー全文と発生操作を確認し、スキーマ構造の制約、コンテンツ容量、WRITE APIのリクエストサイズを切り分ける。GETの `fields` / `depth` の調整は取得レスポンスの最適化であり、保存対象のスキーマ定義を減らす対策ではない。

変更前後のスキーマを比較し、追加したフィールド・カスタムフィールド・繰り返しの構造を絞って調べる。既存コンテンツが使う定義を、エラー回避だけを目的に削除しない。繰り返しで使っているカスタムフィールドの削除はAPIレスポンスに影響するため、移行と表示への影響も確認する。

内部の検索基盤・マッピング数の上限や計算式は、公開情報や個別のサポート回答で確認できた範囲だけで説明する。特定のエンジンの一般的なデフォルト値をmicroCMSの上限として案内したり、根拠なく「何フィールド以下なら安全」と断定したりしない。構造の見直しで解消しない場合は、エラーと再現に必要なスキーマを整理してmicroCMSサポートへ相談する。

## 参照の深さとレスポンス

コンテンツ参照の取得では `depth` を使って参照先をどこまで展開するか指定できる。microCMSの `depth` は `0` から `3` までで、デフォルトは `1`。

参照を多段化する場合は、次の点を考慮する。

- 必要な情報がデフォルトの深さで取得できるか。
- `depth` を増やした結果、レスポンスが大きくなりすぎないか。
- 参照をたどる設計そのものが過度に複雑になっていないか。
- `fields` で必要なフィールドだけに絞れるか。

「取得できる最大深度まで使う」のではなく、必要最低限の `depth` を選ぶ。

## スキーマ変更に強い設計

本番運用後のスキーマ変更は、既存コンテンツとフロントエンドの両方へ影響する。

そのため、変更時は次の順序を基本とする。

1. 変更対象のフィールドを利用しているコンテンツ・コードを確認する。
2. 互換性を保ったまま新しいフィールドを追加できるか検討する。
3. 必要なら既存データを移行する。
4. フロントエンドを新フィールドへ切り替える。
5. 利用されなくなった旧フィールドを最後に整理する。

APIレスポンスの破壊的変更を伴う削除・名称変更などを、管理画面だけを見て即座に行わない。

スキーマ変更は即時反映される。変更前のスキーマをエクスポートし、利用可能なら複数環境で検証する。公式ヘルプでは、既存APIのスキーマをファイルのインポートで上書き・ロールバックする方法は提供されていないと案内されている。エクスポートを自動復元手段とはみなさず、実際の復旧手順も用意する。複数環境の利用条件・本番反映方法は最新仕様を確認する。[公式ヘルプ：運用中のスキーマ変更](https://help.microcms.io/ja/knowledge/change-api-schema-in-operation)

## 典型パターン

### ブログ

```text
articles (list)
├─ title
├─ body
├─ eyecatch
├─ category -> categories
├─ tags -> tags[]
└─ author -> authors

categories (list)
└─ name

tags (list)
└─ name

authors (list)
├─ name
├─ image
├─ description
├─ xUrl
└─ githubUrl
```

記事URLのslugをコンテンツIDでまかなえる要件なら、専用slugフィールドを増やさずコンテンツIDを利用する選択肢もある。

### コーポレートサイト

```text
news (list)
case-studies (list)
members (list)
site-settings (object)
company (object)
```

固定ページをすべて1つの巨大なオブジェクトAPIへ詰め込むか、ページごとに分けるかは、編集権限・更新頻度・担当者・データの独立性で判断する。

### LP / 柔軟なページ

```text
pages (list)
├─ title
├─ seo
└─ sections[] (repeat)
    ├─ hero
    ├─ text
    ├─ imageText
    └─ cta
```

自由度が必要な場合だけ採用する。固定レイアウトなら通常フィールドの方が編集者にも実装者にも分かりやすい。

## 避けたい設計

- 画面ごとに同じカテゴリ名・著者名を重複入力する。
- 1件しか存在しない設定を、理由なくリスト形式で管理する。
- フロントエンドの一時的なレイアウト都合だけでフィールドを命名する。
- 参照を深く連鎖させ、取得のために常に最大 `depth` を要求する。
- 柔軟性を理由にすべてを繰り返しフィールドへする。
- APIを細分化しすぎて編集者が複数画面を行き来しないと1ページを更新できない。
- 既存コンテンツへの影響を確認せず、フィールド削除などの破壊的変更を行う。

## 提案時のチェックリスト

コンテンツモデルを提案する前に、少なくとも以下を確認する。

- そのコンテンツは1件か複数件か。
- 一覧・詳細ページが必要か。
- 他コンテンツから再利用されるか。
- カテゴリやタグを独立して管理・表示するか。
- 編集者がレイアウト順を変更する必要があるか。
- 参照先の情報をどこまで取得する必要があるか。
- APIレスポンスが大きくなりすぎないか。
- 繰り返しで使うカスタムフィールドの種類・項目数・入れ子が過剰でないか。
- 複雑な構造を提案する場合、想定スキーマと代表コンテンツで保存・公開・取得まで検証できているか。
- 既存の編集運用を不必要に複雑化しないか。
- 将来要件ではなく現在の具体的な要件から設計しているか。

ユーザー要件が十分に分かっている場合は、不要な追加質問を挟まず、推奨スキーマとその理由を具体的に提示する。

## 表示用の日時を選ぶ

公開日は `publishedAt`、公開内容の更新日は `revisedAt` を基本にする。`updatedAt` は下書き保存でも変わるため、公開ページの日付や並び順へ使うと編集途中の操作が反映される。`createdAt` は作成日時であり公開日ではない。任意の編集上の日付が必要なら独自の日時フィールドを設ける。[公式ヘルプ：日時の使い分け](https://help.microcms.io/ja/knowledge/how-to-setup-date)

APIの日時はUTCのISO 8601形式。表示時に対象タイムゾーンへ変換し、日付範囲の `filters` もUTCで組み立てる。JSTの日付境界をUTCの同じ日付の0時に置き換えない。[公式ヘルプ：UTCの扱い](https://help.microcms.io/ja/knowledge/specification-of-utc-time)

## 公式情報

- [APIの作成・管理](https://document.microcms.io/manual/create-api)
- [カスタムフィールド](https://document.microcms.io/manual/custom-field)
- [繰り返しフィールド](https://document.microcms.io/manual/repeat-field)
- [セレクトフィールド](https://document.microcms.io/manual/select-field)
- [レスポンス形式と空値](https://document.microcms.io/content-api/get-api-field-responses)
- [depth・fields・filters](https://document.microcms.io/content-api/get-list-contents)
- [制限事項／注意事項](https://document.microcms.io/manual/limitations)

SHA-256: 5d5007648417a5fdef39a58559fac2b1660c13336adbbd1ba368d157ddf5d893