generating-custom-lightning-type

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

• 構造化された入力／出力用のカスタム Lightning 型（CLT）を作成する
• Lightning Platform 用の JSON Schema ベースの型定義を生成する
• Einstein Agent アクション用に CLT を設定する
• カスタム UI 用のエディターおよびレンダラー設定を行う
• ウィジェット／モザイク／フラグメントのレンディションを備えた CLT を作成する
• カスタム 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" フィールドを絶対に含めないでください
  • このフィールドが有効な JSON Schema の $schema 宣言であっても、Salesforce CLT バリデーターは含まれているスキーマを拒否します。
• ルートオブジェクトスキーマには、必ず次を含めてください。
  • "type": "object"
  • "title"
  • "lightning:type": "lightning__objectType"
  • "unevaluatedProperties": false
• CLT メタスキーマでは "unevaluatedProperties" は 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 は追加しないでください。

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 参照パターンを使います。
     • 別の CLT を参照するには "lightning:type": "c__<CLTName>" を使います。
     • 参照先の 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 というプロパティがある場合は、value が実際のプロパティでない限り、{!$attrs.value} ではなく {!$attrs.temperature} を使います。
   • プロパティレベルのオーバーライドパターン（個々のフィールド向け）：
     • 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>" }。または、editor.layout で lightning/propertyLayout と attributes.property = "<listPropertyName>" を使い、デフォルトのリスト編集を行います。
   • レイアウトパターン：
     • 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 を使います。
   • ルートオーバーライドパターン（全面的にカスタムのレンダリング UI で最もよく使われます）：
     • renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
     • スキーマデータをカスタムレンダラーコンポーネントの属性にバインドする場合は、属性マッピングで {!$attrs.<name>} を使います。
     • 重要： {!$attrs.propertyName} のような属性マッピングでは、型スキーマに実際に存在するプロパティを参照しなければなりません。存在しないプロパティを参照すると、検証に失敗します。
     • 型の一致： 属性値は、コンポーネントで期待される型と一致していなければなりません。たとえば、文字列属性を期待するコンポーネントに整数を渡すと、検証に失敗します。
   • ウィジェットレンダラーパターン（ウィジェット形式での表示向け）：
     • 使用するタイミング： ユーザーが CLT に対して「mosaic」、「widget」、「fragment」、または「cross-platform rendering」を求めた場合に使います。
     • 構造： renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }
     • 必須のワークフロー：
       • 中止してください： ウィジェットレンダラーを自分で作成しないでください。
       • 最初に必ず行うこと： 作業を進める前に、このスキルのディレクトリにある参照ファイル references/widget-rendition.md を取得しなければなりません。
       • 生成した CLT スキーマを基準スキーマとして、widget-rendition.md に記載されたワークフロー全体に従います。
       • 参照ファイル widget-rendition.md には、ウィジェット生成ワークフロー全体が記載されています。これには、discoverUiComponents による UEM ブロックの検出、getUiComponentSchemas の呼び出し、UEM ツリーの構築、renderer.json の作成が含まれます。
       • 参照ファイル widget-rendition.md を先に取得せずに、ウィジェット形式での表示を生成しようとしないでください。
   • プロパティレベルのオーバーライドパターン：
     • 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/）を使います。
6. カスタム LWC コンポーネントを設定する（カスタムコンポーネントを使用する場合）
   • 重要： エディター／レンダラーの設定で参照されるカスタム 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 セクションにある実際のプロパティを参照していることを確認します
非推奨キーを使用しているため 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" フィールドが含まれていない