selector-creator

セレクターの作成

ブランチ上で、Datex Studio セレクター（configurationTypeId=7）を作成または変更します。これは、プラットフォームのドロップダウン／オートコンプリートコントロールです。セレクターは、データソースに基づくオプションリスト、各オプションの表示ラベルを定義する式、入力されたテキストをバックエンドのデータソースに渡す組み込みの全文検索ボックスを定義します。フォームフィールド、ハブのフィルタードロップダウン、グリッドのフィルターセル内にマウントされ、単独ではレンダリングされません。

参考資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（スキル間で共有）
• references/selectors.md — セレクター作成の決定版リファレンス：コンポーネントバリアントのルール、ファイル形式、データソースの接続、全文検索の3要素の契約、getList と getByKeys の同等性
• ../datex-studio-conventions/file-format.md — configurationTypeId の一覧と TypeScript 式のエンコード規則
• ../datex-studio-conventions/naming-conventions.md — _dd サフィックスの規則、ファイル名のベース名の一致、表示名の規則
• ../datex-studio-runtime/runtime-globals.md — セレクターコードで利用できるプラットフォーム注入のグローバル（$selector、$option、$flows、$utils、…）
• ../datex-studio-runtime/calling-conventions.md — UI 層の呼び出し規則（関数を呼び出し、アクションは呼び出さない）
• ../datasource-creator/references/datasources.md — データソースの分類（コンポーネントバリアントの -datasource.json と FPDS の -footprintDatasource.json）
• ../datasource-creator/references/flow-datasources.md — フロー型データソースの形式（列挙型ドロップダウン、計算されたオプションセット）
• ../datasource-creator/references/odata-datasources.md — OData 型データソースの形式（エンティティに基づくドロップダウン）
• ../component-wiring-check/references/component-wiring.md — 呼び出し元との契約ルール、moduleId のルール
• ../form-creator/references/forms.md — 一般的なマウント先（フォームフィールド）
• ../hub-creator/references/hubs.md — 一般的なマウント先（ハブのフィルタードロップダウン）

依存関係

• requirements-gathering スキル — 会話のコンテキストに要件ブリーフがない場合、作成のために呼び出します
• datasource-creator スキル — セレクターに新しいバックエンドデータソースが必要な場合に呼び出します（ラップする -datasource.json がまだないセレクターすべてが対象）。バックエンドには必ず -datasource.json を使用し、-footprintDatasource.json は使用しないでください
• schema-explorer スキル — OData に基づくセレクターを作成する前に呼び出し、エンティティ、表示ラベルのフィールド、およびフィルターフィールドが Footprint スキーマに存在することを確認します
• form-creator／hub-creator スキル — セレクターのホスト（フォームフィールドまたはハブのフィルタードロップダウン）で、セレクターをマウントするための configParameters の契約を設定する必要がある場合に呼び出します
• component-wiring-check スキル — プッシュ前に、セレクターのホスト（外側）とバックエンドデータソース（内側）の両方で、configParameters と対象の inParams の契約を監査するために呼び出します。特に full_text_search の接続が対象です
• type-definition-creator スキル — セレクターのオプションエンティティの形状に新しいインターフェースまたは拡張したインターフェースが必要な場合に呼び出します（まれです。ほとんどのセレクターは既存のデータソースの outParams を反映します）

CLI のライフサイクル

セレクターの作成・編集には dxs configuration を使用します。これは、すべてのプラットフォーム設定タイプに対応する汎用 CRUD プリミティブです。dxs selector サブコマンドやフィールド単位のパッチ機能はありません。JSON 本文全体を作成する（または取得して抽出する）→編集する→全体を再度プッシュする、という手順になります。CLI のタイプ識別子は selector（小文字。ConfigurationEndpoints.normalize_type の出力と一致）で、configurationTypeId: 7 に対応します。

新しいセレクターを作成する場合：

# 1. Build body.json from scratch (see references/selectors.md → Datasource-Backed Selector)
# 2. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate selector -b <branchId> -D body.json
# 3. Create
dxs configuration upsert selector -b <branchId> -D body.json

