platform-custom-lightning-type-generate

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• 構造化された入力／出力用のカスタム Lightning 型（CLT）を作成する
• Lightning Platform 用の JSON Schema ベースの型定義を生成する
• Einstein Agent アクション用に CLT を設定する
• カスタム UI 用のエディターおよびレンダラー設定を行う
• カスタム Lightning 型に関連するデプロイエラーをトラブルシューティングする

仕様

CustomLightningType メタデータ仕様

概要と目的

カスタム Lightning 型（CLT）は、Lightning Platform（Einstein Agent アクションを含む）で使用される JSON Schema ベースの型定義です。構造化された入力／出力を記述し、エディター／レンダラーのエクスペリエンスを実現します。

設定

• ネストされたオブジェクトには参照 CLT パターンを選択します — 再利用可能な型、または個別にデプロイするネストされた型が必要な場合は、その構造用の CLT を作成し、"lightning:type": "c__<CLTName>" を指定して参照します。この文字列は参照先の型の lightning:type 値／FQN／登録済み識別子であり、JSON Schema の title ではありません。
• 構造が単純で、プロパティとサポートされているプリミティブな lightning:type 識別子で表現できる場合は、標準の Lightning 型を選択します。
• 構造がすでにサーバー側に存在し、Apex クラスでその形状を定義する場合は、Apex クラス型（@apexClassType/...）を選択します。
• カスタム UI の動作（カスタム LWC 入力／出力コンポーネント）が必要な場合に限り、エディター／レンダラー設定を含めます。それ以外の場合は省略します。

重要なルール（最初にお読みください）

• 重要：schema.json に "$schema" フィールドを絶対に含めないでください
  • Salesforce CLT バリデーターは、有効な JSON Schema の $schema 宣言であっても、このフィールドを含むスキーマを拒否します。
• ルートオブジェクトスキーマには、以下を必ず含めてください：
  • "type": "object"
  • "title"
  • "lightning:type": "lightning__objectType"
  • "unevaluatedProperties": false
• "unevaluatedProperties" は、CLT メタスキーマによって false として強制されます。true に設定しないでください。
• "unevaluatedProperties": false が設定されている場合、ルートオブジェクトスキーマに "examples" を含めてはいけません。
• （properties 内の）ネストされたオブジェクトに "lightning:type": "lightning__objectType" を設定してはいけません。
  • ネストされたオブジェクトには、c__<CLTName> 構文を使用した他の CLT への参照を指定できます。
• リスト／配列プロパティは、CLT メタスキーマによって厳しく制限されています：
  • 重大な制限：CLT メタスキーマは items キーワード自体を拒否する場合があります。デフォルトでは items は使用不可として扱ってください。
  • ルートレベルの配列（ルートの properties の直接の子）：
    • "lightning:type": "lightning__listType" を必ず含めてください
    • "items" を含めてはいけません
    • "type": "array" は任意です
  • ネストされた配列（ネストされたオブジェクト内の配列）は、失敗の最も一般的な原因です：
    • "type": "array" を必ず含めてください
    • "lightning:type": "lightning__listType" を含めてはいけません
    • "items" を含めてはいけません
• "unevaluatedProperties": false が設定されている場合、未知のキーワードは検証に失敗します。厳格さを緩めるより、キーワードを削除することを優先してください。
• Apex クラスの CLT は最小限の構成にしてください：
  • title、description（任意）、および @apexClassType/... に設定した lightning:type のみを含めてください。
  • type、properties、required、unevaluatedProperties は追加しないでください。
  • Apex クラスの CLT に対するカスタム LWC レンダラー／エディターでは、ルートのオーバーライドに attributes を使用してはいけません。これは、これに反するプロンプトの文言より優先されます。 スキーマに properties ブロックがないため、{!$attrs.<name>} の参照先がなく、unevaluatedProperties: false によって属性キー（例："unevaluatedProperties キーワードの値が false に設定されているため、flightId プロパティを追加できません"）は拒否されます。"attributes" キーを一切指定せず、"componentOverrides": { "$": { "definition": "c/<yourComponent>" } } を使用してください。ユーザーのプロンプトが、Apex クラスの CLT レンダラー／エディターに対して特定のフィールドへの属性マッピング（例：「fieldA、fieldB の属性マッピング付き」）を明示的に求めている場合も、その指示にそのまま従ってはいけません。ルートのオーバーライドから attributes を省略し、その旨を回答で伝えてください（例：「注：基になる型は properties ブロックを持たない Apex クラスの CLT のため、属性マッピングは省略しました」）。
