カタログエンティティの作成と変更¶

CLI と MCP から owl.catalog.entity_create と owl.catalog.entity_modify を呼び出せます。対応する CLI、Registry、書き込み API を提供する AIAPI / Backend を更新し、カタログを同期してください。利用可能な機能と権限は接続先に従います。書き込み前に対象と変更内容を確認します。

タイプ、チーム、対象の確認¶

owl sync
owl exec owl.catalog.entity_type_query -p '{"page_size":20,"page_index":1}'
owl exec owl.workspace.member.group_list -p '{"search":"Platform"}'
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

選択したタイプの schemaDefine と customProperties を読み、必須属性をすべて指定します。トップレベルの name は別の必須属性の代わりにはなりません。動的な属性と関係はバックエンドが検証します。

entity_query には entity_type が必須です。name は完全一致、search は名前・表示名・URN のあいまい検索で、同時指定はできません。urn と filters でさらに絞り込めます。filters はカタログのフィールド構文であり SQL/DQL ではありません。name と filters.name を併用する場合は同じ名前にします。

チーム検索は group_uuid、name、member_count を返し、ページ分割はありません。owl.member.group_list は互換エイリアスです。attributes.owner には返されたチーム名を使い、UUID や個人名を使いません。値の形式はタイプ定義に従います。無料版ワークスペースではチーム検索を利用できません。

作成と部分変更¶

作成には request_id（UUID）、entity_type、name が必須です。display_name、attributes、relation_modes は任意です。name は最大 1024 文字、空白でない display_name は最大 256 文字で、省略時は name を使います。既存の識別子や同タイプ・同名のエンティティを上書きしません。

変更には request_id と検索で返された完全な urn が必須です。変更する display_name、attributes、relation_modes だけを送信します。name の改名、タイプ変更、ワークスペースをまたぐ書き込みには対応しません。検索 item 全体を送り返さず、表示名はトップレベルの display_name に指定します。

省略したフィールドは維持し、オブジェクトは再帰的にマージ、通常の配列は全体を置換します。空オブジェクトはクリアを意味せず、null は削除命令ではありません。手動編集で provider やライフサイクルが変わる場合があります。

実際のタイプが定義する関係だけを送信します。変更時は depends_on、component_of、components の各送信フィールドに relation_modes を指定します。add は追加と重複排除、replace は全体置換で、空配列との replace はクリアです。作成時の既定値は replace です。関係先は同じワークスペースに存在する URN を使い、自己参照を禁止します。components は全タイプ共通ではありません。

書き込み結果と確認¶

新しい操作ごとに UUID を一つ生成し、ツール、完全なパラメーター、認証主体とワークスペースを永続的に記録します。認証情報の値は記録しません。CLI は -f json で業務結果を確認してください。終了コード 0、HTTP 200、外側の success だけでは完了を証明しません。

成功には data.write_state=confirmed、対応する request_id、エンティティ URN が必要です。changed=false は変更なしの成功である場合があります。replayed=true は再書き込みを意味しません。confirmed は実体の再取得と監査タスクの投入完了であり、監査の最終保存完了ではありません。

can_retry_write=true の場合だけ、後続の呼び出しが業務書き込みを再送できます。retry_after_ms（最大 30000 ミリ秒）と合計最大 6 回の送信制限に従い、元の UUID とパラメーターを再利用します。それ以外の pending は確認のみです。audit_unknown を自動再試行しません。

バックエンドの状態保持期間はワークスペース・実アカウント・request_id ごとに 7 日です。期限切れ、状態消失、主体やワークスペース変更後は先に照合します。古い UUID は永久的な重複防止ではありません。一回の呼び出しが自動でポーリングや再送を行うことはありません。