既存のセレクターを編集する場合：

# 1. Fetch — note the envelope wrapper
dxs configuration get selector <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (round-trip footgun guard — see "Round-trip rule" below)
jq .json envelope.json > body.json
# 3. Edit body.json
# 4. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate selector -b <branchId> -D body.json
# 5. Push
dxs configuration upsert selector -b <branchId> -D body.json

ラウンドトリップのルール（重要）

既存の設定を編集する場合、envelope.json を直接 dxs configuration upsert にパイプしてはいけません。設定内容が警告なく破壊されます。上記の修正済み手順（編集前に jq で内部の .json を抽出する）は、すべてのラウンドトリップで必須です。正規のラウンドトリップ手順と根本原因となったバグについては、../datex-studio-shared/configuration-roundtrip.md を参照してください。

セレクターはグリッドやフォームよりもシンプルです。本文の大部分は、configId、moduleId、datasourceKeyDef、configParameters、configOutParameters を含む datasourceConfig、表示ラベルの式である text、文字列の top、およびコンポーネント識別情報のエンベロープで構成されます。全文検索の設定はセレクターと、それを支えるデータソースにまたがります。両方にラウンドトリップの手順（取得 → jq で抽出 → 編集 → 検証 → プッシュ）が適用されます。

ワークフロー

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO -> invoke `requirements-gathering`
  |            |
  +-----+------+
        |
[Phase 2: Decide selector shape + backing source]
Consult references/selectors.md:
  - datasource-backed dropdown (most common) — wraps an existing or new
    `-datasource.json` (flow-type or OData-type query inside)
  - autocomplete — same shape; the dropdown's built-in full-text search
    box plus the three-piece contract makes it an autocomplete
  - enum dropdown — flow-type backing iterating $types.<Package>.<enum>
    with formatKey helpers, getList/getByKeys parity required
Backing-datasource source:
  - existing `-datasource.json` -> wrap it; verify keyDef/outParams; flow-type
    backing must be the keyed-collection shape (getListFlow + getByKeysFlow
    populated, non-empty keyDef) — getList-only cannot resolve selected labels
  - existing `-footprintDatasource.json` (FPDS) -> NOT ALLOWED as backing;
    wrap the FPDS in a flow-type `-datasource.json` that calls through,
    or invoke `datasource-creator` for a fresh one
  - no datasource yet -> invoke `datasource-creator`; for OData-backed
    options invoke `schema-explorer` first to confirm the entity
        |
