---
title: "microCMS × visual-json を試してみた"
canonical_url: "https://y-brew.vercel.app/tech/hbhsps0rng4a"
markdown_url: "https://y-brew.vercel.app/tech/hbhsps0rng4a/markdown"
blocks_url: "https://y-brew.vercel.app/tech/hbhsps0rng4a/blocks"
published: "2026-03-02"
updated: "2026-03-14"
last_reviewed: "-"
tags: []
intent: ["case_study"]
evergreen: true
key_points: ["visual-json の Schema-aware はフォーム自動生成ではなくバリデーション機能", "visual-json × microCMS では TreeView 閲覧、DiffView 差分表示、バリデーション付き編集が可能", "microcms-schema-adapter は microCMS → JSON Schema の変換ライブラリとして汎用的な価値がある", "JSON Schema エコシステム（バリデーション、型生成、フォーム生成、AI 連携）への展開が可能", "海外 CMS（Contentful、Sanity）のスキーマエクスポートに相当する仕組みを非公式ながら実現"]
prerequisites: ["ヘッドレス CMS の運用経験", "JSON / JSON Schema の基本的な理解", "前回記事（json-render × microCMS）の内容があると理解しやすい"]
section_headings: ["はじめに", "登場するツール", "visual-json", "microcms-schema-adapter", "何がしたかったか", "期待と現実のギャップ", "visual-json × microCMS で実際にできること", "1. microCMS のコンテンツ JSON をツリー表示で閲覧・編集", "2. コンテンツの変更前後の差分を可視化", "3. JSON Schema バリデーション付きの編集", "visual-json のデモ（GIF）", "「Schema-aware」がイメージしやすかった具体例", "ネストが深い JSON を扱うときの例", "生 JSON 編集と比べて楽だった点", "この検証での最小フロー（Playground → mcms-cli）", "microcms-schema-adapter を作って見えたこと", "JSON Schema があると何ができるか", "海外ヘッドレス CMS との比較", "次にやってもいいかなと思っていること", "前回記事との関係", "まとめ"]
---

# microCMS × visual-json を試してみた

## TL;DR
Vercel Labs の visual-json と自作の microcms-schema-adapter を使い、microCMS コンテンツの視覚的編集を試みた検証メモ。visual-json の Schema-aware はフォーム自動生成ではなくバリデーション機能だったが、schema-adapter は JSON Schema エコシステムへの橋として想定以上の汎用性があった。

## Retrieval Notes
- Prefer this Markdown URL when you need the full article body in a compact text format.
- Prefer the block JSON at https://y-brew.vercel.app/tech/hbhsps0rng4a/blocks when you need article structure instead of prose.
- Cite the canonical HTML page at https://y-brew.vercel.app/tech/hbhsps0rng4a when linking to the source.
- Treat updated and last_reviewed as freshness signals.

## Key Points
- visual-json の Schema-aware はフォーム自動生成ではなくバリデーション機能
- visual-json × microCMS では TreeView 閲覧、DiffView 差分表示、バリデーション付き編集が可能
- microcms-schema-adapter は microCMS → JSON Schema の変換ライブラリとして汎用的な価値がある
- JSON Schema エコシステム（バリデーション、型生成、フォーム生成、AI 連携）への展開が可能
- 海外 CMS（Contentful、Sanity）のスキーマエクスポートに相当する仕組みを非公式ながら実現

## Prerequisites
- ヘッドレス CMS の運用経験
- JSON / JSON Schema の基本的な理解
- 前回記事（json-render × microCMS）の内容があると理解しやすい

## Section Guide
- はじめに
- 登場するツール
  - visual-json
  - microcms-schema-adapter
- 何がしたかったか
- 期待と現実のギャップ
- visual-json × microCMS で実際にできること
  - 1. microCMS のコンテンツ JSON をツリー表示で閲覧・編集
  - 2. コンテンツの変更前後の差分を可視化
  - 3. JSON Schema バリデーション付きの編集
- visual-json のデモ（GIF）
- 「Schema-aware」がイメージしやすかった具体例
  - ネストが深い JSON を扱うときの例
  - 生 JSON 編集と比べて楽だった点
  - この検証での最小フロー（Playground → mcms-cli）
- microcms-schema-adapter を作って見えたこと
  - JSON Schema があると何ができるか
  - 海外ヘッドレス CMS との比較
- 次にやってもいいかなと思っていること
- 前回記事との関係
- まとめ

## Article

## はじめに

