Tech Article

公開 2026年3月2日

更新 2026年3月14日

microCMS × visual-json を試してみた

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

Prerequisites

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

Key Points

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

はじめに

前回のjson-render × microCMS の検証記事では、「UI 構成の一部を運用側で触れるようにする」アプローチを試しました。

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

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

登場するツール

visual-json

Vercel Labs が公開している JSON エディタの OSS です（GitHub）。v0.1.0 がリリースされたばかりで、React コンポーネントとして以下の 3 つのビューを提供しています。

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

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

microcms-schema-adapter

今回の検証のために作成した自作変換ライブラリです（GitHub / npm）。

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 等）に対応しています。

何がしたかったか

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

microCMS のスキーマ情報を microcms-schema-adapter で JSON Schema に変換
JSON Schema を visual-json に渡す
visual-json がスキーマに沿った入力フォーム（セレクトボックス、日付ピッカー等）を自動生成
非エンジニアでも 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）

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

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

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）

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

Playground 側で schema を読み込み、JSON を編集
生成した payload を Copy JSON で取得
mcms-cli で validate --json を実行し、.ok == true を確認
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 を起点にした展開先は広いのではないかと感じました。

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