platform-custom-lightning-type-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此技能

Use this skill when you need to:

Create Custom Lightning Types (CLTs) for structured inputs/outputs
Generate JSON Schema-based type definitions for Lightning Platform
Configure CLTs for Einstein Agent actions
Set up editor and renderer configurations for custom UI
Create CLTs with widget/mosaic/fragment rendition
Troubleshoot deployment errors related to Custom Lightning Types

当您需要以下操作时，请使用此技能：

为结构化输入/输出创建Custom Lightning Types (CLTs)
为Lightning Platform生成基于JSON Schema的类型定义
为Einstein Agent操作配置CLTs
为自定义UI设置编辑器和渲染器配置
创建带widget/mosaic/fragment rendition的CLTs
排查与Custom Lightning Types相关的部署错误

Specification

规范

CustomLightningType Metadata Specification

CustomLightningType元数据规范

Overview & Purpose

概述与用途

Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the Lightning Platform (including Einstein Agent actions) to describe structured inputs/outputs and drive editor/renderer experiences.

Custom Lightning Types (CLTs)是基于JSON Schema的类型定义，由Lightning Platform（包括Einstein Agent操作）用于描述结构化输入/输出，并驱动编辑器/渲染器体验。

Configuration

配置

Choose referenced CLT pattern for nested objects - When you need a reusable or separately deployed nested type, create a CLT for that shape and reference it with
```
"lightning:type": "c__<CLTName>"
```
. That string is the referenced type’s lightning:type
value / FQN / registered identifier — not the JSON Schema
```
title
```
.
Choose standard Lightning types when the structure is simple and can be expressed with properties and supported primitive
```
lightning:type
```
identifiers.
Choose Apex class types (
```
@apexClassType/...
```
) when the structure already exists server-side and you want the Apex class to define the shape.
Include editor/renderer config only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.

为嵌套对象选择引用CLT模式 - 当您需要可复用或独立部署的嵌套类型时，为该结构创建CLT，并使用
```
"lightning:type": "c__<CLTName>"
```
引用它。该字符串是被引用类型的**
```
lightning:type
```
值/完全限定名/注册标识符** — 而非JSON Schema的
```
title
```
。
当结构简单且可通过属性和受支持的原始
lightning:type
标识符表达时，选择标准Lightning类型
当结构已在服务器端存在且希望用Apex类定义其形状时，选择Apex类类型 (
```
@apexClassType/...
```
)
仅在需要自定义UI行为（自定义LWC输入/输出组件）时才包含编辑器/渲染器配置，否则请省略。

Critical Rules (Read First)

重要规则（请先阅读）

CRITICAL: NEVER include the
"$schema"
field in schema.json
- Salesforce CLT validator WILL REJECT schemas with this field, even if it's a valid JSON Schema
```
$schema
```
  declaration.

Root object schemas MUST include:

```
"type": "object"
```
```
"title"
```

"lightning:type": "lightning__objectType"

```
"unevaluatedProperties": false
```

```
"unevaluatedProperties"
```
is enforced as
```
false
```
by the CLT metaschema. Do not set it to
```
true
```
.
Root object schemas MUST NOT include
```
"examples"
```
when
```
"unevaluatedProperties": false
```
is set.
Nested objects (inside
properties
) MUST NOT set
```
"lightning:type": "lightning__objectType"
```
.
- Nested objects can be: references to other CLTs using
```
c__<CLTName>
```
  syntax.
List/array properties are highly restricted by the CLT metaschema:
- CRITICAL LIMITATION: the CLT metaschema may reject the
```
items
```
  keyword entirely. Treat
```
items
```
  as disallowed by default.
- Root-level arrays (direct children of the root
```
properties
```
  ):
  - MUST include
```
"lightning:type": "lightning__listType"
```
  - MUST NOT include
```
"items"
```
  - OPTIONAL
```
"type": "array"
```
- Nested arrays (arrays inside nested objects) are the most common failure:
  - MUST include
```
"type": "array"
```
  - MUST NOT include
```
"lightning:type": "lightning__listType"
```
  - MUST NOT include
```
"items"
```
When
"unevaluatedProperties": false
is set, any unknown keyword will fail validation. Prefer removing keywords over relaxing strictness.

Apex class CLTs are minimal:

Include only

title

description

(optional), and

lightning:type

set to

@apexClassType/...