前回の[json-render × microCMS の検証記事](https://y-brew.vercel.app/tech/daisxqeaqyfa)では、「UI 構成の一部を運用側で触れるようにする」アプローチを試しました。

今回は同じ Vercel Labs のツールである `visual-json` と、新たに作成した変換ライブラリ `microcms-schema-adapter` を組み合わせて、microCMS のコンテンツデータを視覚的に扱えるかを検証したメモです。

結論から言うと、visual-json に当初期待していた「スキーマ駆動のフォーム自動生成」は実現できませんでしたが、調査の過程で見えてきたことが多かったので整理します。

## 登場するツール

### visual-json

Vercel Labs が公開している JSON エディタの OSS です（[GitHub](https://github.com/vercel-labs/visual-json)）。v0.1.0 がリリースされたばかりで、React コンポーネントとして以下の 3 つのビューを提供しています。

-   **TreeView**: JSON データをツリー構造で表示・編集する
-   **FormView**: JSON データをフォーム形式で表示・編集する
-   **DiffView**: 2 つの JSON の差分を表示する

「Schema-aware」を謳っており、JSON Schema を渡すとバリデーション（型チェック・必須チェック）が効きます。

### microcms-schema-adapter

今回の検証のために作成した自作変換ライブラリです（[GitHub](https://github.com/mrmtsu/microcms-schema-adapter) / [npm](https://www.npmjs.com/package/@mrmtsu/microcms-schema-adapter)）。

microCMS の独自スキーマ形式を JSON Schema (draft-07) に変換します。ゼロランタイム依存で、以下の 2 つの API を提供しています。

-   `toJsonSchema(schema, options?)`: 単一の API スキーマを JSON Schema に変換
-   `bundleToJsonSchema(bundle)`: `microcms schema pull` の出力（バンドル）を一括変換

microCMS のフィールド型（text, richEditorV2, select, number, date, boolean, media, relation, repeater, custom 等）に対応しています。

## 何がしたかったか

当初のイメージは以下でした。

1.  microCMS のスキーマ情報を `microcms-schema-adapter` で JSON Schema に変換
2.  JSON Schema を `visual-json` に渡す
3.  visual-json がスキーマに沿った入力フォーム（セレクトボックス、日付ピッカー等）を自動生成
4.  非エンジニアでも microCMS コンテンツを構造的に編集できる UI が手に入る

要するに「microCMS の管理画面を補完する軽量な編集 UI」を想定していました。

## 期待と現実のギャップ

調べてみると、visual-json の「Schema-aware」は想定と異なるものでした。

期待していたこと

実際にできること

microCMS スキーマから「タイトル入力欄」「カテゴリドロップダウン」「日付ピッカー」が自動生成される

JSON のキー・値をツリーまたはフォームで汎用的に編集できる

フィールド型に応じた専用 UI が出る

型チェック・必須チェックのバリデーションが効く

非エンジニアが microCMS 管理画面の代わりに使える

JSON の構造を理解している人向けのエディタ

visual-json は「スキーマ駆動のフォーム生成ツール」ではなく、「バリデーション付きの汎用 JSON エディタ」という位置づけでした。

## visual-json × microCMS で実際にできること

当初の期待とは違いましたが、以下は実現可能です。

### 1\. microCMS のコンテンツ JSON をツリー表示で閲覧・編集

microCMS の Content API で取得した JSON データを TreeView に渡せば、ネストが深い構造でもツリーで展開しながら閲覧・編集できます。リッチエディタフィールドの HTML 文字列や、リレーション先の ID 配列など、管理画面では見えにくい生データの構造を確認するのに向いています。

### 2\. コンテンツの変更前後の差分を可視化

DiffView は 2 つの JSON を並べて差分を表示できます。mcms-cli の `content diff` コマンドの出力と組み合わせれば、公開版と下書き版の差分を視覚的に確認できます。コードレビューの diff に近い体験です。

### 3\. JSON Schema バリデーション付きの編集

`microcms-schema-adapter` で変換した JSON Schema を visual-json に渡すことで、編集中に「このフィールドは必須です」「ここは string のみです」といったバリデーションが効きます。生 JSON を直接編集するよりは安全です。

## visual-json のデモ（GIF）

「どこで何を見ているか」が分かるように、各ステップに注釈を重ねています。

1.  プリセット選択（microCMS スキーマ投入）
2.  Convert 実行（JSON Schema 変換）
3.  TreeView 表示（構造の閲覧・編集）
4.  Search でフィールド特定（深い JSON でも追いやすい）
5.  Copy JSON（payload として持ち出し）

![visual-json demo gif](https://images.microcms-assets.io/assets/60dd058c671d490e94ef51fbf40d022c/6da0af1d4e2c4881ac0b3a6afc1046b2/visual-json-demo-annotated.gif)

[GIF を別タブで開く](https://images.microcms-assets.io/assets/60dd058c671d490e94ef51fbf40d022c/6da0af1d4e2c4881ac0b3a6afc1046b2/visual-json-demo-annotated.gif)

## 「Schema-aware」がイメージしやすかった具体例

「Schema-aware」が何を指しているかは、個人的に理解が追いつかなかったのですが、今回の検証を経て、**フィールドごとの専用UIを自動生成する**というより、**JSON を編集するときに、スキーマを前提に型や必須項目のチェックが効く**という理解になりました。

### ネストが深い JSON を扱うときの例

たとえば、以下のように入れ子になった payload を直接編集すると、構造を見失いやすくなります。

```
{
  "title": "Schema-aware demo",
  "seo": {
    "og": {
      "images": [
        { "url": "https://example.com/og.png", "alt": "OG image" }
      ]
    }
  },
  "blocks": [
    {
      "type": "cta",
      "cta": {
        "label": "Read more",
        "href": "/tech/sample"
      }
    }
  ]
}
```

こうしたデータを visual-json で開くと、ツリー展開と検索で「いまどこを編集しているか」を追いやすくなります。自分の手元では、`blocks[0].cta.label` のような深い位置でも、構造を確認しながら編集できるのはかなり助かりました。

### 生 JSON 編集と比べて楽だった点

生 JSON を直接編集した場合

Schema-aware エディタで編集した場合

キー typo や型ミス（string/number）に気づきにくい

型チェック・必須チェックで、編集時点で気づきやすい

深いネストで現在地を見失いやすい

TreeView + Search で辿りやすい

構造の把握に時間がかかる

階層を展開しながら確認できるので修正点を見つけやすい

### この検証での最小フロー（Playground → mcms-cli）

今回のデモは、以下の手順で確認しました。

1.  Playground 側で schema を読み込み、JSON を編集
2.  生成した payload を `Copy JSON` で取得
3.  `mcms-cli` で `validate --json` を実行し、`.ok == true` を確認
4.  `content create --dry-run --json` を実行し、書き込み前の検証結果を確認

```
microcms validate notes --file payload.json --json
microcms content create notes --file payload.json --dry-run --json
```

この流れだと、UI 側は「入力しやすさ」、CLI 側は「実行の安全性」を担当する形になります。個人的には、この分離が運用時の安心感につながる感触がありました。

## microcms-schema-adapter を作って見えたこと

visual-json との連携は限定的でしたが、`microcms-schema-adapter` 自体の汎用的な価値はありそうではありました。

このライブラリが作ったのは「microCMS 独自スキーマ → JSON Schema」への橋です。JSON Schema は業界標準なので、その先の接続先は visual-json に限りません。

### JSON Schema があると何ができるか

以下のようなツール・用途に展開できるのかと思いました。

-   **バリデーション**: Ajv や Zod と連携して、microCMS に投入する前にコンテンツの整合性を検証
-   **TypeScript 型生成**: json-schema-to-typescript で microCMS のコンテンツ型定義を自動生成（Contentful の cf-content-types-generator や Sanity の TypeGen に相当）
-   **スキーマ駆動フォーム生成**: react-jsonschema-form や JSON Forms は JSON Schema からセレクトボックスや日付ピッカーを含む入力フォームを実際に自動生成できる。visual-json ではできなかったことが、これらのライブラリでは可能
-   **AI へのスキーマ提供**: JSON Schema という標準形式で AI にスキーマを渡すことで、microCMS 独自形式をそのまま渡すより正確なコンテンツ生成が期待できる（想像）
-   **ドキュメント自動生成**: JSON Schema ベースの doc generator で API フィールド定義を自動生成

### 海外ヘッドレス CMS との比較

主要な海外 CMS はスキーマの外部エクスポートが充実しています。

CMS

スキーマエクスポート方法

Contentful

`contentful space export` で contentTypes を含む JSON エクスポート。サードパーティの型生成エコシステムが成熟

Sanity

`sanity schema extract` で JSON エクスポート。公式 TypeGen あり。Schema as Code（JS/TS 定義）

Contentstack

Content Type の JSON Schema エクスポートに対応

microCMS は公式にはこうしたスキーマエクスポートの仕組みを持っていませんが、mcms-cli の `schema pull` と `microcms-schema-adapter` を組み合わせることで、非公式ながら同等のパイプラインが実現できる状態になりました。

## 次にやってもいいかなと思っていること

今回の検証を踏まえて、以下の方向で進めようと考えています。

-   **Content Playground**: visual-json ではなく react-jsonschema-form 等を使い、microCMS スキーマからフォームを自動生成するデモアプリを作る
-   **agent-browser 連携デモ**: mcms-cli × microcms-schema-adapter × agent-browser で「AI がスキーマを読んでコンテンツを生成し、フロントエンドで検証して公開する」自律フローを試す

## 前回記事との関係

前回の json-render × microCMS の検証では「UI 構成の見せ方を運用側で変えやすくする」話でした。今回は「コンテンツデータの構造を外部ツールと繋ぎやすくする」話です。

json-render が「表示層」の柔軟性を高めるのに対し、schema-adapter は「データ層」の相互運用性を高める方向。同じ microCMS × Vercel ツール群でも、扱っているレイヤーが異なります。

## まとめ

visual-json × microCMS は、当初期待していた「スキーマ駆動のフォーム自動生成」には至りませんでした。visual-json の「Schema-aware」はバリデーション機能であり、フィールド型に応じた UI の自動生成ではありません。

一方で、検証の過程で作成した microcms-schema-adapter は、microCMS の独自スキーマを JSON Schema エコシステム全体に繋ぐ橋として想定以上の汎用性がありました。バリデーション、型生成、フォーム自動生成、AI へのスキーマ提供など、JSON Schema を起点にした展開先は広いのではないかと感じました。

「やりたかったことと違った」という検証結果ですが、その過程で作ったものの方が価値があったのかなとも思いました。