フィールドの種類と値の形

コンテンツタイプのフィールドには、14 の種類があります。このページでは、種類ごとに、設定できること、Content API で返る値の形、書き込める値、絞り込みと並べ替えに使えるかを並べます。名前は、管理画面のコンテンツタイプの画面と同じです。

種類の一覧

画面の名前	kind	入れるもの	返る値	値がないとき
テキスト	text	タイトルや名前など、1 行の文字	文字列	キーがない
テキストエリア	textArea	説明など、改行を含む文字	文字列。改行は \n	キーがない
リッチエディタ	richEditor	見出し・リスト・画像などを含む本文	Hako Rich Text v1 の JSON	キーがない
画像	media	1 枚の画像	{ "url", "width", "height", "alt" }	キーがない
複数画像	mediaList	並べた複数の画像	画像の配列	[]
ファイル	file	PDF などのファイル	{ "url", "fileSize" }	キーがない
日時	date	日時か日付	UTC の ISO 8601 の文字列	キーがない
真偽値	boolean	オン・オフ	true か false	false
セレクト	select	決まった選択肢から選ぶもの	選んだ値の配列	[]
数字	number	価格や順位などの数	数値	キーがない
参照	relation	ほかのコンテンツタイプのエントリー 1 つ	参照先のエントリー	キーがない
複数参照	relationList	ほかのコンテンツタイプのエントリーいくつか	参照先のエントリーの配列	[]
カスタム	custom	カスタムフィールド 1 つ	fieldId と中のフィールドを持つオブジェクト	キーがない
繰り返し	repeater	カスタムフィールドをいくつでも	カスタムの値の配列	[]

配列になる種類と真偽値は、値がなくてもいつも返ります。そのほかの種類は、値がないとキーごと返りません。

どの種類にもある設定

画面の名前	キー	型	必須	既定	決まり
フィールド ID	fieldId	文字列	○		英字で始まり、英数字・_・- が続く 1〜64 文字。同じスキーマの中で重ならない。保存したあとは変えられない
表示名	name	文字列	○		1〜100 文字
説明	description	文字列		なし	500 文字まで。入力欄の下に、入稿する人向けに出る
必須	required	真偽値		false	公開するときに値を求める。下書きの保存では求めない
種類	kind	文字列	○		上の表の 14 のどれか

フィールド ID は、Content API の応答のキーになります。次のフィールド ID は、Hako CMS が使うので使えません：sys id createdAt updatedAt publishedAt revisedAt fieldId。消したフィールドの ID も、戻せるように取っておかれるので、新しいフィールドには使えません。

スキーマの JSON は、次の形です。管理画面のコンテンツタイプの画面で［JSON で編集］を押すと、同じ形で編集できます。

{
  "fields": [
    { "fieldId": "title", "name": "タイトル", "kind": "text",
      "required": true, "unique": true, "maxLength": 100 },
    { "fieldId": "tags", "name": "タグ", "kind": "select", "multiple": true,
      "options": [
        { "id": "a1", "value": "news" },
        { "id": "b2", "value": "tech" }
      ] },
    { "fieldId": "blocks", "name": "ブロック", "kind": "repeater",
      "customFieldIds": ["text"] }
  ],
  "customFields": [
    { "id": "text", "name": "テキスト",
      "fields": [{ "fieldId": "body", "name": "本文", "kind": "richEditor" }] }
  ]
}

種類ごとの設定

設定を省くと、制約はかかりません。

下書きを保存するときは、必須、最小文字数、最小件数を確かめません。公開するときに、すべての設定を確かめます。合わないときは 400 が返り、どのフィールドがなぜ合わないかが issues に出ます。

テキスト（text）

画面の名前	キー	型	既定	決まり
重複を許さない	unique	真偽値	false	同じコンテンツタイプのほかのエントリーと同じ値を許さない
最小文字数	minLength	整数	なし	0 以上
最大文字数	maxLength	整数	なし	0 以上
正規表現	pattern	文字列	なし	値の全体が、この正規表現に合わなければならない。1000 バイトまで

