generating-custom-lightning-type

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
Troubleshoot deployment errors related to Custom Lightning Types

当你需要以下操作时，请使用本技能：

为结构化输入/输出创建Custom Lightning Types（CLTs）
为Lightning Platform生成基于JSON Schema的类型定义
为Einstein Agent操作配置CLTs
为自定义UI设置编辑器和渲染器配置
排查与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
```
值/完全限定名（FQN）/注册标识符** —— 而非JSON Schema的
```
title
```
。
当结构简单且可通过属性和受支持的原始
lightning:type
标识符表达时，选择标准Lightning类型。
当结构已在服务器端存在且希望通过Apex类定义其形状时，选择Apex类类型（
```
@apexClassType/...
```
）。
仅当需要自定义UI行为（自定义LWC输入/输出组件）时，才包含编辑器/渲染器配置，否则请省略。

Critical Rules (Read First)

关键规则（请先阅读）

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必须包含：

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

"lightning:type": "lightning__objectType"

```
"unevaluatedProperties": false
```

CLT元Schema强制要求
```
"unevaluatedProperties"
```
为
```
false
```
，请勿将其设置为
```
true
```
。
当设置了
"unevaluatedProperties": false
时，根对象Schema不得包含
"examples"
。
嵌套对象（位于
properties
内）不得设置
"lightning:type": "lightning__objectType"
。
- 嵌套对象可以是：使用
```
c__<CLTName>
```
  语法引用其他CLTs。
CLT元Schema对列表/数组属性有严格限制：
- 关键限制：CLT元Schema可能完全拒绝
```
items
```
  关键字。默认情况下，请将
```
items
```
  视为不允许使用。
- 根级数组（根
```
properties
```
  的直接子项）：
  - 必须包含
```
"lightning:type": "lightning__listType"
```
  - 不得包含
```
"items"
```
  - 可选
```
"type": "array"
```
- 嵌套数组（嵌套对象内的数组）是最常见的失败点：
  - 必须包含
```
"type": "array"
```
  - 不得包含
```
"lightning:type": "lightning__listType"
```
  - 不得包含
```
"items"
```
当设置了
"unevaluatedProperties": false
时，任何未知关键字都会导致验证失败。优先移除关键字而非放宽严格性。
基于Apex类的CLTs需保持极简：
- 仅包含**
```
title
```
  、可选的
```
description
```
  **，以及设置为
```
@apexClassType/...
```
  的
```
lightning:type
```
  。
- 请勿添加
```
type
```
  、
```
properties
```
  、
```
required
```
  或
```
unevaluatedProperties
```
  。

Additional CLT Metaschema Validations

额外CLT元Schema验证

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

原始类型与约束

```
lightning__textType
```
- Max length 255
```
lightning__multilineTextType
```
- Max length 2000
```
lightning__richTextType
```
- Max length 100000

lightning__urlType

Max length 2000

Optional

lightning:allowedUrlSchemes

enum values:

https

http

relative

mailto

tel

```
lightning__dateType
```
- Data pattern: YYYY-MM-DD
```
lightning__timeType
```
- Data pattern: HH:MM:SS.sssZ
```
lightning__dateTimeType
```
- Data shape is an object with required
```
dateTime
```
  and optional
```
timeZone
```

lightning__numberType

Decimal numbers; optional
```
maximum
```
,
```
minimum
```
,
```
multipleOf
```

```
lightning__integerType
```
- Whole numbers only; optional
```
maximum
```
  ,
```
minimum
```
```
lightning__booleanType
```
- true/false

```
lightning__textType
```
- 最大长度255
```
lightning__multilineTextType
```
- 最大长度2000
```
lightning__richTextType
```
- 最大长度100000

lightning__urlType

最大长度2000

可选的

lightning:allowedUrlSchemes

枚举值：

https

http

relative

mailto

tel

```
lightning__dateType
```
- 数据格式：YYYY-MM-DD
```
lightning__timeType
```
- 数据格式：HH:MM:SS.sssZ
```
lightning__dateTimeType
```
- 数据结构是包含必填
```
dateTime
```
  和可选
```
timeZone
```
  的对象

lightning__numberType

十进制数字；可选
```
maximum
```
,
```
minimum
```
,
```
multipleOf
```

```
lightning__integerType
```
- 仅支持整数；可选
```
maximum
```
  ,
```
minimum
```
```
lightning__booleanType
```
- true/false

Allowed Property-Level Keywords

允许的属性级关键字

When strict validation is enabled (

unevaluatedProperties: false

), keep each property minimal and prefer only keywords known to be allowed:

```
title
```
,
```
description
```
,
```
einstein:description
```
```
type
```
(when used, ensure it matches the chosen
```
lightning:type
```
)
```
lightning:type
```
```
maximum
```
,
```
minimum
```
,
```
multipleOf
```
(numeric)
```
maxLength
```
,
```
minLength
```
(string)
```
const
```
,
```
enum
```

lightning:textIndexed

lightning:supportsPersonalization

lightning:localizable

lightning:uiOptions

lightning:allowedUrlSchemes

```
lightning:tags
```
(metaschema restricts values; currently
```
flow
```
is the only known allowed tag)

当启用严格验证（

unevaluatedProperties: false

）时，保持每个属性极简，优先仅使用已知允许的关键字：

```
title
```
,
```
description
```
,
```
einstein:description
```
```
type
```
（使用时请确保与所选
```
lightning:type
```
匹配）
```
lightning:type
```
```
maximum
```
,
```
minimum
```
,
```
multipleOf
```
（数值类型）
```
maxLength
```
,
```
minLength
```
（字符串类型）
```
const
```
,
```
enum
```

lightning:textIndexed

lightning:supportsPersonalization

lightning:localizable

lightning:uiOptions

lightning:allowedUrlSchemes

```
lightning:tags
```
（元Schema限制值；目前已知唯一允许的标签是
```
flow
```
）

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

Deploy and validate
- Run a final schema sanity check before deploy: valid
```
lightning:type
```
  names, required fields present, and no disallowed keywords.
- Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
- Validate incrementally: if deployment fails, remove disallowed keywords first (especially
```
examples
```
  ,
```
items
```
  , nested
```
lightning:type
```
  ).

确认CLT实现方式
- 如果引用Apex：捕获精确的类引用（
```
@apexClassType/namespace__ClassName$InnerClass
```
  ）。
- 如果使用标准原始类型：列出字段、对应的Lightning原始类型，以及哪些字段是必填的。
起草
schema.json
- 从根对象结构（必填根字段）开始。
- 使用有效的原始
```
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": { ... } }
```
- 将Schema数据传递到自定义LWC时，使用
```
{!$attrs.<name>}
```
  语法进行属性映射：例如
```
"attributes": { "myField": "{!$attrs.value}" }
```
  ，以便运行时将Schema值绑定到组件的属性。
- 关键注意事项：
```
{!$attrs.<name>}
```
  中的
```
<name>
```
  必须是类型Schema中定义的属性。例如，如果你的Schema有一个名为
```
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时）
- 支持的结构：顶级
```
renderer
```
  对象，包含