Do not add

type

properties

required

, or

unevaluatedProperties

重要提示：切勿在schema.json中包含
"$schema"
字段
- Salesforce CLT验证器会拒绝包含此字段的模式，即使它是有效的JSON Schema
```
$schema
```
  声明。

根对象模式必须包含:

```
"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
```
  。

Additional CLT Metaschema Validations

额外CLT元模式验证

Org namespace validation: titles/descriptions and other string fields may be validated to ensure you are not using an org namespace in places that are disallowed.
Lightning type validation: CLTs are validated to prevent referencing internal namespaces (for example, disallowing types from internal namespaces like
```
sfdc_cms
```
where not permitted).
Object type validation: the CLT root is validated to ensure
```
lightning:type
```
is exactly
```
lightning__objectType
```
.

Org命名空间验证：标题/描述和其他字符串字段可能会被验证，以确保您未在不允许的位置使用Org命名空间。
Lightning类型验证：CLTs会被验证以防止引用内部命名空间（例如，在不允许的情况下禁止引用
```
sfdc_cms
```
等内部命名空间的类型）。
对象类型验证：CLT根会被验证以确保
```
lightning:type
```
恰好为
```
lightning__objectType
```
。

Primitive Types & Constraints

原始类型与约束

When you need the full list of supported primitive

lightning:type

identifiers, their constraints, and the allowed property-level keywords, read

assets/primitive-types-and-constraints.md

in this skill's directory.

如需获取受支持的原始

lightning:type

标识符的完整列表、其约束以及允许的属性级关键字，请阅读此技能目录下的

assets/primitive-types-and-constraints.md

。

Generation Workflow

生成流程

Confirm the CLT approach
- If referencing Apex: capture the exact class reference (
```
@apexClassType/namespace__ClassName$InnerClass
```
  ).
- If using standard primitives: list the fields, their Lightning primitive types, and which fields are required.
Draft
schema.json
- DO NOT include
  "$schema"
  at the top
- Start with the root object structure (required root fields).
- Add
```
properties
```
  using valid primitive
```
lightning:type
```
  identifiers.
- For nested-object properties, use CLT Reference pattern:
  - ```
  "lightning:type": "c__<CLTName>"
```
  to reference another CLT
- The referenced CLT must be deployed to the org before the parent CLT.
- For Apex-based nested objects: Use
```
@apexClassType/...
```
  when structure exists server-side.
- If the prompt explicitly requires true nested object output, prefer an Apex-based CLT (
```
@apexClassType/...
```
  ) for deploy-safe nested structures.
- For arrays: follow the strict list rules (avoid
```
items
```
  ; avoid
```
lightning:type
```
  on nested arrays).
- Before deployment, verify exact
```
lightning:type
```
  spellings (for example, use
```
lightning__richTextType
```
  , not misspelled variants).

(Optional) Draft
editor.json
(only if custom UI is required)

Supported shape: Top-level
```
editor
```
object with
```
editor.componentOverrides
```
and
```
editor.layout
```
.
- Top-level
```
editor
```
  object.
- Use
```
editor.componentOverrides
```
  for component overrides.
- Use
```
editor.layout
```
  for layout.
- DEPRECATED: Do NOT use
```
propertyRenderers
```
  or
```
view
```
  — these are legacy keys. Always use
```
componentOverrides
```
  and
```
layout
```
  instead.
Root override pattern (most common for fully custom editing UI):
- ```
editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }
```
- When passing schema data into a custom LWC, use attribute mapping with the
```
{!$attrs.<name>}
```
  syntax: e.g.
```
"attributes": { "myField": "{!$attrs.value}" }
```
  so the runtime binds schema values to your component's attributes.
- CRITICAL: The
```
<name>
```
  in
```
{!$attrs.<name>}
```
  must be a property defined in your type schema. For example, if your schema has a property called
```
temperature
```
  , use
```
{!$attrs.temperature}
```
  , not
```
{!$attrs.value}
```
  unless
```
value
```
  is an actual property.

Property-level override pattern (for individual fields):

editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }

Valid editor components (examples):

es_property_editors/inputText

es_property_editors/inputNumber

es_property_editors/inputRichText

es_property_editors/inputImage

es_property_editors/inputTextarea

. Do not use

es_property_editors/inputList

Collection editor (for root-level

lightning__listType

properties): Use a collection-level override so the list is edited by a custom component:

collection.editor.componentOverrides["$"] = { "definition": "c/<yourCollectionEditorComponent>" }

. Alternatively, use

editor.layout

with

lightning/propertyLayout

and

attributes.property = "<listPropertyName>"

for default list editing.

Layout pattern:

editor.layout.definition = "lightning/verticalLayout"

editor.layout.children[*].definition = "lightning/propertyLayout"

with

attributes.property = "<propertyName>"

CRITICAL:
```
lightning/propertyLayout
```
only accepts the
```
property
```
attribute. Do NOT add
```
label
```
,
```
title
```
, or any other attributes — these will fail validation with
```
additionalProperties: false
```
errors.

Avoid known-invalid patterns:
- Do not use
```
es_property_editors/inputList
```
  .
- Do not use
```
itemSchema
```
  attributes.

(Optional) Draft
renderer.json
(only if custom UI or mosaic rendition is required)
- Supported shape: Top-level
```
renderer
```
  object with
```
renderer.componentOverrides
```
  and
```
renderer.layout
```
  .
  - Top-level
```
renderer
```
    object.
  - Use
```
renderer.componentOverrides
```
    for component overrides.
  - Use
```
renderer.layout
```
    for layout.
  - DEPRECATED: Do NOT use
```
propertyRenderers
```
    or
```
view
```
    — these are legacy keys. Always use
```
componentOverrides
```
    and
```
layout
```
    instead.
- Root override pattern (most common for fully custom rendering UI):
  - ```
  renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
```
- Use
```
  {!$attrs.<name>}
```
  in attribute mappings when binding schema data to custom renderer component attributes.
- CRITICAL: Attribute mappings like
```
  {!$attrs.propertyName}
```
  must reference properties that actually exist in your type schema. Referencing non-existent properties will fail validation.
- Type matching: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation.
- Widget renderer pattern (for widget rendition):
  - When to use: Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT.
  - Structure:
```
renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }
```
  - REQUIRED workflow:
    - STOP: Do NOT attempt to create the widget renderer yourself.
    - MANDATORY FIRST STEP: You MUST fetch the reference file
      references/widget-rendition.md
      located in this skill's directory before proceeding.
    - Follow the complete workflow documented in
      widget-rendition.md
      using the generated CLT schema as the grounding schema.
    - The
      widget-rendition.md
      reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json.
    - Do not attempt to generate widget rendition without first fetching the
      widget-rendition.md
      reference file.
- Property-level override pattern:
  - ```
  renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }
```
  . Valid renderer components (examples):
```
  es_property_editors/outputText
```
  ,
```
  es_property_editors/outputNumber
```
  ,
```
  es_property_editors/outputImage
```
  . Avoid input-style components in the renderer.
- Layout pattern for renderer:
  - ```
  renderer.layout.definition = "lightning/verticalLayout"
```
- ```
renderer.layout.children[*].definition = "lightning/propertyLayout"
```
    with
```
attributes.property = "<propertyName>"
```
  - CRITICAL: Same as editor layouts,
```
lightning/propertyLayout
```
    only accepts the
```
property
```
    attribute. Do NOT add
```
label
```
    ,
```
title
```
    , or any other attributes.
- Collection renderer (for root-level
```
lightning__listType
```
  properties): Use
```
collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" }
```
  or
```
es_property_editors/genericListTypeRenderer
```
  to render the list.

Place files in the correct bundle structure

```
lightningTypes/<TypeName>/schema.json
```

(Optional)

lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json

(Optional)

lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json

For Gen AI / Copilot the standard path is
```
lightningDesktopGenAi/
```
. Other targets (e.g. Experience Builder, Mobile Copilot, Enhanced Web Chat) use different subfolders when supported:
```
experienceBuilder/
```
,
```
lightningMobileGenAi/
```
,
```
enhancedWebChat/
```
.

Configure custom LWC components (if using custom components)

CRITICAL: Custom LWC components referenced in editor/renderer configs MUST have the correct target configuration in their
```
-meta.xml
```
files:
- For editor components (
```
c/<componentName>
```
  used in
```
editor.json
```
  ): The LWC's
```
-meta.xml
```
  file must include
```
<target>lightning__AgentforceInput</target>
```
- For renderer components (
```
c/<componentName>
```
  used in
```
renderer.json
```
  ): The LWC's
