Generating Custom Lightning Type

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

Specification

CustomLightningType Metadata Specification

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.

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.

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.

Additional CLT Metaschema Validations

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

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.

Generation Workflow

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

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

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

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

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

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

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

Primitive Types & Constraints

Reference for all supported Lightning primitive types and their allowed constraints. Read this when authoring property-level lightning:type identifiers or determining which keywords are valid on a given property.

Supported Types

• 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

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)

Widget Generation Guide

📋 Overview

Widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs.

🎯 Purpose

Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc.

Schema Grounding

Widget generation is always schema-grounded using a CLT's schema. The schema describes the data shape the widget should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full Workflow below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema.

⚙️ Composition

A widget is a UEM (Unified Experience Model) tree of blocks and regions. The widget you return must follow the Typescript interfaces below:

interface BlockType {
   type: 'block'
   definition: string  // {namespace}/{blockName}
   attributes?: Record<string, any>
   children?: (BlockType | RegionType)[]
}

interface RegionType {
   type: 'region'
   name: string
   children: BlockType[]
}

---

🔧 Available Metadata Actions

When to Use Each Action

discoverUiComponents

Purpose: Discover the palette of available blocks that can be used in widget composition.

Use for: Finding available blocks before building your widget structure.

Input Parameters:

• actionName (required*): "discoverUiComponents"
• metadataType (required): "FRAGMENT"
• parameters (required): JSON object with the below fields
• pageType (required): "FRAGMENT"
• pageContext (optional): JSON object - not required for FRAGMENT type
• searchQuery (optional): String to filter components by name or description

Returns: List of components with:

• definition: Fully qualified name (e.g., "namespace/definiton")
• description: Component description
• label: Human-readable label
• attributes: Optional attribute metadata

getUiComponentSchemas

Purpose: Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.

Use for: You know which components you want but need to understand their properties before adding them to your widget.

Input Parameters:

• actionName (required*): "getUiComponentSchemas"
• metadataType (required): "FRAGMENT"
• parameters (required): JSON object with the below fields
• pageType (required): "FRAGMENT"
• componentDefinitions (required): List of fully qualified names (e.g., ["namespace/definition"])
• CRITICAL: NEVER include "tile/mosaic" in this list. "tile/mosaic" is a container component used in renderer.json structure and should not be passed to getUiComponentSchemas
• pageContext (optional): JSON object - not required for FRAGMENT type
• includeKnowledge (optional): Boolean, defaults to true - includes additional component-specific guidance

Returns:

• componentSchemas: List of results (supports partial failures)
• Success entries: Contains JSON schema with property definitions, types, constraints
• Failure entries: Contains error message explaining why schema couldn't be retrieved
• $defs: Schema definitions and references (if schema transformation applied)

Key Feature: Supports partial failures - if some components can't be found, you still get schemas for the successful ones.

---

Attribute binding using placeholder syntax

• Where to use: When block properties must display or pass runtime data from the grounding schema, use the Placeholder Syntax below so that the runtime binds values into the widget. Check each block's schema (from getUiComponentSchemas) for the correct property name (e.g. value, text, label).
• Placeholder Syntax: Use {!$attrs.<attrName>} as the placeholder for each block property that should receive data.

<attrName> must match the property name from the grounding schema so that the runtime can resolve its value. Example: for a schema property title, set the block property to {!$attrs.title}.

• List / iterative data: Only the children (list items) hold bound values; the parent list block does not. For each item inside a list (e.g. tile/listItem), use {!$attrs.<listAttrName>.item} so the runtime binds the current item. <listAttrName> MUST match the schema property name of the list. Example: for icons, use "{!$attrs.icons.item}" on the list item.

---

💡Workflow

1. Schema Parsing

• Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the widget spec.

2. Discover Available Blocks (REQUIRED - do NOT skip)

• Use discoverUiComponents metadata action above to explore what blocks are available.
• Use property types from the widget spec to inform searchQuery (e.g. text → "text", number → "number").

3. Select Components

• Choose blocks that can represent each property in the widget spec from the results of step 2.

4. Get Component Schemas (REQUIRED - do NOT skip)

• Use getUiComponentSchemas metadata action with the selected block definitions from step 3 and review block properties' metadata.

5. Build Widget

• Construct the UEM tree. Map each property in the widget spec to block properties and preserve order of the widget spec.
• For block properties that must show or pass runtime data, use the placeholder syntax (see Attribute binding using placeholder syntax above).
• Use block properties from the schemas retrieved in step 4.

6. Write output to CLT Bundle

• Always write to lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json (or the correct target subfolder for the product surface, e.g. experienceBuilder/, lightningMobileGenAi/, enhancedWebChat/ when applicable).

Check required root override pattern below - renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes - contains the widget UEM generated using the **Workflow** steps 1-5 above }

---

⚠️ Important Notes

• widget spec includes both required and optional attributes - review carefully to ensure valid configuration.
• When using `execute_metadata_action` tool, always supply `parameters` with the required fields above; missing parameters or required keys causes hard failures, not partial results.
• Block definitions always follow the {namespace}/{blockName} convention.
• Use the same definition format returned by discoverUiComponents when calling getUiComponentSchemas
• Placeholder syntax for non-list properties is {!$attrs.<attrName>} and for list properties is {!$attrs.<listAttrName>.item}.