コンテンツにスキップ
Kozou

ui-hints.yaml

ui-hints.yaml は、データベースに自然な置き場所のない表示上の上書き 設定のための任意ファイルです。DDL と COMMENT テキストだけで、Kozou は 使いやすい Admin UI をレンダリングし、REST API を公開し、MCP コンテキスト を出力するのに十分な情報を得ています。ui-hints.yaml が存在するのは、 スキーマそのものの性質ではない、ごく少数の見た目に関する決定のためだけ です。たとえば、ある列に特定の入力ウィジェットを強制したり、テーブルに より分かりやすいラベルを与えたりする場合です。

データベースが唯一の信頼できる情報源であるため （信頼できる情報源としての Postgres を参照）、 このファイルは意図的に小さく保たれています。このファイルがなくても システムは動作します。デフォルトが誤っていて、それを COMMENT で直す 良い方法がない場合にのみ、このファイルに手を伸ばしてください。

このファイルは任意です

Section titled “このファイルは任意です”

Kozou は ui-hints.yaml がまったくなくても動作します。ファイルが存在 しない場合 — あるいは存在していても空の場合 — すべてのラベル、ウィジェット、 表示フィールドはスキーマと妥当なデフォルトから得られます。create-kozou は、ほぼ空の ui-hints.yaml（コメントアウトされた例を伴う tables: {} のプレースホルダ）を雛形として生成します。これは、無視する理由がない うちは無視できるようにするためです。

パスは kozou.config.yaml の uiHints.path で設定し、ファイルが存在 しなくても許容されます。

uiHints:
  path: ./ui-hints.yaml             # the file need not exist

設定項目の残りの部分については kozou.config.yaml を参照してください。

優先順位

Section titled “優先順位”

各プロパティについて、Kozou は最大 3 つの情報源から順に値を解決します。 値を提供する最初の情報源が採用されます。

プロパティ解決順序
列のウィジェットui-hints.yaml → @widget COMMENT タグ → ヒューリスティックなデフォルト
列のラベルui-hints.yaml → 列の COMMENT の 1 行目 → 列名
テーブルのラベルui-hints.yaml → テーブルの COMMENT の 1 行目 → テーブル名
表示フィールドui-hints.yaml → ヒューリスティックなデフォルト

したがって ui-hints.yaml のエントリは、 @widget COMMENT タグと、Kozou が そうでなければ推測するであろうヒューリスティックの両方を上書きします。 それはチェーンの最上位に位置します。ここでウィジェットを設定すると、 その列の COMMENT 内の @widget タグはその列について無視されます。

このファイルが上書きするヒューリスティックは、 出力されるサーフェス のために文書化 されているのと同じデフォルトです。外部キーは既定で relation-select に、 検出可能な enum を持つ列は enum-select に、uuid 列は uuid に、数値型 は number に、といった具合です。表示フィールドは、name、title、 label、display_name、name_ja、name_en のうち存在する最初の列に、 次いで主キーにフォールバックします。

このファイルで上書きできるもの

Section titled “このファイルで上書きできるもの”

このファイルには tables と views という 2 つのトップレベルキーがあり、 それぞれオブジェクト名をキーとするマップです。以下の各フィールドは すべて任意です。変更したいものだけを含めてください。

  • テーブルごとの label — テーブルまたはビューに表示される表示名。
  • テーブルごとの displayField — 他の場所から参照されたときに行を 表すために使われる列（たとえば、外部キー関連で生の id の代わりに表示 されるテキスト）。
  • 列ごとの label — 列に表示される表示名。
  • 列ごとの widget — 列の入力／表示ウィジェット。次のいずれか： text、textarea、number、boolean、date、datetime、 enum-select、relation-select、json、image-url、uuid、 currency。
  • 列ごとの readonly — Admin UI で列を読み取り専用としてマークします。
  • 列ごとの relation — relation-select 列について、参照される行の ラベル付けと検索の方法を制御する labelField と searchFields[]。

列の並び順は、テーブルまたはビューの下に列を列挙した順序に従います。 エントリはマップとして記述され、キーはソース順で提示されます。記載しな かった列はスキーマ上の位置を保ちます。

ここには列ごとの description や @ai に相当するものはありません。 そうしたテキストはデータベースの COMMENT に属し、そこではすべての 出力サーフェスがそれを読み取れます。

構造

Section titled “構造”
tables:
  <table_name>:
    label: <string>
    displayField: <column_name>
    columns:
      <column_name>:
        label: <string>
        widget: <widget>
        readonly: <bool>
        relation:
          labelField: <column_name>
          searchFields: [<column_name>, ...]


views:
  <view_name>:
    label: <string>
    columns:
      <column_name>:
        label: <string>
        widget: <widget>

例

Section titled “例”

products に、draft / published / archived に制約された status 列があるとします。Kozou はすでに enum を検出して enum-select を レンダリングしますが、より分かりやすいラベルが欲しく、また長い description 列には複数行エディタを使いたいとします。

tables:
  products:
    label: Catalog
    displayField: name
    columns:
      status:
        label: Publication status
        widget: enum-select
      description:
        widget: textarea
      sku:
        readonly: true

ここでは status のラベルとウィジェット、description のウィジェット、 sku の読み取り専用フラグが、COMMENT タグやヒューリスティックが生成 したであろうものを上書きします。products の他のすべてはデフォルトに 委ねられます。

関連の上書きは次のようになります。これは author_id が authors テーブルを指す orders テーブルの例です。

tables:
  orders:
    columns:
      author_id:
        label: Author
        widget: relation-select
        relation:
          labelField: full_name
          searchFields: [full_name, email]

最小限に保つ

Section titled “最小限に保つ”

ui-hints.yaml のすべてのエントリは、データベースの外側で表現された データに関する事実です。つまり、スキーマと同期が取れなくなる可能性が あり、また COMMENT テキストと整合させ続けるべきファイルが 1 つ増える ことになります。それはコストだと捉えてください。

  • 表示上の問題は情報源で直すことを優先してください。誤ったウィジェット は、列の COMMENT 内の @widget タグで修正するほうが良いことが多く、 誤ったラベルは COMMENT の 1 行目をより明確にすることで修正するほうが 良いことが多いです。どちらもスキーマとともに移動し、MCP コンテキストを 読む AI エージェントから見えます。
  • ui-hints.yaml は残りカスのために使ってください。すなわち、純粋に 表示に関するもので SQL に置き場所のない選択や、データベースの COMMENT を編集するほどの価値がない一回限りの上書きです。
  • 検証は読み込み時に実行されます。存在しないテーブル、ビュー、または列を 参照すると、Kozou は警告します。解析不能なファイルやスキーマ的に無効な ファイルはエラーとして報告されます。ファイルを小さく保つことで、これら の参照をスキーマと照らし合わせて検証しやすくなります。

目標は、データベースが表現できない上書きだけを保持する、ほとんど空の ui-hints.yaml です。

関連項目

Section titled “関連項目”