フィールドタイプリファレンス

EmDash はコンテンツスキーマを定義するための 17 のフィールドタイプをサポートします。各タイプは SQLite の列タイプに対応し、適切な管理 UI を提供します。

概要

次の表は各フィールドタイプとその SQLite 列を示します。

Type	SQLite Column	Description
`string`	TEXT	短いテキスト入力
`text`	TEXT	複数行テキスト
`url`	TEXT	URL 値
`number`	REAL	小数
`integer`	INTEGER	整数
`boolean`	INTEGER	真/偽
`datetime`	TEXT	日時
`select`	TEXT	オプションからの単一選択
`multiSelect`	JSON	複数選択
`portableText`	JSON	リッチテキストコンテンツ
`image`	TEXT	画像参照
`file`	TEXT	ファイル参照
`reference`	none	別コレクションのエントリへのリンク
`json`	JSON	任意の JSON データ
`slug`	TEXT	URL セーフな識別子
`repeater`	JSON	繰り返しフィールドグループ
`blocks`	JSON	型付きページ構成

テキストタイプ

`string`

短い 1 行テキスト。タイトル、名前、短い値に使います。

{
  slug: "title",
  label: "Title",
  type: "string",
  required: true,
  validation: {
    minLength: 1,
    maxLength: 200,
  },
}

検証オプション:

minLength — 最小文字数
maxLength — 最大文字数
pattern — 値が一致しなければならない正規表現

エディタは入力を maxLength で制限し、長さルールに対するライブ文字数を表示します。

ウィジェットオプション:

特になし

`text`

複数行のプレーンテキスト。説明、抜粋、長いプレーンテキストに使います。

{
  slug: "excerpt",
  label: "Excerpt",
  type: "text",
  options: {
    rows: 3,
  },
}

検証オプション:

minLength — 最小文字数
maxLength — 最大文字数
pattern — 値が一致しなければならない正規表現

エディタは入力を maxLength で制限し、長さルールに対するライブ文字数を表示します。

ウィジェットオプション:

rows — テキストエリアの行数（デフォルト: 3）

`url`

Web アドレス。コンテンツ API は有効な URL でない値を拒否します。

{
  slug: "website",
  label: "Website",
  type: "url",
  required: true,
}

URL フィールドはテキストとして保存されます。値が /about のような相対パスになり得る場合は、代わりに string フィールドを使ってください。相対パスは url フィールドの有効な値ではありません。

`slug`

スラッグ風の値を保持するためのテキスト。このカスタムフィールドタイプは値を生成したりサニタイズしたりしません。

{
  slug: "legacy_slug",
  label: "Legacy Slug",
  type: "slug",
  required: true,
  unique: true,
}

すべてのコンテンツエントリには、公開 URL 用に EmDash が別途管理する予約済みシステム slug が既にあります。コンテンツモデルが別の保存済みスラッグ風の値を必要とする場合にのみ、カスタム slug フィールドを使ってください。

数値タイプ

`number`

小数。価格、評価、測定値に使います。

{
  slug: "price",
  label: "Price",
  type: "number",
  required: true,
  validation: {
    min: 0,
    max: 999999.99,
  },
}

検証オプション:

min — 最小値
max — 最大値

エディタは数値入力に min と max を設定し、その下に許可範囲を表示します。

SQLite REAL（64 ビット浮動小数点）として保存されます。

`integer`

整数。数量、カウント、順序値に使います。

{
  slug: "quantity",
  label: "Quantity",
  type: "integer",
  defaultValue: 1,
  validation: {
    min: 0,
    max: 1000,
  },
}

検証オプション:

min — 最小値
max — 最大値

エディタは数値入力に min と max を設定し、その下に許可範囲を表示します。

SQLite INTEGER として保存されます。

`boolean`

真または偽。トグルやフラグに使います。

{
  slug: "featured",
  label: "Featured",
  type: "boolean",
  defaultValue: false,
}

SQLite INTEGER（0 または 1）として保存されます。

日時

`datetime`

ある瞬間の時刻。API、MCP、CLI の書き込みには Z または明示的な UTC オフセットが必要です。管理画面は Settings → General で設定されたタイムゾーンで日時ピッカーを解釈します。

{
  slug: "publishedAt",
  label: "Published At",
  type: "datetime",
}

保存形式: 2025-01-24T12:00:00.000Z

EmDash は受け付けた入力を、保存前に 3 桁のミリ秒付きの UTC に変換します。たとえば 2025-01-24T21:00:00+09:00 は 2025-01-24T12:00:00.000Z として保存されます。値が瞬間ではなくカレンダー日付やローカルの壁時計時刻である場合は、代わりに string フィールドを使ってください。

