フィールド

入力項目の種類、配信される値、必須設定、参照フィールドの設計。

フィールドは、コンテンツに入力する1つの項目です。管理画面で使う表示名と、APIレスポンスのキーになるフィールドIDを設定します。

たとえば表示名が「タイトル」、IDがtitleなら、配信されるJSONは{ "title": "はじめての記事" }です。スキーマを変更できるのはオーナーです。

種類と使い分け

種類	APIでの種類名	配信される値	用途
テキスト	`text`	文字列	タイトル、短い説明
テキストエリア	`textarea`	文字列	装飾のない複数行の文章
リッチテキスト	`richtext`	HTML文字列	見出し、画像、リンクのある本文
画像	`image`	`{ url, alt }`	アイキャッチ
複数画像	`images`	`{ url, alt }`の配列	ギャラリー
日時	`datetime`	日時の文字列	イベント日時
真偽値	`boolean`	`true`または`false`	おすすめ表示などのフラグ
セレクト	`select`	単一選択は文字列、複数選択は文字列配列	カテゴリ、タグ
コンテンツ参照	`reference`	ID、展開されたオブジェクト、または`null`	著者など1件への関連付け
複数コンテンツ参照	`references`	IDまたは展開されたオブジェクトの配列	関連記事
数字	`number`	数値	表示順、数値データ
ファイル	`file`	URL文字列	PDFなどのダウンロード
連携ブロック	`extension`	プロバイダーに応じたオブジェクト	Google Maps、Google Drive、Dropbox、X

未入力の項目もあるため、任意フィールドを使う表示では値の有無を確認してください。リッチテキストはJSONのエディタデータではなく、HTMLとして返されます。Reactコンポーネントで表示できます。

必須を有効にすると、コンテンツの保存時に入力を求めます。種類に応じて、文字数・数値の範囲、選択肢、初期値、複数選択、参照先APIなどを設定できます。

必須設定は「公開するときだけ」の制約ではありません。作成途中の記事を保存する運用も考えて設定してください。

初期値を設定しても、すでに保存されているすべての記事に値が追加されるわけではありません。項目を追加した後は、既存データの確認も必要です。

著者情報を複数の記事で共用したい場合は、著者用のAPIを作り、ブログのauthorフィールドから参照します。記事ごとに著者名をコピーして入力する必要がなくなります。

配信時の形はdepthで変わります。

展開対象は公開条件を満たす参照先だけです。参照先が下書き・削除済みなどの場合、単一参照はnull、複数参照ではその項目が配列から除かれます。親記事のプレビューでも参照先の下書きは展開されません。

CLIが生成する参照型はunknown／unknown[]です。参照先の型を自動生成して関連付ける機能ではありません。利用箇所で値を確認するか、期待する形をアプリ側で定義してください。

画像のaltには、画像の内容や役割が伝わる説明を入力します。サイト側でもimgのaltへ渡してください。ファイルのURLは、配信レスポンスから取得します。

メディアを差し替えると、次回の取得で新しいURLが返されます。取得したURLを別のデータベースに固定保存して使い続けると、差し替えに追従できなくなります。メディア管理を参照してください。

連携ブロックは、プロバイダーに応じた値にembedUrlを付けて返します。Dropboxなど、iframe向けのURLを生成しない場合はembedUrlが省略されるため、リンクとして表示するなどの分岐が必要です。

連携先の共有設定や埋め込み可否も確認してください。genko.meにURLを保存するだけで、非公開ファイルの閲覧権限が付与されるわけではありません。

APIで返る形の詳細はレスポンスの値、絞り込みに使える種類はクエリ仕様を参照してください。