```
-meta.xml
```
  file must include
```
<target>lightning__AgentforceOutput</target>
```

Without the correct target, deployment will fail with:

Invalid target configuration. To use 'c/componentName' as a renderer/editor, your js-meta.xml file must include valid target 'lightning__AgentforceOutput/Input'.

Example

-meta.xml

for a renderer component:

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>

确认CLT方案
- 如果引用Apex：捕获精确的类引用（
```
@apexClassType/namespace__ClassName$InnerClass
```
  ）。
- 如果使用标准原始类型：列出字段、其Lightning原始类型以及必填字段。
起草
schema.json
- 请勿在顶部包含
  "$schema"
- 从根对象结构（必填根字段）开始。
- 使用有效的原始
```
lightning:type
```
  标识符添加
```
properties
```
  。
- 对于嵌套对象属性，使用CLT引用模式:
  - ```
  "lightning:type": "c__<CLTName>"
```
  以引用另一个CLT
- 被引用的CLT必须在父CLT之前部署到Org中。
- 对于基于Apex的嵌套对象：当结构已在服务器端存在时，使用
```
@apexClassType/...
```
  。
- 如果提示明确要求真正的嵌套对象输出，优先选择基于Apex的CLT（
```
@apexClassType/...
```
  ）以确保部署安全的嵌套结构。
- 对于数组：遵循严格的列表规则（避免使用
```
items
```
  ；避免在嵌套数组上使用
```
lightning:type
```
  ）。
- 部署前，验证
```
lightning:type
```
  的拼写是否准确（例如，使用
```
lightning__richTextType
```
  ，而非拼写错误的变体）。

（可选）起草
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}
```
  ，而非
```
{!$attrs.value}
```
  ，除非
```
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>" }

。或者，使用

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
```
  属性。

（可选）起草
renderer.json
（仅当需要自定义UI或mosaic rendition时）
- 支持的结构：顶层
```
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}
```
  等属性映射必须引用类型模式中实际存在的属性。引用不存在的属性会导致验证失败。
- 类型匹配：属性值必须与组件预期的类型匹配。例如，如果组件期望字符串属性，传递整数会导致验证失败。
- Widget渲染器模式（针对widget rendition）:
  - 使用场景：当用户为其CLT请求"mosaic"、"widget"、"fragment"或"跨平台渲染"时使用。
  - 结构：
```
renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM块和区域树 */ ] }
```
  - 必填流程:
    - 停止：请勿尝试自行创建widget渲染器。
    - 强制第一步：在继续之前，您必须获取此技能目录下的参考文件
      references/widget-rendition.md
      。
    - 使用生成的CLT模式作为基础模式，遵循
      widget-rendition.md
      中记录的完整流程。
    - widget-rendition.md
      参考文件包含完整的widget生成流程：通过discoverUiComponents发现UEM块、调用getUiComponentSchemas、构建UEM树以及编写renderer.json。
    - 请勿在未获取
      widget-rendition.md
      参考文件的情况下尝试生成widget rendition。
- 属性级覆盖模式:
  - ```
  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
