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

当结构简单且可通过属性和受支持的原始
```
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 should be plain JSON Schema objects (
```
type
```
  ,
```
properties
```
  , optional
```
required
```
  , optional
```
unevaluatedProperties
```
  ).
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

根对象模式必须包含：

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

"lightning:type": "lightning__objectType"

```
"unevaluatedProperties": false
```

CLT元模式强制
```
"unevaluatedProperties"
```
为
```
false
```
，请勿将其设置为
```
true
```
。
当设置
```
"unevaluatedProperties": false
```
时，根对象模式不得包含
```
"examples"
```
。
嵌套对象（位于
properties
内）不得设置
```
"lightning:type": "lightning__objectType"
```
。
- 嵌套对象应为纯JSON Schema对象（包含
```
type
```
  、
```
properties
```
  ，可选
```
required
```
  、可选
```
unevaluatedProperties
```
  ）。
列表/数组属性受到CLT元模式的严格限制：
- 关键限制：CLT元模式可能完全拒绝
```
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元模式验证

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
```
（元模式限制值；目前已知仅允许
```
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 objects: omit
```
lightning:type
```
  and keep keywords minimal.
- For arrays: follow the strict list rules (avoid
```
items
```
  ; avoid
```
lightning:type
```
  on nested arrays).

(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
- 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
```
  。
- 对于嵌套对象：省略
```
lightning:type
```
  ，并保持关键字极简。
- 对于数组：遵循严格的列表规则（避免使用
```
items
```
  ；避免在嵌套数组上使用
```
lightning:type
```
  ）。

（可选）起草
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时）
- 支持的结构：顶级
```
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}
```
  等属性映射必须引用类型模式中实际存在的属性。引用不存在的属性会导致验证失败。
- 类型匹配：属性值必须与组件预期的类型匹配。例如，如果组件期望字符串属性，传入整数会导致验证失败。
- 属性级覆盖模式：
  - ```
  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>

部署与验证
- 使用你的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	Nested object includes `lightning:type: lightning__objectType`	Remove `lightning:type` from nested objects
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` ）	删除违规关键字；保持模式极简
嵌套对象验证失败	嵌套对象包含 `lightning:type: lightning__objectType`	从嵌套对象中移除 `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

根模式包含

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