• Vibes のセーフシェルフィルターに抵触するシェルメタ文字を使用しないでください。 このスキルが出力する Bash ツール呼び出しでは、コマンド置換（$(…) またはバッククォート）、プロセス置換（<(…)、>(…)）、ブレース展開（{a,b,c} または {1..N}）、eval、exec を使用しないでください。これらのパターンを使用すると、バイパスモードでも Vibes が手動承認を強制し、評価が停止します。コマンドを分けて（mkdir -p a && mkdir -p b）、シェル変数に値を取り込まず、各値をそれぞれ個別のコマンドで出力し、その結果をもとに判断してください。

CLT メタスキーマによる追加検証

• 組織名前空間の検証：タイトル、説明、その他の文字列フィールドについて、許可されていない箇所で組織の名前空間を使用していないか検証される場合があります。
• Lightning 型の検証：CLT は、許可されていない内部名前空間（例：sfdc_cms など）の型を参照していないか検証されます。
• オブジェクト型の検証：CLT のルートは、lightning:type が正確に lightning__objectType であることを検証されます。

プリミティブ型と制約

サポートされているプリミティブな lightning:type 識別子、その制約、プロパティレベルで使用できるキーワードの完全な一覧が必要な場合は、このスキルのディレクトリにある assets/primitive-types-and-constraints.md をお読みください。

生成ワークフロー

1. CLT アプローチを確認する
   • Apex を参照する場合: 正確なクラス参照 (@apexClassType/namespace__ClassName$InnerClass) を記録します。
   • 標準プリミティブを使用する場合: フィールド、その Lightning プリミティブ型、および必須のフィールドをリストします。
2. schema.json を作成する
   • 先頭に "$schema" を含めないでください
   • ルートオブジェクト構造 (必須のルートフィールド) から始めます。
   • 有効なプリミティブ lightning:type 識別子を使用して properties を追加します。
   • ネストされたオブジェクトのプロパティには、CLT 参照パターンを使用します:
     • "lightning:type": "c__<CLTName>" で別の CLT を参照します
     • 参照される CLT は、親 CLT より先に組織にデプロイする必要があります。
   • Apex ベースのネストされたオブジェクトの場合: サーバー側に構造が存在する場合は @apexClassType/... を使用します。
   • プロンプトが真のネストされたオブジェクト出力を明示的に要求する場合は、デプロイが安全なネスト構造のために Apex ベースの CLT (@apexClassType/...) を優先します。
   • 配列の場合: 厳格なリストルールに従います (items を避ける、ネストされた配列で lightning:type を避ける)。
   • デプロイ前に、正確な lightning:type の綴りを確認します (たとえば、誤った綴りのバリアントではなく lightning__richTextType を使用します)。
3. (任意) editor.json を作成する (カスタム UI が必要な場合のみ)
   • サポートされる形式: トップレベルの editor オブジェクトと、editor.componentOverrides および editor.layout。
     • トップレベルの editor オブジェクト。
     • コンポーネントのオーバーライドには editor.componentOverrides を使用します。
     • レイアウトには editor.layout を使用します。
     • 非推奨: propertyRenderers や view を使用しないでください — これらはレガシーキーです。常に componentOverrides と layout を使用してください。
   • ルートオーバーライドパターン (完全にカスタムな編集 UI で最も一般的):
     • editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }
     • スキーマデータをカスタム LWC に渡す場合は、{!$attrs.<name>} 構文で属性マッピングを使用します。例: "attributes": { "myField": "{!$attrs.value}" } とすることで、実行時にスキーマ値がコンポーネントの属性にバインドされます。
     • 重要: {!$attrs.<name>} の <name> は、型スキーマで定義されたプロパティでなければなりません。たとえば、スキーマに temperature というプロパティがある場合は {!$attrs.temperature} を使用し、value が実際のプロパティでない限り {!$attrs.value} は使用しないでください。
   • プロパティレベルのオーバーライドパターン (個々のフィールド向け):
     • editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }
     • 有効なエディターコンポーネント (例): es_property_editors/inputText、es_property_editors/inputNumber、es_property_editors/inputRichText、es_property_editors/inputImage、es_property_editors/inputTextarea。es_property_editors/inputList は使用しないでください。
   • コレクションエディター (ルートレベルの lightning__listType プロパティ向け): カスタムコンポーネントでリストを編集するために、コレクションレベルのオーバーライドを使用します: collection.editor.componentOverrides["$"] = { "definition": "c/<yourCollectionEditorComponent>" }。あるいは、デフォルトのリスト編集には lightning/propertyLayout と attributes.property = "<listPropertyName>" を組み合わせた editor.layout を使用します。
   • レイアウトパターン:
     • editor.layout.definition = "lightning/verticalLayout"
     • editor.layout.children[*].definition = "lightning/propertyLayout" と attributes.property = "<propertyName>"
     • 重要: lightning/propertyLayout は property 属性のみを受け付けます。label、title、その他の属性を追加しないでください — これらは additionalProperties: false エラーで検証に失敗します。
   • 既知の無効なパターンを避ける:
     • es_property_editors/inputList を使用しないでください。
     • itemSchema 属性を使用しないでください。