• 文字数は、Unicode の文字（スカラー値）で数えます。minLength は maxLength 以下にします
• 正規表現は、値の全体に当てます（前後に ^ と $ を書かなくても、全体で比べます）。書き方は Rust の regex の形です。後読みや後方参照は使えません
• 重複を許さない設定は、カスタムフィールドの中のテキストには付けられません

テキストエリア（textArea）

画面の名前	キー	型	既定	決まり
最小文字数	minLength	整数	なし	0 以上
最大文字数	maxLength	整数	なし	0 以上
正規表現	pattern	文字列	なし	値の全体が、この正規表現に合わなければならない。1000 バイトまで

文字数と正規表現の決まりは、テキストと同じです。

リッチエディタ（richEditor）、画像（media）、ファイル（file）、真偽値（boolean）

どの種類にもある設定のほかに、設定はありません。

複数画像（mediaList）

画面の名前	キー	型	既定	決まり
（最小件数）	minCount	整数	なし	0 以上
最大件数	maxCount	整数	なし	0 以上

日時（date）

画面の名前	キー	型	既定	決まり
日付のみ	dateOnly	真偽値	false	管理画面で、日付だけを入力させる

dateOnly は入力のしかただけを変えます。API で返る値は、いつも日時の文字列です。

セレクト（select）

画面の名前	キー	型	既定	決まり
選択肢（1 行に 1 つ）	options	{ "id", "value" } の配列		必須。value が API で返る値。id は、並べ替えや名前の変更のあとも選択肢を追うためのもの
複数選択	multiple	真偽値	false	2 つ以上選べるようにする

選択肢は 1 つ以上要ります。id と value は空にできず、選択肢の間で重なってはいけません。

multiple が false でも、値は 1 つの値の配列（["news"]）で返ります。

数字（number）

画面の名前	キー	型	既定	決まり
最小値	min	数値	なし
最大値	max	数値	なし	min 以上

参照（relation）

画面の名前	キー	型	既定	決まり
参照先のコンテンツタイプ	contentTypeId	文字列		必須。参照先のコンテンツタイプの ID（Admin API の id。エンドポイントではない）

スキーマのファイル（*.hako.json）では、参照先を contentType にエンドポイントで書きます。contentTypeId は書きません。

複数参照（relationList）

画面の名前	キー	型	既定	決まり
参照先のコンテンツタイプ	contentTypeId	文字列		必須。参照と同じ
（最小件数）	minCount	整数	なし	0 以上
最大件数	maxCount	整数	なし	0 以上

カスタム（custom）

画面の名前	キー	型	既定	決まり
カスタムフィールド	customFieldId	文字列		必須。スキーマの customFields の id

繰り返し（repeater）

画面の名前	キー	型	既定	決まり
使えるカスタムフィールド	customFieldIds	文字列の配列		必須。スキーマの customFields の id
（最小件数）	minCount	整数	なし	0 以上
最大件数	maxCount	整数	なし	0 以上

繰り返しの中には、許したカスタムフィールドを、種類を混ぜて好きな順に並べられます。customFieldIds は 1 つ以上要ります。

件数の設定では、minCount を maxCount 以下にします。「（最小件数）」の印のある設定は、管理画面のフォームには出ません。［JSON で編集］か Admin API で設定します。

カスタムフィールド

カスタムフィールドは、いくつかのフィールドをまとめた入れ物です。スキーマの customFields に置き、カスタムと繰り返しのフィールドから使います。

画面の名前	キー	型	必須	決まり
ID	id	文字列	○	英字で始まり、英数字・_・- が続く 1〜64 文字。値の fieldId になる。保存したあとは変えられない
名前	name	文字列	○	1〜100 文字
フィールド	fields	フィールドの配列	○	中のフィールド。形はふつうのフィールドと同じ

カスタムフィールドの中に、カスタムと繰り返しのフィールドは置けません。

カスタムの値は、どのカスタムフィールドかを示す fieldId と、中のフィールドの値を持ちます。

"seo": { "fieldId": "seo", "description": "Hako CMS の紹介です" }