```
renderer.componentOverrides
```
  和
```
renderer.layout
```
  。
  - 顶级
```
renderer
```
    对象。
  - 使用
```
renderer.componentOverrides
```
    进行组件覆盖。
  - 使用
```
renderer.layout
```
    进行布局。
  - 已废弃：请勿使用
```
propertyRenderers
```
    或
```
view
```
    —— 这些是遗留关键字。请始终使用
```
componentOverrides
```
    和
```
layout
```
    替代。
- 根覆盖模式（完全自定义渲染UI最常用）：
  - ```
  renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }
```
- 将Schema数据绑定到自定义渲染器组件属性时，在属性映射中使用
```
  {!$attrs.<name>}
```
  。
- 关键注意事项：
```
  {!$attrs.propertyName}
```
  等属性映射必须引用类型Schema中实际存在的属性。引用不存在的属性会导致验证失败。
- 类型匹配：属性值必须与组件预期的类型匹配。例如，如果组件期望字符串属性，传递整数会导致验证失败。
- 属性级覆盖模式：
  - ```
  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

对于生成式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>

部署与验证
- 部署前运行最终的Schema完整性检查：验证
```
lightning:type
```
  名称有效、必填字段存在、无不允许的关键字。
- 使用Org的标准元数据部署流程（如Salesforce CLI或IDE）部署包。所使用的MCP客户端或工具应提供或集成适用于Lightning Type包的部署/检索命令。
- 增量验证：如果部署失败，优先移除不允许的关键字（尤其是
```
examples
```
  ,
```
items
```
  , 嵌套
```
lightning:type
```
  ）。

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

错误/症状	可能原因	修复方案
Schema因未知关键字验证失败	`unevaluatedProperties: false` + 不允许的关键字（常见为 `examples` , `items` ）	移除违规关键字；保持Schema极简
嵌套对象验证失败	Org/渠道验证拒绝 `LightningTypeBundle` 中的嵌套对象类型	使用CLT引用（ `c__<CLTName>` ）或Apex类类型
无效CLT引用	被引用的CLT不存在于Org中或语法错误	先部署被引用的CLT； `c__<CLTName>` 必须与被引用类型的 `lightning:type` 值/完全限定名（FQN）/注册标识符匹配，而非 `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`
属性映射在类型Schema中不存在	使用 `{!$attrs.propertyName}` 但 `propertyName` 未在Schema中定义	确保所有属性映射都引用类型Schema的 `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

根Schema包含

type: "object"

title

lightning:type: "lightning__objectType"

和

unevaluatedProperties: false

启用严格验证时，根Schema不包含
```
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}
```
）都引用类型Schema中存在的属性
自定义LWC组件在
```
-meta.xml
```
中有正确的目标：编辑器使用
```
lightning__AgentforceInput
```
，渲染器使用
```
lightning__AgentforceOutput
```