```
  来渲染列表。

将文件放置在正确的包结构中

```
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/
```
。

配置自定义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

<?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>

Common Deployment Errors

常见部署错误

Error / Symptom	Likely Cause	Fix
Schema validation fails due to unknown keyword	`unevaluatedProperties: false` + disallowed keyword (commonly `examples` , `items` )	Remove the offending keyword; keep schema minimal
Nested object validation failure	Org/channel validation rejects nested object typing in `LightningTypeBundle`	Use CLT reference ( `c__<CLTName>` ) or Apex class types
Invalid CLT reference	Referenced CLT doesn't exist in org or incorrect syntax	Deploy the referenced CLT first; `c__<CLTName>` must match the referenced type’s `lightning:type` value / FQN / registered identifier, not `title`
Invalid or misspelled `lightning:type` (for example, `lightning__richtextType` instead of `lightning__richTextType` )	Incorrect generated type name	Cross-check all `lightning:type` values against supported type names and correct them before deployment
Array property rejected	Use of `items` (or `lightning:type` in nested arrays) rejected by validator	For nested arrays: keep only `type: "array"` . For root arrays: use minimal structure; remove `items` if rejected
Apex-based CLT rejected	Extra fields added (e.g., `type` , `properties` )	Use only `title` , optional `description` , and `lightning:type`
Editor config rejected	Use of invalid patterns ( `es_property_editors/inputList` , `itemSchema` ) or unrecognized top-level keys	Use `editor.componentOverrides` and `editor.layout` ; keep config minimal
`additionalProperties` error on layout attributes	Adding `label` or other attributes to `lightning/propertyLayout`	Only use `property` attribute in `lightning/propertyLayout` . Remove `label` , `title` , or any other attributes
Invalid target configuration for custom LWC	Custom LWC component's `-meta.xml` missing required target ( `lightning__AgentforceInput` or `lightning__AgentforceOutput` )	Add correct target to LWC's `-meta.xml` : use `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers
Attribute mapping doesn't exist in type schema	Using `{!$attrs.propertyName}` where `propertyName` is not defined in schema	Ensure all attribute mappings reference actual properties in your type schema's `properties` section
`additionalProperties` error with deprecated keys	Using `propertyRenderers` or `view` in editor/renderer config	Replace deprecated `propertyRenderers` with `componentOverrides` and `view` with `layout`
Type mismatch in component attributes	Passing wrong type for component attribute (e.g., integer instead of string)	Ensure attribute values match the expected type defined by the component

错误/症状	可能原因	修复方法
模式因未知关键字验证失败	`unevaluatedProperties: false` + 不允许的关键字（常见为 `examples` 、 `items` ）	删除违规关键字；保持模式极简
嵌套对象验证失败	Org/渠道验证拒绝 `LightningTypeBundle` 中的嵌套对象类型	使用CLT引用（ `c__<CLTName>` ）或Apex类类型
无效CLT引用	被引用的CLT在Org中不存在或语法错误	先部署被引用的CLT； `c__<CLTName>` 必须与被引用类型的 `lightning:type` 值/完全限定名/注册标识符匹配，而非 `title`
`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`
属性映射在类型模式中不存在	使用 `{!$attrs.propertyName}` 但 `propertyName` 未在模式中定义	确保所有属性映射都引用类型模式 `properties` 部分中实际存在的属性
使用废弃键出现 `additionalProperties` 错误	在编辑器/渲染器配置中使用了 `propertyRenderers` 或 `view`	将废弃的 `propertyRenderers` 替换为 `componentOverrides` ，将 `view` 替换为 `layout`
组件属性类型不匹配	为组件属性传递了错误类型（例如，整数而非字符串）	确保属性值与组件定义的预期类型匹配

Verification Checklist

验证清单

Root schema has

type: "object"

title

lightning:type: "lightning__objectType"

, and

unevaluatedProperties: false

Root schema does not include
```
examples
```
when strict validation is enabled
No nested object includes
```
lightning:type: "lightning__objectType"
```
Arrays are defined minimally (especially nested arrays)
Only supported primitive
```
lightning:type
```
identifiers are used for leaf properties

Apex class CLTs contain only

title

description

and

lightning:type: "@apexClassType/..."

Bundle structure and filenames match Lightning Types requirements

Editor config uses only allowed patterns (no

es_property_editors/inputList

, no

itemSchema

); use valid components (e.g.

es_property_editors/inputText

es_property_editors/inputNumber

) or custom

c/

components

Renderer config uses output-style components (e.g.
```
es_property_editors/outputText
```
,
```
es_property_editors/outputNumber
```
) where applicable, not input editors
Layout configurations use
```
lightning/propertyLayout
```
with ONLY the
```
property
```
attribute (no
```
label
```
,
```
title
```
, or other attributes)
All attribute mappings (
```
{!$attrs.propertyName}
```
) reference properties that exist in the type schema
Custom LWC components have correct targets in
```
-meta.xml
```
:
```
lightning__AgentforceInput
```
for editors,
```
lightning__AgentforceOutput
```
for renderers
Root schema does NOT include
```
"$schema"
```
field

根模式包含

type: "object"

、

title

、

lightning:type: "lightning__objectType"

和

unevaluatedProperties: false

启用严格验证时，根模式不包含
```
examples
```
没有嵌套对象包含
```
lightning:type: "lightning__objectType"
```
数组定义保持极简（尤其是嵌套数组）
叶子属性仅使用受支持的原始
```
lightning:type
```
标识符

基于Apex类的CLTs仅包含

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"
```
字段