[Phase 3: Author selector body]
Build body.json:
  - File shape (configurationTypeId=7, *-selector.json suffix,
    referenceName typically ends _dd, snake_case matches filename stem)
  - Hard component-variant rule — datasourceConfig.configId points to a
    `-datasource.json` (configurationTypeId=6), NEVER a
    `-footprintDatasource.json` (configurationTypeId=19); query type
    inside the backing is unconstrained (flows or oDataQuery)
  - Key wiring — datasourceKeyDef mirrors the datasource's keyDef;
    configId + moduleId resolve to the backing; moduleId is the
    DATASOURCE's package, not the selector's caller
  - configOutParameters mirrors the datasource's outParams shape with
    full property-descriptor boilerplate on every objectTypeDef entry
  - text — display-label expression on $option.entity.<DisplayField>
  - top — STRING ("25"), not a number
  - Sort by display label — when authoring the backing datasource for
    this selector, sort by the field referenced in text (OData orderBys
    or in-code sort for flow-type)
  - Full-text-search three-piece contract (when backing exists solely
    for this selector): (1) backing declares full_text_search inParam
    (string, required: false); (2) backing applies conditional
    contains-filter on the display-label field gated on
    $utils.isDefined; (3) selector wires $selector.fullTextSearch into
    the datasource's full_text_search via configParameters
  - getList ↔ getByKeys parity — if getListFlow applies a Key transform
    (formatKey, etc.), getByKeysFlow MUST apply the identical transform
    (duplicate the helper definitions inside both code bodies — flows
    don't share scope)
  - No $types.<Package>.e_<enum> in vars/inParams/outParams — primitives
    only at the param layer; cast at usage in flow code
  - Sibling *Config keys explicitly null
  - Invoke `schema-explorer` for OData entity / display-label / filter
    field validation before authoring OData-backed selectors
  - Invoke `component-wiring-check` to audit BOTH the outer host
    contract (form field / hub filter / grid filter cell) AND the inner
    selector → datasource contract (every declared backing inParam,
    including full_text_search, needs an explicit configParameters
    entry)
        |
[Phase 4: Validate + push]
dxs configuration validate selector -b <branchId> -D body.json
        |
   +----+----+
   |         |
  CREATE   MODIFY-EXISTING
   |         |
   |         use the corrected round-trip
   |         (get -O envelope -> jq .json -> body)
   |         |
   +----+----+
        |
        v
dxs configuration upsert selector -b <branchId> -D body.json
   (upsert creates or updates by referenceName — one command for both)
        |
[Phase 5: Verify in Studio (optional)]
Open the selector through its normal mount (form field / hub filter);
confirm option population, alphabetized order by display label,
full-text-search filtering live as you type, saved-selection re-hydration
shows the same display label getList showed (getByKeys parity)
        |
[invoke `post-edit-verification`; then `component-validator`]

フェーズの詳細

フェーズ 1：セットアップと要件

1. ブランチと接続の選択については、../datex-studio-shared/branch-setup.md に従ってください。ブランチ ID を決めつけてはいけません。ユーザーに確認を求めてください。
2. 会話のコンテキストに要件概要（requirements-gathering または別の呼び出し元スキルが作成）がすでにあるか確認してください。
   • 概要がある場合 — それを使用してください。概要には、ドロップダウンが表すもの（エンティティ、列挙型、計算されたリスト）、ユーザーに表示するラベル、保存された選択内容に保持される基になるキー／値、セレクターの配置場所（フォームフィールド／ハブフィルター／グリッドフィルターセル）、およびオートコンプリートの動作が必要かどうかを明記してください。
   • 概要がない場合 — まず requirements-gathering スキルを呼び出してください。表示ラベル、保存するキー、配置場所を最初に正しく把握しておけば、text、datasourceKeyDef、およびホストの configParameters を作り直す必要がなくなります。

フェーズ 2：セレクターの形状とデータソースを決める

作成を始める前に、references/selectors.md を確認してください。決めることは 2 つあります。

セレクターの形状。 よく使われる形状は 3 種類です。

• データソース連携型ドロップダウン — 標準的な形状です。既存または新規の -datasource.json をラップし、その outParams を選択肢として表示します。text: "$option.entity.<DisplayField>" で表示ラベルを指定します。
• オートコンプリート — 形状はデータソース連携型ドロップダウンと同じです。ドロップダウンに組み込まれた全文検索ボックスと、3 要素からなる契約（references/selectors.md → 全文検索の配線 を参照）により、入力した文字に応じて選択肢がリアルタイムで絞り込まれます。
• 列挙型ドロップダウン — フロー型のデータソースが $types.<Package>.<enum> を反復処理し、{ Key, Value } の行を出力します。formatKey／capitalize ヘルパーで表示ラベルを整形します。getList と getByKeys の整合性が必要です（references/selectors.md → getList と getByKeys のキー変換の整合性 を参照）。

データソース。 選択肢の取得元を決めます。

• 既存の -datasource.json — これをラップします。keyDef と outParams の形状を確認してください。セレクターの datasourceKeyDef と configOutParameters は、それらと一致させる必要があります。このブランチのサーバー側使用ゲートでは、基盤となるデータソースに getList と getByKeys の実装がない場合、公開がブロックされます。このセクションで必要とする、キー付きコレクションと同じ形状です。
• 既存の -footprintDatasource.json（FPDS） — セレクターのデータソースとして使用できません。これはプラットフォームの厳格なルールです。FPDS を呼び出すフロー型の -datasource.json でラップするか、datasource-creator を呼び出して同じ形状を返す新しいデータソースを作成してください。
• データソースがまだない — datasource-creator を呼び出します。OData を基盤とするデータソースの場合は、まず schema-explorer を呼び出して、Footprint スキーマにエンティティ、表示ラベル用のフィールド、フィルター用のフィールドが存在することを確認してください。

フェーズ 3：セレクターの本体を作成する

references/selectors.md → データソース連携型セレクター のひな形から body.json を作成します。重要な点は次のとおりです。

1. ファイルの基本事項。 以下の事前確認チェックリストと ../datex-studio-conventions/universal-checklist.md に従ってください。-selector.json ファイルの形状については、references/selectors.md → データソース連携型セレクター を参照してください。referenceName の _dd ドロップダウンインジケーターは、セレクター固有の命名規則です。

2. コンポーネントのバリアントに関する厳格なルール。 datasourceConfig.configId と moduleId は、-datasource.json（configurationTypeId: 6）を参照する必要があります。-footprintDatasource.json（FPDS、configurationTypeId: 19）を参照することはできません。これは例外のない、プラットフォームの厳格なルールです。基盤データソース内部のクエリタイプには制約がありません。フロー型（type: "flows"。列挙型ドロップダウンや計算済みリストに使用）でも、OData 型（type: "oDataQuery"。データベースエンティティから選択肢を取得する場合に使用）でも構いません。つまり、セレクターで重要なのはコンポーネントのバリアントであり、クエリタイプではありません。必要なデータを FPDS がすでに公開している場合は、FPDS を呼び出すフロー型の -datasource.json でラップしてください。セレクターから FPDS を直接参照してはいけません。references/selectors.md → 基盤データソースのバリアント — 厳格なルール を参照してください。

3. キーの接続。 datasourceConfig.configId と moduleId は、データソースを識別します。moduleId はセレクターの呼び出し元ではなく、データソースのパッケージです。datasourceConfig.datasourceKeyDef はデータソースの keyDef をミラーリングします（同じ ID、同じ型）。ここに不整合があると、getByKeys による保存済み選択の再ハイドレーションが失敗します。datasourceConfig.configParameters は、セレクターの入力（例：$selector.fullTextSearch）をデータソースの inParams に接続します。datasourceConfig.configOutParameters は、データソースの outParams の形状をミラーリングします。同じ objectTypeDef エントリーを、パラメーター記述子の定型項目すべてとともに使用してください。references/selectors.md → 主なポイントを参照してください。

4. text は表示ラベルの式です。 通常は "$option.entity.<DisplayField>"（例："$option.entity.Name"、"$option.entity.Key"）です。ドロップダウンでリストを描画する際、オプションごとに一度実行されます。formatKey で整形された { Key, Value } の行を返すデータソースを使用する列挙型ドロップダウンでは、標準の表示値は "$option.entity.Key" です。

5. top は数値ではなく文字列です。 "25" は、ドロップダウンに表示する項目数を指定します。JSON の数値 25 を指定するとインポートに失敗します。プラットフォームのパラメータースロットでは、TS 式の文字列リテラルが必要です。

6. 表示ラベルでソートします。 このセレクター用に特別にデータソースを作成する場合は、text で参照されるフィールドで結果をソートしてください。OData 型のデータソースでは、そのフィールドの orderBys エントリーを追加します。フロー型のデータソースでは、返す前にコード内で配列をソートします。Name を表示する task_status_dd セレクターのデータソースは、Name の昇順でソートする必要があります。これにより、ユーザーには挿入順やデータベースから返された順ではなく、アルファベット順のオプションがすぐに表示されます。references/selectors.md → 主なポイントを参照してください。

7. 全文検索の 3 点セットの契約。 データソースがこのセレクターを支えるために特別に用意されている場合に適用されます。他のフローやアクションでも使用される単独のデータソースは対象外です。次の 3 つの要件は相互に連携しており、いずれか 1 つでも欠けると、ドロップダウンの組み込み検索が正常に動作しないように感じられます。

   1. データソースで full_text_search を inParam として宣言する — ID は正確に full_text_search、type: "string"、required: false とします。
   2. データソースで表示ラベルのフィールド（text が参照するフィールド）に条件付き contains フィルターを適用する。$utils.isDefined($datasource.inParams.full_text_search) を条件に指定し、入力が空の場合はフィルターを無効にします。OData 型では、hasCondition: true と条件式を指定した標準形 contains(<LabelField>, ${$utils.odata.formatString(...)}) を使用します。フロー型では、getListFlow のコード内で if ($utils.isDefined($flow.inParams.full_text_search)) { rows = rows.filter(r => r.<LabelField>.toLowerCase().includes((... as string).toLowerCase())); } のようにガードします。
   3. datasourceConfig.configParameters エントリーを介して、セレクターの $selector.fullTextSearch をデータソースの full_text_search 入力に接続する。そのエントリーの value は "$selector.fullTextSearch" とします。

   top: "25" と「表示ラベルでソート」を組み合わせることで、オートコンプリートの基本動作を実現できます。要件を省くと、ユーザーが入力してもドロップダウンが反応しないように感じられます。references/selectors.md → 全文検索の接続を参照してください。

8. getListFlow ↔ getByKeysFlow のキー変換の一貫性。 ユーザーがドロップダウンを開いたとき、プラットフォームはドロップダウンにデータを設定するために getListFlow を呼び出し、以前に保存された値について表示可能なレコードを再取得するために getByKeysFlow を呼び出します。getListFlow でキー変換（例：formatKey による ParentOfTarget → Parent of target への変換など、その他のラベルの調整も含む）を適用する場合、getByKeysFlow でも同じ変換を適用する必要があります。そうしないと、保存した選択値を getByKeys 経由で再取得したときに生の enum ID が返され、編集時にはドロップダウンコントロールに ParentOfTarget が表示される一方、再読み込み後には Parent of target が表示されます。formatKey／capitalize ヘルパー関数は、それぞれのフローの code 本文内にネストされた関数宣言として定義されています。プラットフォームは各フローを個別にコンパイルし、スコープを共有しないため、両方のフローで同じ定義を重複させてください。OData 型のバックエンドでこの問題が発生することはまれです（getByKeys は keyDef から自動生成され、生の列を選択します）。ただし、OData クエリオプションに計算列や列のエイリアスが含まれる場合は、リスト取得時に使うプロジェクションをキー検索時に使うプロジェクションと一致させる必要があります。references/selectors.md → getList ↔ getByKeys のキー変換の一貫性を参照してください。

9. vars／inParams／outParams にカスタム enum の FQN を指定しないでください。 セレクターはパラメーター宣言内の $types.<Package>.e_<enum> を解決できません。これらのフィールドはプリミティブ型（文字列値の enum には string、数値の enum には number）として宣言し、フローコード内で使用時にキャストしてください。バックエンドの outParams.result.objectTypeDef[Value] は、作成者が最も enum 型で指定したい箇所であるため、この問題は enum を使うセレクターで特に発生しやすくなります。

10. 隣接する *Config キーは明示的に null にします。 customOptionsConfig、actionConfig、onInitFlowConfig、およびその他の無効なサブ設定は、標準的なデータソース接続型セレクターでは明示的に null のままにしてください。構造的な差分比較ではこの慣例に従ってください。既存のセレクターコンポーネントでは、隣接するすべてのスロットが存在し、null に設定されています。

11. 呼び出し階層への準拠。 セレクターコード（onInitFlowConfig および flows[] の各エントリー）からは、$flows.<Package>.<fn> 経由で関数を呼び出します。その関数が、CRUD アクションの呼び出しを $apis.<Package>.FootprintApi.extendedActions.<action_name>({...}) でラップします。セレクターコードからアクションを直接呼び出さないでください。../datex-studio-runtime/calling-conventions.mdを参照してください。

12. ホストコントラクトの監査。 このセレクターをマウントするホスト（フォームフィールド、ハブのフィルタードロップダウン、グリッドのフィルターセル）はすべて、完全な configParameters コントラクトを宣言します。セレクターが宣言するすべての inParam について、未使用のものも含めて、ホスト側にエントリーを設け、value: null を設定してください。component-wiring-check を実行し、両側の参照コントラクト（外側のホスト → セレクターのコントラクトと、内側のセレクター → バックエンドデータソースのコントラクト）を監査してください。セレクターが読み取るバックエンドのすべての inParam（full_text_search を含む）について、セレクター側に明示的な configParameters エントリーが必要です。自動配線はありません。../component-wiring-check/references/component-wiring.mdを参照してください。

フェーズ 4：検証してプッシュする

# Validate the body locally against the branch. Exit 1 = validation found errors
# (read validation_errors, fix body.json, re-run) — not a broken CLI. Do not push on exit 1.
dxs configuration validate selector -b <branchId> -D body.json

# For a new selector
dxs configuration upsert selector -b <branchId> -D body.json

# For modify-existing (round-trip — never skip the jq extract)
dxs configuration get selector <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json
# ... edit body.json ...
dxs configuration upsert selector -b <branchId> -D body.json

検証では、必須フィールドの不足、不正なパラメーターディスクリプターの形式、未定義のフロー ID 参照、参照エラーを検出してからプッシュできます。ただし、コンポーネントバリアントの規則（-footprintDatasource.json を指定したセレクターはスキーマ検証に合格しますが、アップロード時または実行時に失敗します）、並べ替えられていないオプションのバグ、未完成の全文検索コントラクト、getList ↔ getByKeys 間のキー変換の不一致は検出しません。これらは動作上の問題であり、アップロード時の検証または実行時にドロップダウン上でのみ表面化します。プッシュする前に、以下に埋め込まれた事前チェックリストを確認してください。

フェーズ 5：Studio で確認（任意）

通常のマウント方法（フォームフィールド、ハブのフィルタードロップダウン、グリッドのフィルターセル）でセレクターを開き、次を確認します。

• オプションがバックエンドのデータソースから取得されます。空ではなく、formatKey が実行されるべき場合に列挙型の生の ID が表示されることもなく、重複もありません。
• オプションが表示ラベルのフィールド（text が参照するフィールド）でアルファベット順に並びます。これにより、バックエンドの orderBys またはコード内のソートが反映されたことを確認できます。
• 検索ボックスに入力すると、オプションがリアルタイムに絞り込まれます。これにより、全文検索の契約を構成する 3 つの要素（データソースでの inParam の宣言、条件付きフィルターの適用、configParameters を介した $selector.fullTextSearch のセレクターへの接続）がすべて設定されていることを確認できます。
• 選択を保存し、フォーム／ダイアログを閉じてから再度開きます。保存された Value が再読み込みされ、getListFlow で表示されるものと同じ表示ラベルで描画されます（getByKeysFlow の Key が一致していることを確認できます）。
• マウントの moduleId でセレクターを解決できます。インポートログに Referenced configuration <name> does not exist エラーがありません。

実行中のアプリを利用できない場合は、（修正済みの jq .json 抽出パターンを使用して）設定を再取得し、body.json との差分を確認してプッシュが反映されたことを確かめます。

プッシュ前チェックリスト

プッシュ前に、このチェックリストを確認します。簡易版：

1. コンポーネントのバリエーション。 バックエンドは -datasource.json（configurationTypeId: 6）であり、-footprintDatasource.json（configurationTypeId: 19）ではありません。内部のクエリタイプは flows または oDataQuery のどちらでもかまいません。
2. ファイルの基本事項。 サフィックスは -selector.json、configurationTypeId: 7、referenceName は通常 _dd で終わります。さらに、共通チェック（../datex-studio-conventions/universal-checklist.md）も確認します。
3. データソース接続の契約。 configId と moduleId が実在するデータソースを解決します（moduleId = データソースのパッケージ）。datasourceKeyDef はデータソースの keyDef と一致します。configOutParameters は、完全なパラメータ記述子の定型項目を含めて outParams と一致します。
4. 表示式。 text が $option.entity.<field> 上の実在するフィールドを参照します。
5. top は文字列（"25"）であり、数値ではありません。
6. データソースが表示ラベルのフィールドでソートされます（OData の orderBys またはフローコード内のソート）。初期状態でオプションがアルファベット順に並びます。
7. バックエンドのデータソースがこのセレクター専用の場合は、全文検索を完全に設定します。 必要な要素は 3 つです。バックエンドで full_text_search inParam（string、required: false）を宣言すること、$utils.isDefined を条件として表示ラベルのフィールドに contains フィルターを適用すること、configParameters を介してセレクターの $selector.fullTextSearch をバックエンドの full_text_search に接続することです。
8. getListFlow と getByKeysFlow の Key 変換が一致していること。 getListFlow で Key 変換（formatKey など）を行う場合は、getByKeysFlow でも同じ変換を行います。ヘルパー関数（formatKey、capitalize）は両方の code 本文内に複製します。フローはそれぞれ独立してコンパイルされます。
9. vars／inParams／outParams に $types.<Package>.e_<enum> がないこと。 パラメータ層ではプリミティブ型のみを使用し、フローコード内の使用箇所でキャストします。
10. 同階層の *Config キーが明示的に null であること。 標準のデータソース接続セレクターでは、customOptionsConfig、actionConfig、onInitFlowConfig などは null のままにします。
11. 呼び出し層の要件を満たしていること。 セレクターのコードは $flows.<Package>.<fn> 経由で関数を呼び出します。関数は $apis.<Package>.FootprintApi.extendedActions.<action_name>({...}) 経由で CRUD アクションをラップします。セレクターからアクションを直接呼び出しません。
12. ホストに完全な configParameters 契約が設定されていること。 セレクターが宣言するすべての inParam に、ホスト（フォームフィールド／ハブのフィルター／グリッドのフィルターセル）でエントリがあります。未使用のものは value: null を使用します。component-wiring-check で監査します。
13. 内部データソースの契約。 セレクター自身の datasourceConfig.configParameters で、バックエンドのデータソースが宣言するすべての inParam（full_text_search を含む）をカバーします（自動接続はされません。value: "$selector.fullTextSearch" の明示的なエントリが必要です）。

よくある間違い

間違い	修正方法
セレクターが -footprintDatasource.json（FPDS、configurationTypeId: 19）を参照している	プラットフォームの厳格なルールとして、参照先は -datasource.json（configurationTypeId: 6）である必要があります。FPDSにデータがある場合は、それを呼び出すフロー型の -datasource.json でラップしてください。セレクターからFPDSを直接参照してはいけません。
コンポーネントのバリアントとクエリの種類を混同し、「ODataドロップダウンならFPDSが参照先」と思い込んでいる	セレクターが参照するのはコンポーネントのバリアントであり、クエリの種類ではありません。ODataを参照するドロップダウンも問題ありません。ただし、ODataクエリを定義するのはFPDSではなく -datasource.json（type: "oDataQuery"）です。
top: "25"（TS式の文字列）ではなく、top: 25（JSON数値）を指定している	スロットが受け取るのは文字列リテラルです。数値の 25 はインポートに失敗します。必ず引用符で囲んでください。
<field> がデータソースの outParams に存在しないのに、text: "$option.entity.<field>" を指定している	text は $option.entity に対して評価されます。選択肢の行の形状は、データソースの outParams[result].objectTypeDef によって決まります。実際に存在するフィールドを選ぶか、データソースにそのフィールドを追加してください。
参照先データソースが選択肢を挿入順で返すため、ユーザーからドロップダウンが「ランダム」だと苦情が出る	表示ラベルのフィールドに対して、orderBys（OData）を追加するか、コード（フロー型）でソートしてください。ユーザーは選択肢がアルファベット順に並ぶことを期待します。
fullTextSearch は表示されるが、入力した文字で選択肢が絞り込まれない	3つの要素からなる契約が正しく設定されていません。次を確認してください。（1）参照先で full_text_search inParam を宣言している。（2）参照先で表示ラベルのフィールドに条件付きフィルターを適用している。（3）セレクターの datasourceConfig.configParameters に、value: "$selector.fullTextSearch" を持つ full_text_search エントリーがある。いずれの要素も自動で連携されません。
getListFlow ではKeyのプロジェクションに formatKey(key) を使っているが、getByKeysFlow は元のcamelCaseの列挙型IDを返している	保存した選択値を再度読み込むと、ドロップダウンの選択肢には整形された値が表示される一方で、保存値は未加工のまま表示されます。getByKeysFlow.code 内にも同じ formatKey 式（およびヘルパー関数の定義）を複製してください。フローは個別にコンパイルされ、スコープを共有しません。
セレクターの vars／inParams／outParams で $types.<Package>.e_<enum> を参照している	UIコンポーネントは、パラメーター層でカスタム列挙型の完全修飾名（FQN）を解決できません。プリミティブ型（文字列値の列挙型には string、数値の列挙型には number）として宣言し、フローコード内で使用するときにキャストしてください。
datasourceKeyDef が参照先の keyDef と異なる（IDまたは型が異なる）	getByKeysFlow を通じた保存済み選択値の再ハイドレーションに失敗するか、誤ったレコードが返されます。2つの keyDef は完全に一致させる必要があります。
configOutParameters の記述子の定型情報が {id, type} だけに省略されている	プラットフォームでは、各エントリーに完全なプロパティ記述子の形状（required、description、oneOf、fromBaseConfiguration、objectTypeDef、objectType、isCollection、isSecured、isConstant、constantValue）が必要です。参照先の outParams と同じ形状を使用してください。
セレクターの datasourceConfig の moduleId に、データソースのパッケージではなくセレクターのパッケージを設定している	コンポーネント間参照のルールでは、moduleId は常に参照先のパッケージです。データソースが登録されている場所を指定してください。../component-wiring-check/references/component-wiring.md を参照してください。
セレクター独自の vars／inParams／outParams フィールドを、トップレベルで宣言せずにフローコード内で記述している	インポートエラーが発生します。Property 'vars' does not exist on type 'ISelector'。各var／inParam／outParamを、標準のプロパティ記述子の形状で、対応するトップレベル配列に宣言してください。
兄弟の *Config スロットが省略されている（例：datasourceConfig だけを設定し、customOptionsConfig／actionConfig／onInitFlowConfig がすべて欠落している）	既存のセレクターでは、構造差分を取るためにすべての兄弟スロットを残し、null に設定しています。この規約に合わせてください。
セレクターのコードからアクションを直接呼び出している	UI層のルールでは、セレクターが呼び出せるのは関数のみです。関数内で $apis.<Package>.FootprintApi.extendedActions.<action_name>({...}) を使ってアクションをラップしてください。
dxs configuration get -O envelope.json の出力を、そのまま dxs configuration upsert -D envelope.json に渡している	設定の内容が警告なく破壊されます。編集前に必ず jq .json envelope.json > body.json を実行してください。上記の「往復ルール」を参照してください。
description が100文字を超えている	SQLの列制限により、プッシュ時の検証に失敗します。短くしてください。
（セレクターがドロップダウンインジケーターの場合）referenceName が _dd で終わっていない、またはファイル名のベース名と一致していない	規約の不一致により、検索や、_dd の接尾辞を期待する後続の呼び出し元で問題が発生します。スネークケースを使用し、該当する場合は _dd の接尾辞を付け、ファイル名のベース名と一致させてください。
編集後、post-edit-verification を実行して、説明文／JSON／スキーマの違反を検出してください。最終確認では、component-validator を実行してください。