Apex-Based Custom Lightning Types

With Apex-based custom Lightning types, you can define the structure of a custom Lightning type by referencing an Apex class code. Instead of manually defining every field and property in a JSON schema, the custom Lightning type inherits its structure directly from the Apex class member variables, specifically the variables annotated with @AuraEnabled. Use this approach when your agent action returns complex data that you have already modeled in your Apex logic. This method maintains a single source of truth for the data structure.

Supported in:

• Agentforce Employee agent in Lightning Experience
• Agentforce Service agent via Enhanced Chat v2

For Apex-based types, the schema references an Apex class. You don’t define properties here. Instead, you point to the class that contains the data structure.

This table lists the keywords that you can specify in a schema.json file.

Unless noted otherwise, the keywords follow the JSON Schema specification.

Here’s a sample code that shows the contents of the schema.json file for a custom Lightning type flightResponse.

See Also

• Create Custom Labels for Custom Lightning Types

To ensure successful invocation and rendering within Agentforce—especially in namespaced orgs or managed packages—configure your Apex classes according to these requirements.

Class Definition and Visibility

• Top-level definition. Define every class as a top-level class in its own file. Don’t use nested (inner) classes.
• Global visibility. Mark all classes as global. Using public or private modifiers can cause failures in namespaced orgs or managed packages.

Annotations

• @AuraEnabled. Apply this annotation to every field required in the response, including fields inside objects used as @InvocableVariable.
• @JsonAccess. Annotate every class with @JsonAccess(serializable='always' deserializable='always'). This annotation ensures that the internal invocation layer can process the data.

Namespace Prefixes

• Local org classes. Use the “c” prefix for classes in your local org.
• Managed packages. Use the specific registered namespace for the package.
  
  See Understand Namespace Prefixes for Metadata References

Supported Types

Not all data types that you use in an Apex class are supported in Lightning types.

Lightning types support these data types.

• Primitives, including Integer, Double, Long, Date, Datetime, Time, String, ID, and Boolean
• sObjects, either a generic or specific sObject, such as Account, Contact, and MyCustomObject__c
• Collections
  • A list or array of primitives, sObjects, user-defined Apex classes, and collections
  • A map, represented as Map<key, value>, where the key is always a string and the value can be a primitive, sObject, or collection
• User-defined Apex classes

Schema projection is the automated process that evaluates an Apex class to generate a runtime JSON schema.

How It Works

• API Evaluation. The internal LightningTypeBundle API introspects the referenced Apex class. The projection process scans for the @AuraEnabled annotation on member variables to determine which properties to expose.
• Dynamic Translation. The projection layer automatically translates Apex primitives (such as String and Integer) and complex types (such as nested classes or sObjects) into the corresponding Lightning type schema. This automation eliminates manual variable mapping.
• Single Source of Truth. Because the schema projects directly from the code, changes to the Apex class automatically update the Lightning type’s structure. This automation eliminates manual updates to the schema.json file.

While schema.json defines the data structure, the UI configuration files in the Lightning Type Bundle control the visual representation. Organize these files by channel to support specific Salesforce applications.

Channels

Store UI overrides in channel-specific subfolders to target different Salesforce applications.

• lightningDesktopGenAi. Use this folder for Agentforce Employee agents in Lightning Experience.
• enhancedWebChat. Use this folder for Agentforce Service agents via Enhanced Chat v2.

Configuration Files

Configure input and output UI overrides by using these JSON files.

• editor.json. Configures the UI when the custom Lightning type is an input parameter. It points to a Lightning Web Component (LWC) that serves as a custom form for data entry.
• renderer.json. Configures the UI when the custom Lightning type is an output parameter. It points to an LWC that renders the returned data (for example, as a custom card or list).

Component Override

You can customize the visual presentation by adding component overrides to your editor.json and renderer.json files.

• Top-Level Override. A top-level override replaces the default UI for the entire custom Lightning type. To configure this override, use the $ symbol as the key in the componentOverrides section of your editor.json or renderer.json. This approach is useful for creating specialized interfaces, such as a custom card or a multi-field form handled by a single component.

Attribute Mapping

In both configuration files, map schema fields to LWC component fields by using the {!\$attrs.FieldName} syntax.

LWC Target Requirements

To use a component as an override, include the appropriate target in the component’s js-meta.xml file.

• lightning__AgentforceInput for input overrides
• lightning__AgentforceOutput for output overrides

See Also

• Lightning Types Configuration Files
• Lightning Type UI Configuration

To maintain the integrity of active agent actions and prevent runtime failures, adhere to these restrictions when you modify Apex classes referenced by a custom Lightning type.