選択タイプ

`select`

事前定義されたオプションからの単一選択。

{
  slug: "status",
  label: "Status",
  type: "select",
  required: true,
  defaultValue: "draft",
  validation: {
    options: ["draft", "published", "archived"],
  },
}

検証オプション:

options — 許可される値の任意配列。事前定義の選択肢を提示し他の文字列を拒否するために指定します。指定しない場合、検証は任意の文字列を受け付けます。

選択された値を含む TEXT として保存されます。

`multiSelect`

事前定義されたオプションからの複数選択。

{
  slug: "tags",
  label: "Tags",
  type: "multiSelect",
  validation: {
    options: ["news", "tutorial", "review", "opinion"],
  },
}

検証オプション:

options — 許可される値の任意配列。事前定義の選択肢を提示し他の文字列を拒否するために指定します。指定しない場合、検証は任意の文字列配列を受け付けます。

JSON 配列として保存: ["news", "tutorial"]

リッチコンテンツ

`portableText`

Portable Text 形式のリッチテキストコンテンツ。見出し、リスト、リンク、画像、カスタムブロックをサポートします。

{
  slug: "content",
  label: "Content",
  type: "portableText",
  required: true,
}

値は Portable Text ブロックの JSON 配列として保存されます。例:

[
	{
		"_type": "block",
		"style": "normal",
		"children": [{ "_type": "span", "text": "Hello world" }]
	}
]

プラグインはカスタムブロックタイプ（埋め込み、ウィジェットなど）をエディタに追加できます。これらはスラッシュコマンドメニューに表示されます。公開サイトで保存されたブロックをレンダリングするには、ネイティブプラグインまたはコンパニオンパッケージの Astro コンポーネントが必要です。Portable Text レンダリングコンポーネントを参照してください。

メディアタイプ

`image`

アップロードされた画像への参照。寸法や代替テキストなどのメタデータを含みます。

{
  slug: "featuredImage",
  label: "Featured Image",
  type: "image",
  validation: {
    allowedMimeTypes: ["image/jpeg", "image/png"],
  },
  options: {
    darkVariant: true,
  },
}

ウィジェットオプション:

darkVariant — ダークカラースキームで表示する画像用の 2 つ目のスロットをエディタに提供します（デフォルト: false）。Dark Modeを参照してください。

検証オプション:

allowedMimeTypes — 選択されたメディアで受け付ける正確な MIME タイプの空でないリスト

値はメディア参照とそのメタデータを持つオブジェクトとして保存されます:

{
	"id": "01HXK5MZSN...",
	"src": "/_emdash/api/media/file/01HXK5MZSN...",
	"alt": "Description",
	"width": 1920,
	"height": 1080,
	"provider": "local",
	"meta": {
		"storageKey": "01HXK5MZSN....jpg"
	}
}

darkVariant が有効な場合、値は同じ形状で darkVariant の下にダーク側の対応を持てます:

{
	"id": "01HXK5MZSN...",
	"alt": "Architecture diagram",
	"width": 1920,
	"height": 1080,
	"darkVariant": {
		"id": "01HXK5N2QT...",
		"width": 1920,
		"height": 1080
	}
}

`file`

ドキュメントや PDF など、アップロードされたファイルへの参照。

{
  slug: "document",
  label: "Document",
  type: "file",
  validation: {
    allowedMimeTypes: ["application/pdf"],
  },
}

検証オプション:

allowedMimeTypes — 選択されたメディアで受け付ける正確な MIME タイプの空でないリスト

値はキャッシュされたメタデータを持つプロバイダ参照として保存されます:

{
	"id": "01HXK5MZSN...",
	"provider": "local",
	"filename": "report.pdf",
	"mimeType": "application/pdf",
	"meta": {
		"storageKey": "01HXK5MZSN....pdf"
	}
}

url と size は、他のキャッシュされたメタデータフィールドと同様に任意です。コンテンツクエリは永続化された値をそのまま返し、メディアライブラリからハイドレートしません。新しいメタデータやプロバイダ固有の URL が必要な場合の正規のルックアップ API については、ファイル値と現在のメタデータを参照してください。

リレーショナルタイプ

`reference`

エントリを別コレクションのエントリにリンクし、管理画面ではエントリピッカーとして表示されます。そのリンクはリレーションに属します。リレーションは 2 つのコレクションを結合し、各側に名前を付け、各側がリンクできるエントリ数を制限するスキーマオブジェクトです。Relations ではエディタと管理のワークフローを扱います。

次のフィールドは投稿を authors コレクションの 1 エントリにリンクします:

{
  slug: "author",
  label: "Author",
  type: "reference",
  required: true,
  validation: {
    targetCollection: "authors",
    multiple: false,
  },
}

検証:

targetCollection — このフィールドがリンクするコレクションのスラッグ。フィールドを作成すると、それに対するリレーションが作成されます。
multiple — 複数のリンク先エントリを許可（デフォルト: false）。制限はそのとき新しいリレーションに属するため、 targetCollection と合わせて読んでください。
relation — 新規作成の代わりにバインドする既存リレーションのスラッグ。
relationSide — このコレクションが relation のどの端にあるか、"parent" または "child"。両端が同じコレクションで両端が一致するリレーションにのみ設定します。

targetCollection か relation のどちらかを指定します。targetCollection から作成されたフィールドは {collection}_{field} という名前のリレーションの親端になり、子側はフィールドのラベルを取り、 multiple が設定されていなければ 1 エントリを保持します。relation から作成されたフィールドは、そのコレクションが属する端からそのリレーションを見ます。もう一方の端のコレクションがフィールドのターゲットです。1 つのリレーションは端ごとに 1 フィールドのみ受け付けるため、同じ端への 2 つ目のフィールドは拒否されます。どちらの形式も作成されたフィールドに relation、relationSide、targetCollection を保存し、ターゲットコレクションはその後固定されます。変更するにはフィールドを削除して新しいものを追加してください。フィールドの名前変更は、それが見るリレーションの側の名前も変更します。

参照フィールドはコレクションテーブルに列を追加しません。そのリンクは _emdash_content_references にあり、各エントリの翻訳グループでキー付けされるため、選択はロケールごとではなくエントリの翻訳間で共有されます。コンテンツの読み取りは、リンクされたエントリを data ではなくフィールドスラッグでキー付けされた references の下に返します。テンプレートでは名前でフィールドを要求します — 参照フィールドを読むを参照してください。

リレーションにバインドされたフィールドは、インデックスする列を持たないため indexed を設定できず、サイト検索の対象にもなりません。

リレーションのないフィールド

リレーションもターゲットコレクションも指定しない参照フィールドは TEXT 列を保持し、そこに 1 つのエントリ ID を格納します:

"01HXK5MZSN..."

options.allowMultiple が設定されたフィールドは、同じ列にエントリ ID の JSON 配列を保持します:

["01HXK5MZSN...", "01HXK6NATS..."]

列は他のテキスト列と同様に読み書きされ、コレクションスキーマは値を文字列として検証し、フィールドは indexed を設定でき、コンテンツリストのフィルタとして機能できます。ピッカーではなくテキストボックスとして表示されます。

ピッカーにするには、Content Types でフィールドを開き、参照先コレクションを選びます。 EmDash はリレーションを作成し、列内のエントリ ID をリンクとしてコピーし、フィールドの searchable と indexed フラグをクリアするため、コンテンツリストのフィルタとサイト検索はそれをカバーしなくなります。列はそのまま残り、書き込みは停止します。Relations ではエディタ側から同じ手順を扱います。

以前のリリースから更新されたサイトは、この状態のフィールドを保持できます。更新が何をバインドし、何をあなたがバインドする必要があるかについては、参照フィールドはリレーションにバインドされるを参照してください。

柔軟なタイプ

`json`

任意の JSON データ。複雑な入れ子構造、サードパーティ連携、固定スキーマのないデータに使います。

{
  slug: "metadata",
  label: "Metadata",
  type: "json",
}

SQLite JSON 列にそのまま保存されます。

`repeater`

構造化された行の繰り返しリスト。validation.subFields に少なくとも 1 つのサブフィールドを定義します。エディタは生の JSON を入力せずに行を追加、削除、並べ替え、編集できます。

次のフィールドは製品仕様のリストを保存します:

{
  slug: "specifications",
  label: "Specifications",
  type: "repeater",
  validation: {
    minItems: 1,
    maxItems: 12,
    subFields: [
      { slug: "label", label: "Label", type: "string", required: true },
      { slug: "value", label: "Value", type: "text", required: true },
      { slug: "source", label: "Source", type: "url" },
    ],
  },
}

Repeater の値はオブジェクトの配列として保存されます:

[
	{
		"label": "Weight",
		"value": "1.2 kg",
		"source": "https://example.com/specifications"
	}
]

許可されるサブフィールドタイプは string、text、url、number、integer、boolean、datetime、select、image です。Repeater に別の repeater や portableText、reference、file などの複雑なフィールドを含めることはできません。

Repeater の検証は次のプロパティを受け付けます:

subFields — 1 つ以上のサブフィールド定義。各定義には slug、label、type が必要で、required も設定できます。select サブフィールドは options で選択肢を提供します。
minItems — 最小行数。0 以上である必要があります。
maxItems — 最大行数。1 以上で、minItems より小さくできません。

`blocks`

型付きコンテンツブロックの順序付きリスト。各ブロックタイプには独自のフィールドがあり、番号付きバージョンを保持します。コレクションフィールドに追加する前に、スキーマ API、MCP、またはシードファイルでブロックタイプを定義してください。

次のフィールドでは、エディタがヒーローとコールトゥアクションのブロックからページを構成できます:

{
  slug: "layout",
  label: "Layout",
  type: "blocks",
  validation: {
    allowedTypes: ["hero", "call_to_action"],
    maxItems: 20,
  },
}

保存された各ブロックは、そのバージョンが宣言したフィールドとともに、タイプ、バージョン、安定キーを持ちます:

[
	{
		"_type": "hero",
		"_version": 1,
		"_key": "01K5AB3F7M9QZ2X8W4V6T1R0YH",
		"heading": "Bread made slowly, by hand."
	}
]

Blocks の検証は次のプロパティを受け付けます:

allowedTypes — 新しいブロックで利用可能な、順序付きブロックタイプスラッグ。
retiredTypes — 保存済みコンテンツ用に保持されるが、新しいブロックでは利用できないサーバー管理のブロックタイプ。
minItems — 最小ブロック数。データが入ったコレクションで 0 より大きくするとコンテンツ移行が必要です。
maxItems — 最大ブロック数（最大 100）。

blocks フィールドは任意で、デフォルトは空配列です。required、unique、searchable、indexed にできず、カスタムフィールドウィジェットでもレンダリングできません。ブロック定義はスカラー、テキスト、選択、Portable Text、画像、ファイル、repeater フィールドを使えます。参照、JSON、スラッグ、入れ子の blocks は含められません。

保存された配列は emdash/ui の <Blocks value components fallback> でレンダリングします。シード、コンポーネントマップ、欠落レンダラ、有効化、移行の例は blocks でページを構築するを参照してください。

フィールドプロパティ

すべてのフィールドは次の共通プロパティをサポートします:

Property	Type	Description
`slug`	`string`	一意の識別子（必須）
`label`	`string`	表示名（必須）
`type`	`FieldType`	フィールドタイプ（必須）
`required`	`boolean`	値を必須にする（デフォルト: false）
`unique`	`boolean`	一意性を強制（デフォルト: false）
`searchable`	`boolean`	フルテキスト検索にフィールドを含める（デフォルト: false）
`indexed`	`boolean`	インデックス付きの並べ替え/フィルタを有効化
`translatable`	`boolean`	ロケールごとに値を保存（デフォルト: true）
`defaultValue`	`unknown`	新しいエントリのデフォルト値
`validation`	`object`	タイプ固有の検証ルール
`widget`	`string`	カスタムウィジェットの上書き
`options`	`object`	ウィジェット設定
`sortOrder`	`number`	管理画面での表示順

indexed はスカラーフィールドで利用できます: string、url、number、integer、boolean、 datetime、select、reference、slug。インデックス付きフィールドはコンテンツリストクエリの orderBy フィールドとして渡したり、fieldFilters で使ったりできます。並べ替えやフィルタに使わないフィールドのインデックス付けは避けてください。インデックスごとにストレージと書き込みのオーバーヘッドが増えます。

searchable はフィールドのテキストをコレクションのフルテキスト検索インデックスに追加します。識別子、価格、フラグなど、エントリのすべての翻訳で同じでなければならない値には translatable: false を設定してください。あるロケールが翻訳不可フィールドを変更すると、EmDash はその値を翻訳済みエントリに同期します。

blocks タイプはこの共通セットのうち slug、label、type、translatable、validation、sortOrder のみを使います。その配列は列として必須になることはなく、常にデフォルトで [] です。

予約済みフィールドスラッグ

これらのスラッグは予約されており、使用できません:

id
slug
status
author_id
primary_byline_id
created_at
updated_at
published_at
scheduled_at
deleted_at
version
live_revision_id
draft_revision_id
terms
bylines
byline

TypeScript タイプ

プログラムからの利用のためにフィールドタイプ定義をインポートします:

import type { FieldType, Field, CreateFieldInput } from "emdash";

const fieldTypes: FieldType[] = [
	"string",
	"text",
	"url",
	"number",
	"integer",
	"boolean",
	"datetime",
	"select",
	"multiSelect",
	"portableText",
	"image",
	"file",
	"reference",
	"json",
	"slug",
	"repeater",
	"blocks",
];