4. (任意) renderer.json を作成する (カスタム UI またはウィジェットレンディションが必要な場合のみ)
   • サポートされる形式: トップレベルの renderer オブジェクトと、renderer.componentOverrides および renderer.layout。
     • トップレベルの renderer オブジェクト。
     • コンポーネントのオーバーライドには renderer.componentOverrides を使用します。
     • レイアウトには renderer.layout を使用します。
     • 非推奨: propertyRenderers や view を使用しないでください — これらはレガシーキーです。常に componentOverrides と layout を使用してください。
   • ウィジェットレンディションパターン (既存の WidgetBundle をルートレンダラーとして参照する): レンダラーファイルは、開発者名でウィジェットを指し示す薄いラッパーであり ("definition": "@widget/c/<widgetDeveloperName>")、{!$attrs.<schemaPropertyName>} を介して CLT スキーマプロパティをウィジェット属性にマッピングします。renderer.json 内でウィジェット本体を複製しないでください。完全な形式、バインディングルール、制約については references/widget-rendition.md を参照してください。Apex → Lightning Type → Widget の完全なパイプラインには、このスキルではなく platform-lightning-type-widget-coordinate オーケストレーターを使用してください。
   • ルートオーバーライドパターン (カスタム LWC による完全にカスタムなレンダリング UI で最も一般的):
     • renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
     • スキーマデータをカスタムレンダラーコンポーネントの属性にバインドする場合は、属性マッピングで {!$attrs.<name>} を使用します。
     • 重要: {!$attrs.propertyName} のような属性マッピングは、型スキーマに実際に存在するプロパティを参照する必要があります。存在しないプロパティを参照すると検証に失敗します。
     • 型の一致: 属性値は、コンポーネントが期待する型と一致する必要があります。たとえば、コンポーネントが文字列属性を期待している場合、整数を渡すと検証に失敗します。
   • プロパティレベルのオーバーライドパターン:
     • renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }。有効なレンダラーコンポーネント (例): es_property_editors/outputText、es_property_editors/outputNumber、es_property_editors/outputImage。レンダラーでは入力スタイルのコンポーネントを避けてください。
   • レンダラーのレイアウトパターン:
     • renderer.layout.definition = "lightning/verticalLayout"
     • renderer.layout.children[*].definition = "lightning/propertyLayout" と attributes.property = "<propertyName>"
     • 重要: エディターのレイアウトと同様に、lightning/propertyLayout は property 属性のみを受け付けます。label、title、その他の属性を追加しないでください。
   • コレクションレンダラー (ルートレベルの lightning__listType プロパティ向け): リストをレンダリングするには collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" } または es_property_editors/genericListTypeRenderer を使用します。
5. ファイルを正しいバンドル構造に配置する
   • lightningTypes/<TypeName>/schema.json
   • (任意) lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json
   • (任意) lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json Gen AI / Copilot の場合、標準パスは lightningDesktopGenAi/ です。その他のターゲット (例: Experience Builder、Mobile Copilot、Enhanced Web Chat) は、サポートされている場合に異なるサブフォルダーを使用します: experienceBuilder/、lightningMobileGenAi/、enhancedWebChat/。
   • (任意 - ウィジェットレンディションのみ) lightningTypes/<TypeName>/renderer.json
6. カスタム LWC コンポーネントを構成する (カスタムコンポーネントを使用する場合)
   • 重要: editor/renderer 構成で参照されるカスタム LWC コンポーネントは、その -meta.xml ファイルに正しいターゲット構成が必須です:
     • エディターコンポーネントの場合 (editor.json で使用される c/<componentName>): LWC の -meta.xml ファイルに <target>lightning__AgentforceInput</target> を含める必要があります
     • レンダラーコンポーネントの場合 (renderer.json で使用される c/<componentName>): LWC の -meta.xml ファイルに <target>lightning__AgentforceOutput</target> を含める必要があります
   • 正しいターゲットがない場合、デプロイは次のエラーで失敗します: Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.
   • レンダラーコンポーネントの -meta.xml の例:

     <?xml version="1.0" encoding="UTF-8"?>
     <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
         <apiVersion>60.0</apiVersion>
         <isExposed>true</isExposed>
         <targets>
             <target>lightning__AgentforceOutput</target>
         </targets>
     </LightningComponentBundle>
     