返る値の形

Content API の読み取りで返る値です。

種類	返る値
テキスト、テキストエリア	文字列。改行は \n
リッチエディタ	Hako Rich Text v1 の JSON。richText=html を付けると HTML の文字列
画像	{ "url", "width", "height", "alt" }。width、height、alt はないこともある
複数画像	画像の配列
ファイル	{ "url", "fileSize" }
日時	UTC の ISO 8601 で、ミリ秒まで（2026-10-08T06:00:00.000Z）
真偽値	true か false
セレクト	選んだ value の配列。1 つでも配列
数字	数値
参照	参照先のエントリー。include の段数まで展開し、その先は { "sys": { "id", "contentType" } } だけ
複数参照	参照先のエントリーの配列
カスタム	{ "fieldId": <カスタムフィールドの ID>, …中のフィールド }
繰り返し	カスタムの値の配列

公開していない、公開を終えた、または削除したエントリーへの参照は返りません。参照ならキーがなくなり、複数参照なら配列から除かれます。詳しくは 参照の先も一緒に取る にあります。

書き込める値

Content API と Admin API で書き込むときは、返る値と同じ形のほかに、次の形も受け付けます。

種類	送る値
テキスト、テキストエリア	文字列
リッチエディタ	Hako Rich Text v1 の JSON か、HTML の文字列
画像、ファイル	{ "url": … } か、URL の文字列
複数画像	画像の配列
日時	ISO 8601 の文字列。UTC にそろえて保存する
真偽値	true か false
セレクト	選ぶ値の配列
数字	数値
参照	参照先のエントリー ID か、{ "sys": { "id": … } }
複数参照	その配列
カスタム	fieldId を持つオブジェクト
繰り返し	カスタムの値の配列

• 画像とファイルには、外の URL も入れられます。このスペースのメディアの URL なら、幅・高さ（ファイルは fileSize）がメディアの値で補われます。ほかのスペースのメディアは入れられません。画像のフィールドに画像でないメディアは入れられません
• リッチエディタに HTML を送ると、エディタで扱える要素に変えて保存します。扱えない要素は中身だけが残り、<script> などは捨てられます
• 値を消すとき（PATCH）は、どの種類でも null を送ります。配列は [] で空になります
• スキーマにないフィールドを送ると、400 が返ります

絞り込み、並べ替え、検索

Content API の where、order、q で使えるかどうかです。書き方は 絞り込む、並べる、ページに分ける にあります。

種類	where で使える演算子	order	q
テキスト、テキストエリア	= != contains not contains startsWith in not in exists	○	○
リッチエディタ	exists		○
画像、ファイル	exists
複数画像	exists（空でないか）
日時	= != < <= > >= startsWith in not in exists	○
真偽値	= != in not in。値がなければ false
セレクト	= != contains not contains in not in exists。= は「要素に含む」
数字	= != < <= > >= in not in exists	○
参照	= != in not in exists。値は参照先のエントリー ID
複数参照	= != contains not contains in not in exists。= は「要素に含む」
カスタム	exists		中のテキストを探す
繰り返し	exists（空でないか）		中のテキストを探す

参照先のフィールドで絞り込むこと（author.name = "Kohei"）は、まだできません。

種類を変える、フィールドを消す

• 種類を変えられるのは、テキストとテキストエリアの間と、数字からテキストへだけです。ほかの種類にしたいときは、新しいフィールドを足します
• フィールドを消すと、API の応答から外れます。値はしばらく残っていて、同じフィールド ID のフィールドを戻すと値ごと戻ります。消してから 30 日たつと、値も消えます
• 必須にする、文字数を厳しくするなど、今のエントリーが合わなくなる変更をすると、保存の前に、合わないエントリーの数が表示されます。適用すると、合わないエントリーは次に保存するときに直すよう求められます
• 重複を許さない設定は、今のエントリーに同じ値があると付けられません。先に重複を直します

関連

• エントリーを取り出す
• エントリーを書き込む、公開する
• リッチテキストの形（Hako Rich Text v1）
• Content API のリファレンス