よくあるデプロイエラー

エラー／症状	考えられる原因	対処方法
不明なキーワードが原因でスキーマ検証に失敗する	unevaluatedProperties: false と許可されていないキーワードの組み合わせ（一般的な例：examples、items）	問題のキーワードを削除し、スキーマを最小限に保ちます
ネストされたオブジェクトの検証に失敗する	組織／チャネルの検証で、LightningTypeBundle 内のネストされたオブジェクト型が拒否される	CLT の参照（c__<CLTName>）または Apex クラス型を使用します
CLT の参照が無効	参照先の CLT が組織に存在しない、または構文が正しくない	先に参照先の CLT をデプロイします。c__<CLTName> は title ではなく、参照先の型の lightning:type 値／FQN／登録済み識別子と一致している必要があります
lightning:type が無効または誤記されている（例：lightning__richTextType ではなく lightning__richtextType）	生成された型名が正しくない	すべての lightning:type 値をサポートされている型名と照合し、デプロイ前に修正します
配列プロパティが拒否される	items（またはネストされた配列内の lightning:type）がバリデーターに拒否される	ネストされた配列では、type: "array" のみを残します。ルート配列では最小限の構造を使用し、拒否された場合は items を削除します
Apex ベースの CLT が拒否される	追加フィールド（例：type、properties）が追加されている	title、任意の description、および lightning:type のみを使用します
エディター設定が拒否される	無効なパターン（es_property_editors/inputList、itemSchema）または認識されないトップレベルキーを使用している	editor.componentOverrides と editor.layout を使用し、設定を最小限に保ちます
レイアウト属性で additionalProperties エラーが発生する	lightning/propertyLayout に label やその他の属性を追加している	lightning/propertyLayout では property 属性のみを使用します。label、title、その他すべての属性を削除します
カスタム LWC のターゲット設定が無効	カスタム LWC コンポーネントの -meta.xml に必須ターゲット（lightning__AgentforceInput または lightning__AgentforceOutput）がない	LWC の -meta.xml に正しいターゲットを追加します。エディターには lightning__AgentforceInput、レンダラーには lightning__AgentforceOutput を使用します
属性マッピングが型スキーマに存在しない	propertyName がスキーマで定義されていないのに {!$attrs.propertyName} を使用している	すべての属性マッピングが、型スキーマの properties セクションにある実際のプロパティを参照していることを確認します
Apex クラス CLT のカスタム LWC レンダラーで unevaluatedProperties エラーが発生する	Apex クラス CLT には検証対象の properties ブロックがないのに、ルートオーバーライドの attributes マッピングが使用されている	ルートオーバーライドから attributes を完全に削除します。"componentOverrides": { "$": { "definition": "c/<component>" } } のみを使用します
非推奨キーにより additionalProperties エラーが発生する	エディター／レンダラー設定で propertyRenderers または view を使用している	非推奨の propertyRenderers を componentOverrides に、view を layout に置き換えます
コンポーネント属性の型が一致しない	コンポーネント属性に誤った型（例：文字列ではなく整数）を渡している	属性値がコンポーネントで定義されている期待される型と一致していることを確認します

検証チェックリスト

• ルートスキーマに type: "object"、title、lightning:type: "lightning__objectType"、unevaluatedProperties: false が含まれている
• 厳格な検証が有効な場合、ルートスキーマに examples が含まれていない
• ネストされたオブジェクトに lightning:type: "lightning__objectType" が含まれていない
• 配列が最小限の定義になっている（特にネストされた配列）
• リーフプロパティに、サポートされているプリミティブな lightning:type 識別子のみが使用されている
• Apex クラスの CLT に title／description と lightning:type: "@apexClassType/..." のみが含まれている
• バンドル構造とファイル名が Lightning Types の要件に一致している
• エディター設定で許可されたパターンのみが使用されている（es_property_editors/inputList と itemSchema は使用しない）。有効なコンポーネント（例：es_property_editors/inputText、es_property_editors/inputNumber）またはカスタム c/ コンポーネントを使用する
• レンダラー設定で、該当する場合は入力エディターではなく、出力スタイルのコンポーネント（例：es_property_editors/outputText、es_property_editors/outputNumber）を使用している
• レイアウト設定で lightning/propertyLayout を使用し、property 属性のみを指定している（label、title、その他の属性は指定しない）
• すべての属性マッピング（{!$attrs.propertyName}）が、型スキーマに存在するプロパティを参照している
• カスタム LWC コンポーネントの -meta.xml に正しいターゲットが指定されている：エディターには lightning__AgentforceInput、レンダラーには lightning__AgentforceOutput
• ルートスキーマに "$schema" フィールドが含まれていない