Skip to content

DTOs - Guide ​

Who this page is for: developers who send data to a Lightning component, another system or a flow, when they are designing or consuming a data contract; and the architects who keep the internal database structure separate from the formats outside systems see. Deciding whether to use KernDX? See Why KernDX.

Copy this first ​

apex
@JsonAccess(serializable='always' deserializable='always')
public inherited sharing class DTO_OrderSummary extends kern.DTO_JsonBase
{
	@AuraEnabled public String orderId;
	@AuraEnabled public Decimal totalAmount;

	public override Type getObjectType()
	{
		return DTO_OrderSummary.class;
	}
}

// Turn it into JSON
DTO_OrderSummary summary = new DTO_OrderSummary();
summary.orderId = 'ORD-001';
summary.totalAmount = 250.00;
String json = summary.serialize();

// Read it back from JSON
DTO_OrderSummary parsed = (DTO_OrderSummary)new DTO_OrderSummary().deserialize(json);

What this does: defines a small class that holds two fields, turns it into JSON, and reads the JSON back into a new object with the same values. @JsonAccess lets the package write and read your class. getObjectType() tells the package which class to build when it reads JSON. Declare it public override.

Read next: Skip getObjectType() with a type resolver, DTOs in REST APIs, DTOs in Lightning components, Test a DTO.


Quick Navigation ​

I need to...Go to...
Decide whether a DTO is the right toolUse this when / Don't use this when
Build my own DTO classesCreating Custom DTO Classes
Let the package read and write my DTO (@JsonAccess)Creating JSON DTOs
Stop writing getObjectType() in every DTOType Resolution
Fill a DTO from a recordImplementing populate() Methods
Turn one DTO into anotherImplementing transform() Methods
Use a ready-made DTO for name-value pairs, a datatable, or picklist valuesBuilt-in DTO Classes
Send and receive DTOs in a REST APIDTOs in REST APIs
Return a DTO to a Lightning componentDTOs in LWC Components
Pass a DTO from a Lightning component into ApexPassing Complex DTOs as @AuraEnabled Parameters
Use a DTO in a flowDTOs in Flow Invocables
Read a field by its path, sort DTOs, or put them in a SetWhat else can it do?
Test a DTOTesting
Fix a DTO errorTroubleshooting
Understand how DTOs workHow does it work?
See why KernDX is worth usingWhy KernDX: the DTOs example

Quick Start ​

Pick the shape that fits your data:

Your dataWhat to write
Your own fields, sent as JSON for an API integration or a Lightning component response (most of the time)A JSON DTO: a class that extends DTO_JsonBase. The shortest path is below
Key-value parameters, a Lightning datatable, picklist values, or a change-event headerNo class of your own: a ready-made DTO from Built-in DTO Classes
apex
@JsonAccess(serializable='always' deserializable='always')
public inherited sharing class DTO_OrderSummary extends DTO_JsonBase
{
	@AuraEnabled public String orderId;
	@AuraEnabled public Decimal totalAmount;

	// Needed unless you register a Type Resolver (see Type Resolution)
	public override Type getObjectType()
	{
		return DTO_OrderSummary.class;
	}
}

// Create and serialize
DTO_OrderSummary summary = new DTO_OrderSummary();
summary.orderId = 'ORD-001';
summary.totalAmount = 250.00;
String json = summary.serialize();

// Deserialize from JSON
DTO_OrderSummary parsed = (DTO_OrderSummary)new DTO_OrderSummary().deserialize(json);

Namespaces in code samples: kern. on a class and kern__ on an object, field, or metadata type mark the managed package's namespace. On the managed package, framework references need those prefixes even where a sample omits them; repackaged under your own namespace, replace kern/kern__ with your prefix; on an unmanaged deploy, drop them. See How to read the code samples.

When KernDX is installed as a managed package: Always include @JsonAccess(serializable='always' deserializable='always') on every DTO that extends a managed package base class. Without it, serialization fails at runtime. See Type Resolution for the other requirement.


What problem does this solve? ​

When your code moves data between two places (Apex to a Lightning component, Apex to an outside system, or a screen flow to Apex), you need a tidy package to carry it. Without a deliberate shape, that data ends up as loose maps and untyped JSON that the compiler cannot check and tests cannot pin down.

A Data Transfer Object, or DTO, is a small class that holds exactly the fields you want to move and knows how to convert itself to and from JSON. Build your DTOs on KernDX's DTO classes, and the shape of the data you send is clear, type-checked by the compiler, and easy to test.

You use DTOs when building APIs, sending structured data to the front end, or passing parameters into flows.


Mental model ​

Think of a DTO as a shipping container for your data. You pack exactly the items you want to send (the fields), and the container has a standard shape both ends understand. It converts to a flat manifest (JSON) for the journey and back into labelled items on arrival.

The contents inside your warehouse (your SObjects) can be arranged however you like; the container is what crosses the boundary.


Use this when / Don't use this when ​

Reach for a DTO when data crosses a boundary; stay with plain Salesforce objects when it does not.

Use DTOs when ​

Building REST APIs - Standardise request/response formats

apex
// Inbound API with DTO
public with sharing class API_CreateAccount extends API_Inbound
{
	public override void configure()
	{
		super.configure();
		requestPayload = new DTO_AccountRequest();
		responsePayload = new DTO_AccountResponse();
	}
}

Integrating External Systems - Parse REST responses

apex
// Parse external API response
DTO_WeatherResponse weather = (DTO_WeatherResponse)
	new DTO_WeatherResponse().deserialize(responseBody);

Returning Complex Data to LWC - Structure hierarchical data

apex
@AuraEnabled
public static DTO_BaseTable getAccountData()
{
	DTO_BaseTable table = new DTO_BaseTable();
	// Build table structure...
	return table;
}

Flow Invocable Methods - Pass complex parameters

apex
@InvocableMethod
public static List<Results> processData(List<Requests> requests)
{
	// Use DTO_NameValues for flexible parameters
}

Don't use DTOs when ​

If the data never leaves Apex, a DTO adds a layer with no benefit. Use the platform's own types instead.

Working Within Apex - Use SObjects directly

apex
// BAD: Unnecessary DTO usage
DTO_Account dtoAccount = convertToDto(account);
processAccount(dtoAccount);

// GOOD: Direct SObject usage
processAccount(account);

Simple Data Types - Use primitives or simple maps

apex
// BAD: Over-engineering
DTO_StringValue dto = new DTO_StringValue();
dto.value = 'Hello';

// GOOD: Use String directly
String value = 'Hello';

Internal Database Operations - Use SObjects with DML framework

apex
// BAD: Converting to DTO for DML
DTO_Account dtoAccount = mapToDto(account);
DML_Builder.newTransaction().doInsert(convertToSObject(dtoAccount)).execute();

// GOOD: Direct SObject DML
DML_Builder.newTransaction().doInsert(account).execute();

How does it work? ​

All DTOs inherit from one shared base class, so every DTO behaves the same way: it serializes to JSON, parses back, compares for equality, and loads itself from a record. You write only the fields and logic that are specific to your data; the common behaviour comes for free.

The framework sits between your business logic and the things that consume your data (REST APIs, Lightning components, and flows). That position keeps your internal Salesforce object structure separate from the data formats outside systems expect, so a change to one does not force a change to the other.

The key building blocks are:

  • DTO_Base: the virtual base class everything builds on. It provides serialize(), deserialize(), populate(), transform(), equals(), and hashCode().
  • DTO_JsonBase: the JSON-specific class. It adds readable (pretty-printed) JSON output and JsonPath integration for reading fields by path.
  • Built-in DTOs ready to use: DTO_NameValues (key-value parameters), DTO_BaseTable (Lightning datatable), DTO_PickList (picklist metadata), and DTO_ChangeEventHeader (the change-event header from Change Data Capture).

Responsibilities: DTOs transport data between layers (Apex to LWC, Apex to external APIs, Flow to Apex). They do not contain business logic, perform DML, or query data. Population logic in populate() should be limited to mapping fields from selectors and parameters.

DTO Class Hierarchy ​

text
DTO_Base (Virtual base class)
+-- DTO_JsonBase (JSON serialization)
    +-- DTO_NameValues (Key-value collections)
    +-- DTO_BaseTable (Lightning datatable structure)
    +-- [Your custom JSON DTOs]

Standalone DTOs (no inheritance):
+-- DTO_NameValue (Single name-value pair)
+-- DTO_PickList (Picklist metadata)
+-- DTO_PicklistValue (Single picklist value)

Creating Custom DTO Classes ​

Creating JSON DTOs ​

One required step when KernDX is installed as a managed package

When your DTO extends a class from an installed managed package (such as DTO_JsonBase), you must add the @JsonAccess annotation to your DTO class. The annotation gives the package's code permission to serialize and deserialize the DTO classes in your org.

Why it matters: without @JsonAccess, serialization and deserialization fail at runtime with a security error.

apex
// CORRECT: @JsonAccess annotation required for managed package DTOs
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrder extends DTO_JsonBase
{
	// ...
}

// WRONG: Missing @JsonAccess annotation
public class DTO_CustomerOrder extends DTO_JsonBase
{
	// Will fail at runtime when managed package tries to serialize!
}

When to use @JsonAccess:

  • Serializable='always' - Required when managed package code calls serialize() on your DTO
  • Deserializable='always' - Required when managed package code calls deserialize() on your DTO
  • Use both when DTOs are used in bidirectional scenarios (request + response)

Type Resolution: CRITICAL Requirement in Your Org ​

When KernDX runs as an installed managed package, you have to point it at your DTO classes. Skip this and deserialization fails at runtime.

The reason: when the framework parses JSON back into a DTO, it has to build an instance of the right class by name. Its code lives in a different namespace from yours, so it cannot find your classes on its own. With a Type Resolver, you tell the framework where to find the Apex classes in your namespace.

Where this matters:

  • Parsing JSON back into a DTO, through DTO_JsonBase.deserialize().
  • Building a class by name, where framework code uses Type.forName().
  • Working with mixed-type collections, such as factory patterns that create types on the fly.

Pick exactly one of these three approaches:

  1. Make all DTOs global. Global classes are always visible to the package's code. Simple, but it exposes the classes more widely than you may want.
  2. Implement getObjectType() in every DTO. You override one method per class to return its own type. Explicit, but repetitive across many DTOs.
  3. Register a Type Resolver (recommended). You set this up once, and the framework then resolves every DTO automatically. The most flexible and maintainable option.

Without one of these, you will hit runtime errors like this:

text
System.IllegalArgumentException: Unable to resolve type for class "DTO_CustomerRequest".
To deserialize this DTO you must implement the virtual method "getObjectType()", or make the DTO class global

Rather than override getObjectType() in every DTO or make all your classes global, you can register one custom type resolver that handles the lookup for all DTOs automatically. You set it up once and then forget it.

Your classes stay better encapsulated, because they need not be global, and the type-resolution logic lives in one place, with less boilerplate to write and maintain.

How it works:

  1. Create a custom type resolver class:
apex
/**
 * @description Custom type resolver for the DTOs in your org
 *
 * @see UTIL_TypeResolver
 */
global with sharing class CustomDTOTypeResolver extends kern.UTIL_TypeResolver.BaseClassResolver
{
	/**
	 * @description Resolves a Type object from a class name
	 *
	 * @param className The name of the class to resolve
	 *
	 * @return Type The resolved Type object or null if not found
	 */
	public override Type resolveType(String className)
	{
		return getTypeForClassName(className) ?? (Type)nextResolver?.resolveType(className);
	}

	/**
	 * @description Resolves the Type for a given class name, handling namespaces and nested classes
	 *
	 * @param className The class name to resolve
	 *
	 * @return The resolved Type object, or null if not found
	 */
	private static Type getTypeForClassName(String className)
	{
		return String.isBlank(className) ? null : Type.forName(className);
	}
}
  1. Register the resolver in custom metadata:

Create a ClassTypeResolver__mdt record:

  • Label: Custom DTO Type Resolver
  • DeveloperName: CustomDTOTypeResolver
  • ClassName__c: CustomDTOTypeResolver
  1. Simplify your DTOs:
apex
// WITH Type Resolver: No getObjectType() override needed!
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrder extends DTO_JsonBase
{
	@AuraEnabled
	public String orderId;

	@AuraEnabled
	public String customerName;

	// No getObjectType() method needed!
}

// WITHOUT Type Resolver: Must override in every DTO
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrder extends DTO_JsonBase
{
	@AuraEnabled
	public String orderId;

	public override Type getObjectType()  // Repetitive boilerplate
	{
		return DTO_CustomerOrder.class;
	}
}

When to use Type Resolver:

  • Your org, when it has many custom DTOs (reduces boilerplate)
  • Teams wanting centralized type resolution logic
  • Complex namespace scenarios

When to override getObjectType():

  • Single DTO or small number of DTOs
  • Private inner classes requiring specific resolution
  • No custom metadata configuration desired

Step 1: Define DTO Structure

apex
/**
 * @description Custom DTO for complex data structure
 *
 * IMPORTANT: @JsonAccess required because this extends managed package class DTO_JsonBase
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrder extends DTO_JsonBase
{
	@AuraEnabled
	public String orderId;

	@AuraEnabled
	public String customerName;

	@AuraEnabled
	public Date orderDate;

	@AuraEnabled
	public Decimal totalAmount;

	@AuraEnabled
	public String status;

	@AuraEnabled
	public DTO_Address shippingAddress;

	@AuraEnabled
	public List<DTO_OrderItem> lineItems;

	/**
	 * @description Constructor initializes collections
	 */
	public DTO_CustomerOrder()
	{
		lineItems = new List<DTO_OrderItem>();
	}

	/**
	 * @description Required for deserialization of private classes
	 *
	 * NOTE: This override is only required if your DTO class is private/not globally visible.
	 * If you register a custom type resolver via UTIL_TypeResolver and ClassTypeResolver__mdt,
	 * you can skip implementing this method in all your DTOs.
	 *
	 * @see UTIL_TypeResolver
	 * @see ClassTypeResolver__mdt
	 */
	public override Type getObjectType()
	{
		return DTO_CustomerOrder.class;
	}
}

/**
 * @description Nested DTO for address
 *
 * IMPORTANT: @JsonAccess required for ALL nested DTOs extending managed package classes
 *
 * NOTE: getObjectType() override optional if custom type resolver registered in ClassTypeResolver__mdt
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Address extends DTO_JsonBase
{
	@AuraEnabled
	public String street;

	@AuraEnabled
	public String city;

	@AuraEnabled
	public String state;

	@AuraEnabled
	public String postalCode;

	public override Type getObjectType()
	{
		return DTO_Address.class;
	}
}

/**
 * @description Nested DTO for line items
 *
 * IMPORTANT: @JsonAccess required for ALL nested DTOs extending managed package classes
 *
 * NOTE: getObjectType() override optional if custom type resolver registered in ClassTypeResolver__mdt
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_OrderItem extends DTO_JsonBase
{
	@AuraEnabled
	public String productName;

	@AuraEnabled
	public Integer quantity;

	@AuraEnabled
	public Decimal unitPrice;

	@AuraEnabled
	public Decimal totalPrice;

	public override Type getObjectType()
	{
		return DTO_OrderItem.class;
	}
}

Step 2: Use the DTO

apex
// Create DTO
DTO_CustomerOrder order = new DTO_CustomerOrder();
order.orderId = 'ORD-12345';
order.customerName = 'John Doe';
order.orderDate = Date.today();
order.status = 'Processing';

// Add shipping address
DTO_Address address = new DTO_Address();
address.street = '123 Main St';
address.city = 'San Francisco';
address.state = 'CA';
address.postalCode = '94105';
order.shippingAddress = address;

// Add line items
DTO_OrderItem item1 = new DTO_OrderItem();
item1.productName = 'Widget A';
item1.quantity = 2;
item1.unitPrice = 25.00;
item1.totalPrice = 50.00;
order.lineItems.add(item1);

DTO_OrderItem item2 = new DTO_OrderItem();
item2.productName = 'Widget B';
item2.quantity = 1;
item2.unitPrice = 75.00;
item2.totalPrice = 75.00;
order.lineItems.add(item2);

order.totalAmount = 125.00;

// Serialize
String json = order.serialize();

// Deserialize
DTO_CustomerOrder parsedOrder = (DTO_CustomerOrder)
	new DTO_CustomerOrder().deserialize(json);

Implementing populate() Methods ​

Sometimes you have a record ID and want a DTO filled in from that record's data. The populate() method does exactly that: you give it a Salesforce record ID and it loads the DTO's fields from the matching record. This lets you build the DTO only when you actually need its data.

One rule when you write populate(): read the record through a SEL_Base selector (its query property is a QRY_Builder when you need more than the ready-made methods), never inline SOQL. Doing it this way buys you several things:

  • Field selection lives in one place, not scattered across DTOs.
  • The query logic is reusable.
  • Tests can mock the data, so you can test without touching the database.
  • The query stays safe to run on many records at once.
  • Your code follows the same convention as the rest of the framework.
apex
/**
 * @description Account DTO with populate implementation
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Account extends DTO_JsonBase
{
	public String accountName;
	public String industry;
	public Decimal annualRevenue;
	public Integer employeeCount;
	public List<DTO_Contact> contacts;

	public DTO_Account()
	{
		contacts = new List<DTO_Contact>();
	}

	/**
	 * @description Populate DTO from Account ID
	 *
	 * @param recordId The Account record ID
	 */
	public override void populate(Id recordId)
	{
		populate(recordId, null);
	}

	/**
	 * @description Populate with optional parameters
	 *
	 * @param recordId The Account record ID
	 * @param dtoRequestParameters Optional parameters controlling population behavior
	 */
	public override void populate(Id recordId, DTO_NameValues dtoRequestParameters)
	{
		// CORRECT: Use SEL_* selector pattern
		Account account = (Account)new SEL_Accounts().findById(recordId);

		if(account == null)
		{
			LOG_Builder.build()
				.error('Account not found: ' + recordId)
				.emitAt('DTO_Account.populate');
			return;
		}

		// Populate fields
		this.accountName = account.Name;
		this.industry = account.Industry;
		this.annualRevenue = account.AnnualRevenue;
		this.employeeCount = account.NumberOfEmployees;

		// Check optional parameters
		Boolean includeContacts = true;
		if(dtoRequestParameters != null && dtoRequestParameters.exists('includeContacts'))
		{
			includeContacts = Boolean.valueOf(dtoRequestParameters.get('includeContacts'));
		}

		// Populate related contacts
		if(includeContacts && account.Contacts != null)
		{
			for(Contact contact : account.Contacts)
			{
				DTO_Contact contactDto = new DTO_Contact();
				contactDto.firstName = contact.FirstName;
				contactDto.lastName = contact.LastName;
				contactDto.email = contact.Email;
				this.contacts.add(contactDto);
			}
		}
	}
}

// Usage
DTO_Account accountDto = new DTO_Account();
accountDto.populate(accountId);

// With parameters
DTO_NameValues params = new DTO_NameValues();
params.add('includeContacts', 'false');
accountDto.populate(accountId, params);

Implementing transform() Methods ​

Sometimes the shape your code uses internally is not the shape an outside system expects. The transform() method converts one DTO into another, mapping and reshaping fields as it goes.

A common case: turn an internal DTO into the format an external API wants, for example renaming fields or bucketing a number into a category.

apex
/**
 * @description Internal Account DTO
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_AccountInternal extends DTO_JsonBase
{
	public String name;
	public String industryCode;
	public Decimal revenue;

	public override Type getObjectType()
	{
		return DTO_AccountInternal.class;
	}
}

/**
 * @description External API Account DTO
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_AccountExternal extends DTO_JsonBase
{
	public String companyName;
	public String industry;
	public String revenueCategory;

	/**
	 * @description Transform internal DTO to external format
	 */
	public override void transform(DTO_Base dtoBase)
	{
		if(dtoBase instanceof DTO_AccountInternal)
		{
			DTO_AccountInternal internal = (DTO_AccountInternal)dtoBase;

			// Map fields
			this.companyName = internal.name;

			// Transform industry code to readable name
			this.industry = getIndustryName(internal.industryCode);

			// Categorize revenue
			this.revenueCategory = categorizeRevenue(internal.revenue);
		}
	}

	private String getIndustryName(String code)
	{
		Map<String, String> industryMap = new Map<String, String>
		{
			'TECH' => 'Technology',
			'FIN' => 'Financial Services',
			'HEALTH' => 'Healthcare'
		};
		return industryMap.get(code);
	}

	private String categorizeRevenue(Decimal revenue)
	{
		if(revenue == null) return 'Unknown';
		if(revenue < 1000000) return 'Small';
		if(revenue < 10000000) return 'Medium';
		return 'Large';
	}

	public override Type getObjectType()
	{
		return DTO_AccountExternal.class;
	}
}

// Usage
DTO_AccountInternal internalDto = new DTO_AccountInternal();
internalDto.name = 'Acme Corp';
internalDto.industryCode = 'TECH';
internalDto.revenue = 5000000;

DTO_AccountExternal externalDto = new DTO_AccountExternal();
externalDto.transform(internalDto);

// externalDto.companyName: Acme Corp
// externalDto.industry: Technology
// externalDto.revenueCategory: Medium

Working with Base DTO Classes ​

DTO_Base - Foundation ​

Every DTO needs the same core behaviour: turn into a string, parse back from a string, load itself from a record, and compare equal to another DTO with the same content. DTO_Base is the virtual base class that gives all DTOs this behaviour:

apex
global inherited sharing virtual class DTO_Base
{
	global virtual String serialize()
	global virtual DTO_Base deserialize(String dtoString)
	global virtual void populate(Id recordId)
	global virtual void populate(Id recordId, DTO_NameValues dtoRequestParameters)
	global virtual void transform(DTO_Base dtoBase)
	public Boolean equals(Object obj)
	public Integer hashCode()
}

Key Methods:

MethodPurposeOverride Required
serialize()Convert DTO to string formatNo (DTO_JsonBase implements it)
deserialize()Parse string to DTONo (DTO_JsonBase implements it)
populate(Id)Load DTO from record IDOptional
transform()Convert between DTO typesOptional
equals() / hashCode()Support collectionsNo (implemented)

Example: Using equals() in Collections

apex
Set<DTO_Base> uniqueDtos = new Set<DTO_Base>();
uniqueDtos.add(dto1);
uniqueDtos.add(dto2);
uniqueDtos.add(dto1); // Duplicate ignored

if(dto1.equals(dto2))
{
	// DTOs are equal based on serialized content
}

DTO_JsonBase - JSON Handling ​

When your data needs to travel as JSON, which is almost always the case for APIs and Lightning components, extend DTO_JsonBase instead of DTO_Base directly. It builds on DTO_Base and handles JSON serialization for you, with these conveniences:

Key Features:

  1. Automatic JSON serialization: readable (pretty-printed) output that leaves out null fields.
  2. Type-safe deserialization: parses JSON straight back into the right class.
  3. JsonPath integration: read a field by its path through UTIL_JsonPath over the serialized DTO, without writing a getter for it.
  4. Sorting: put a list of DTOs in order with a small Comparator<T> class of your own.

Example: Basic JSON DTO

apex
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Person extends DTO_JsonBase
{
	public String firstName;
	public String lastName;
	public Date birthDate;
	public Decimal salary;

	public override Type getObjectType()
	{
		return DTO_Person.class;
	}
}

// Usage
DTO_Person person = new DTO_Person();
person.firstName = 'John';
person.lastName = 'Doe';
person.birthDate = Date.today();

// Serialize
String json = person.serialize();
// Output: {"firstName":"John","lastName":"Doe","birthDate":"2026-02-07"}

// Deserialize
DTO_Person deserialized = (DTO_Person)new DTO_Person().deserialize(json);

JsonPath Access:

apex
DTO_Person person = new DTO_Person();
person.firstName = 'John';

// Access fields reflectively by serializing through UTIL_JsonPath
UTIL_JsonPath path = new UTIL_JsonPath(person.serialize());
String firstName = path.findNode('firstName').getStringValue();
// firstName: John

Important: Override getObjectType() for Private Classes

If your DTO class is private, or public with no Type Resolver registered, you must override getObjectType() to name the class. When the framework parses JSON back into your DTO, it needs to know which class to build:

Your DTO classCan the framework find it?Override getObjectType()?
globalYes, on its ownNo
public, with a Type Resolver registered (see Type Resolution)YesNo
public, with no Type ResolverNoYes
privateNoYes
apex
// Private DTO class
private class DTO_InternalData extends DTO_JsonBase
{
	public String data;

	// REQUIRED for private classes
	public override Type getObjectType()
	{
		return DTO_InternalData.class;
	}
}

Built-in DTO Classes ​

DTO_NameValue ​

Purpose: Simple DTO for a single name-value pair, designed for use in Flow invocable methods, Aura components, and LWC.

Common Use Cases:

  • Email template merge fields in Flow
  • Parameter passing to invocable methods
  • Configuration key-value pairs
  • Dynamic field mapping
apex
/**
 * @description Using DTO_NameValue in an invocable method
 */
@SuppressWarnings('PMD.AvoidGlobalModifier')
global inherited sharing class FLOW_SendEmailWithMergeFields
{
	@InvocableMethod(category='Email' label='Send Email with Merge Fields' description='Sends an email using merge field values.')
	global static void execute(List<DTO_Request> requests)
	{
		if(requests == null || requests.size() != 1)
		{
			throw new IllegalArgumentException('FLOW_SendEmailWithMergeFields expects a single request');
		}
		DTO_Request request = requests.iterator().next();

		for(DTO_NameValue mergeField : request.mergeFields)
		{
			LOG_Builder.build().info('Field: ' + mergeField.name + ' = ' + mergeField.value).emitAt('FLOW_SendEmailWithMergeFields.execute');
		}
	}

	global inherited sharing class DTO_Request
	{
		@InvocableVariable(label='Template Name' description='The email template name' required=true)
		global String templateName;

		@InvocableVariable(label='Merge Fields' description='Name-value pairs for merge fields')
		global List<DTO_NameValue> mergeFields;
	}
}

Flow Usage:

In Flow Builder, DTO_NameValue appears as a structured input allowing users to specify name-value pairs:

PropertyTypeRequiredDescription
nameStringYesThe field name or placeholder key
valueStringNoThe value to associate with the name

Creating in Apex:

apex
// Create a single name-value pair
DTO_NameValue mergeField = new DTO_NameValue();
mergeField.name = 'recipientName';
mergeField.value = 'John Doe';

// Create a list for invocable methods
List<DTO_NameValue> mergeFields = new List<DTO_NameValue>();
mergeFields.add(mergeField);

DTO_NameValue vs DTO_NameValues:

FeatureDTO_NameValueDTO_NameValues
StructureSingle name-value pairCollection of pairs
Flow Support@InvocableVariableNot directly invocable
Aura/LWC Support@AuraEnabled@AuraEnabled
Use CaseFlow inputs, simple paramsComplex parameter maps
InheritanceStandalone classExtends DTO_JsonBase

DTO_NameValues ​

Purpose: Store and manipulate key-value pairs for parameter passing.

Common Use Cases:

  • API request parameters
  • Dynamic configuration
  • Flow variable collections
  • Email merge fields
apex
/**
 * @description Create and use DTO_NameValues
 */
public static void demonstrateNameValues()
{
	// Create from scratch
	DTO_NameValues params = new DTO_NameValues();
	params.add('firstName', 'John');
	params.add('lastName', 'Doe');
	params.add('email', 'john.doe@example.com');

	// Create from delimited string
	DTO_NameValues params2 = new DTO_NameValues('key1=value1,key2=value2');

	// Create from map
	Map<String, String> configMap = new Map<String, String>
	{
		'timeout' => '30000',
		'retryCount' => '3'
	};
	DTO_NameValues config = new DTO_NameValues(configMap);

	// Check existence
	if(params.exists('email'))
	{
		String email = params.get('email');
	}

	// Check multiple required parameters
	Set<String> requiredParams = new Set<String>{'firstName', 'lastName'};
	if(params.allExists(requiredParams, true)) // true = must be non-blank
	{
		// All required parameters present
	}

	// Serialize to JSON
	String json = params.serialize();

	// Convert to parameter string
	String paramString = params.toParameterString();
	// Output: firstName=John,lastName=Doe,email=john.doe@example.com
}

DTO_NameValues Properties ​

PropertyTypeDescription
sizeIntegerNumber of name-value pairs
namesSet<String>All parameter names
valuesList<String>All parameter values

DTO_NameValues Methods ​

MethodDescription
add(String name, String value)Add or update a parameter
get(String name)Get parameter value (null if not found)
exists(String name)Check if parameter exists
exists(String name, Boolean isNonBlank)Check existence and optionally validate non-blank
allExists(Set<String> names)Check if all parameters exist
isEmpty()Check if no parameters exist
toParameterString()Convert to "name=value,name=value" format

DTO_BaseTable ​

Purpose: Structure data for Lightning datatable components.

Features:

apex
/**
 * @description Build table data for LWC datatable
 */
@AuraEnabled(cacheable=true)
public static DTO_BaseTable getAccountTable()
{
	DTO_BaseTable table = new DTO_BaseTable();

	// Define columns (label, fieldName, type, sortable)
	table.addColumn('Account Name', 'name', 'text', true);
	table.addColumn('Industry', 'industry', 'text', true);
	table.addColumn('Annual Revenue', 'revenue', 'currency', true);
	table.addColumn('Website', 'website', 'url', false);
	table.addColumn('Active', 'isActive', 'boolean', false);

	// Add rows (can be any object type)
	List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
		.fields(new List<SObjectField>{Account.Name, Account.Industry, Account.AnnualRevenue, Account.Website})
		.withLimit(10)
		.toList();

	for(Account account : accounts)
	{
		DTO_AccountRow row = new DTO_AccountRow();
		row.name = account.Name;
		row.industry = account.Industry;
		row.revenue = account.AnnualRevenue;
		row.website = account.Website;
		row.isActive = true;

		table.addRow(row);
	}

	return table;
}

/**
 * @description Row DTO for table data
 */
public class DTO_AccountRow
{
	@AuraEnabled
	public String name;
	@AuraEnabled
	public String industry;
	@AuraEnabled
	public Decimal revenue;
	@AuraEnabled
	public String website;
	@AuraEnabled
	public Boolean isActive;
}

Lightning Datatable Column Types ​

Every supported column type
TypeDescriptionExample
textPlain textAccount Name
numberNumeric value12345
currencyCurrency formatted$50,000
percentPercentage25%
dateDate only2026-02-07
date-localDate (no timezone)2026-02-07
emailEmail addressuser@example.com
phonePhone number(555) 123-4567
urlHyperlinkhttps://example.com
booleanCheckboxtrue/false
buttonButton-
button-iconIcon button-
actionRow actions-

LWC Usage ​

javascript
// accountTable.js
import { wire } from 'lwc';
import { ComponentBuilder } from 'kern/componentBuilder';
import getAccountTable from '@salesforce/apex/AccountController.getAccountTable';

export default class AccountTable extends ComponentBuilder('controller')
{
	tableData;

	@wire(getAccountTable)
	wiredTable({ error, data })
	{
		if(data)
		{
			this.tableData = data;
		}
	}
}
html
<!-- accountTable.html -->
<template>
    <template if:true={tableData}>
        <lightning-datatable
            key-field="name"
            data={tableData.rows}
            columns={tableData.columns}
            hide-checkbox-column>
        </lightning-datatable>
    </template>
</template>

DTO_PickList ​

Purpose: Represent picklist field metadata for dynamic UI components.

Structure:

  • DTO_PickList - Container for picklist field

    • picklistName - Field API name
    • defaultValue - Default DTO_PicklistValue
    • values - List of DTO_PicklistValue objects
  • DTO_PicklistValue - Individual picklist entry

    • label - Display text
    • value - API value
    • validFor - Controlling field dependencies

Example: Using with Invocable Method

apex
/**
 * @description Get picklist values for Flow
 */
@InvocableMethod(label='Get Picklist Values' description='Returns picklist values for a field')
public static List<DTO_PickList> getPicklistValues(List<Request> requests)
{
	List<DTO_PickList> results = new List<DTO_PickList>();

	for(Request req : requests)
	{
		UTIL_SObjectDescribe describe = UTIL_SObjectDescribe.getDescribe(req.objectName);
		Schema.DescribeFieldResult fieldDescribe = describe.getFieldDescribe(req.fieldName);

		DTO_PickList pickList = new DTO_PickList();
		pickList.picklistName = req.fieldName;
		pickList.values = new List<DTO_PicklistValue>();

		for(Schema.PicklistEntry entry : fieldDescribe.getPicklistValues())
		{
			if(entry.isActive())
			{
				DTO_PicklistValue pickValue = new DTO_PicklistValue();
				pickValue.label = entry.getLabel();
				pickValue.value = entry.getValue();

				if(entry.isDefaultValue())
				{
					pickList.defaultValue = pickValue;
				}

				pickList.values.add(pickValue);
			}
		}

		results.add(pickList);
	}

	return results;
}

public class Request
{
	@InvocableVariable(required=true)
	public String objectName;

	@InvocableVariable(required=true)
	public String fieldName;
}

DTO_ChangeEventHeader ​

Purpose: When a Change Data Capture event fires, you often want a flow to read details about what changed and who committed it. This DTO carries the supported part of the event's ChangeEventHeader into Flow as a strongly-typed input variable. So your change-event-triggered flows can read the commit and change details directly, with no bridging Apex to write.

Structure: every field is @AuraEnabled, so it is readable from Flow and LWC.

Every field on the change-event header
FieldTypeDescription
entityNameStringAPI name of the changed entity (for example Account)
recordIdsList<String>Ids of the records affected by the change
changeTypeStringThe change operation (for example CREATE, UPDATE, DELETE, UNDELETE)
changeOriginStringOrigin of the change (the client or integration that made it)
transactionKeyStringIdentifier shared by all changes committed in the same transaction
sequenceNumberIntegerPosition of this change within its transaction
commitTimestampLongCommit time as epoch milliseconds
commitUserStringId of the user who committed the change
commitNumberLongSystem change number of the commit
nulledFieldsList<String>Fields the change explicitly set to null
diffFieldsList<String>Large text fields delivered as diffs rather than full values
changedFieldsList<String>Fields whose values changed

Usage: the framework populates this DTO automatically for change-event-triggered flows (it has a copy constructor from EventBus.ChangeEventHeader), so you do not need to write any bridging Apex. See the Triggers - Guide Change Data Capture section for the end-to-end setup, and reference/apex/DTO_ChangeEventHeader.md for the complete member list.


What else can it do? ​

JsonPath for Reflective Access ​

To read a field out of a DTO by its path, serialize the DTO and wrap it in UTIL_JsonPath, then read fields by path. This helps when the field is buried inside a nested object or an array, where a property is awkward to reach.

Each node gives you a typed getter that matches the field's type: getStringValue(), getIntegerValue(), getDecimalValue(), getBooleanValue(), getDateValue(), getDatetimeValue(), and getIdValue(). There is no untyped getValue(), so you always read the value as the type you expect.

apex
/**
 * @description Demonstrate JsonPath usage
 */
public static void demonstrateJsonPath()
{
	DTO_CustomerOrder order = new DTO_CustomerOrder();
	order.orderId = 'ORD-12345';
	order.customerName = 'John Doe';
	order.totalAmount = 125.00;

	DTO_OrderItem item = new DTO_OrderItem();
	item.productName = 'Widget A';
	item.quantity = 2;
	item.unitPrice = 25.00;
	order.lineItems.add(item);

	// Wrap the serialized DTO in UTIL_JsonPath for path-based reads
	UTIL_JsonPath path = new UTIL_JsonPath(order.serialize());

	// Access fields by path (use the typed getter that matches the underlying field)
	String orderId = path.findNode('orderId').getStringValue();
	// orderId: ORD-12345

	// Access nested fields
	String productName = path.findNode('lineItems[0].productName').getStringValue();
	// productName: Widget A

	// Check field existence
	if(path.exists('totalAmount'))
	{
		Decimal total = path.findNode('totalAmount').getDecimalValue();
	}
}

Common JsonPath Patterns:

PatternDescriptionExample
fieldNameTop-level fieldpath.findNode('orderId')
parent.childNested objectpath.findNode('shippingAddress.city')
array[0]Array indexpath.findNode('lineItems[0]')
array[0].fieldArray element fieldpath.findNode('lineItems[0].productName')

Sorting DTOs ​

To put a list of DTOs in order, write a small class implementing Salesforce's built-in Comparator<T> interface for your DTO type, then call List.sort(comparator). Because the field lives on your own class, you compare the property directly and the compiler checks it for you.

apex
/**
 * @description Orders a list of customer orders by total amount, smallest first.
 */
public with sharing class OrderAmountComparator implements Comparator<DTO_CustomerOrder>
{
	/**
	 * @description Compares two orders by their total amount.
	 *
	 * @param first The first order to compare.
	 * @param second The second order to compare.
	 *
	 * @return -1, 0 or 1 in the usual comparator sense.
	 */
	public Integer compare(DTO_CustomerOrder first, DTO_CustomerOrder second)
	{
		if(first.totalAmount == second.totalAmount)
		{
			return 0;
		}
		return first.totalAmount < second.totalAmount ? -1 : 1;
	}
}

// Then sort with it
orders.sort(new OrderAmountComparator());

To sort by a different field, or in the other direction, write another comparator the same way and pass that instead.


DTO Collections and Equality ​

DTOs implement equals() and hashCode(), treating two DTOs as equal when their serialized content matches. So you can drop DTOs into a Set to remove duplicates, or use one as a Map key, and Sets and Maps work as you would expect.

apex
/**
 * @description Demonstrate DTO collections
 */
public static void demonstrateCollections()
{
	DTO_CustomerOrder order1 = new DTO_CustomerOrder();
	order1.orderId = 'ORD-001';
	order1.totalAmount = 100.00;

	DTO_CustomerOrder order2 = new DTO_CustomerOrder();
	order2.orderId = 'ORD-001';
	order2.totalAmount = 100.00;

	DTO_CustomerOrder order3 = new DTO_CustomerOrder();
	order3.orderId = 'ORD-002';
	order3.totalAmount = 200.00;

	// Equality based on serialized JSON
	Boolean areEqual = order1.equals(order2); // true (same content)
	Boolean areDifferent = order1.equals(order3); // false (different content)

	// Use in Sets (duplicates removed)
	Set<DTO_JsonBase> uniqueOrders = new Set<DTO_JsonBase>();
	uniqueOrders.add(order1);
	uniqueOrders.add(order2); // Duplicate, not added
	uniqueOrders.add(order3);
	// uniqueOrders.size(): 2

	// Use as Map keys
	Map<DTO_JsonBase, String> orderMap = new Map<DTO_JsonBase, String>();
	orderMap.put(order1, 'Processing');
	orderMap.put(order2, 'Shipped'); // Overwrites order1
	orderMap.put(order3, 'Delivered');
	// orderMap.size(): 2
}

How do I connect it to my code? ​

DTOs in REST APIs ​

When you build a REST endpoint, DTOs give you a clear contract for the request you accept and the response you return. Here is a full inbound REST API built on the API_Inbound base class: a request DTO carries the incoming data, and a response DTO carries what you send back.

apex
/**
 * @description REST endpoint for order management
 */
@RestResource(urlMapping='/v1/orders/*')
global inherited sharing class REST_Orders
{
	@HttpPost
	global static void createOrder()
	{
		API_Dispatcher.processInboundService(API_CreateOrder.class.getName());
	}
}

/**
 * @description Create order API implementation
 */
public with sharing class API_CreateOrder extends API_Inbound
{
	private Foobar__c order;

	public override void configure()
	{
		super.configure();
		requestPayload = new DTO_Request();
		responsePayload = new DTO_Response();
	}

	public override List<String> getValidationErrors()
	{
		List<String> errors = new List<String>();
		DTO_Request dto = (DTO_Request)requestPayload;

		if(String.isBlank(dto.customerName))
		{
			errors.add('Customer name is required');
		}

		return errors;
	}

	public override void onSuccess()
	{
		super.onSuccess();
		DTO_Request dto = (DTO_Request)requestPayload;

		order = new Foobar__c();
		order.Name = dto.customerName;

		doInsert(order);
	}

	public override void updateResponseDTO()
	{
		DTO_Response dto = (DTO_Response)responsePayload;

		if(result.isSuccess)
		{
			dto.success = true;
			dto.orderId = order.Id;
			dto.message = 'Order created successfully';
		}
	}

	@JsonAccess(deserializable='always')
	public class DTO_Request extends DTO_JsonBase
	{
		/**
		 * @description The customer name.
		 */
		public String customerName;

		/**
		 * @description The order date.
		 */
		public Date orderDate;

		/**
		 * @description The total amount.
		 */
		public Decimal totalAmount;
	}

	@JsonAccess(serializable='always')
	public class DTO_Response extends DTO_JsonBase
	{
		/**
		 * @description Whether the operation was successful.
		 */
		public Boolean success;

		/**
		 * @description The created order ID.
		 */
		public String orderId;

		/**
		 * @description A status message.
		 */
		public String message;
	}
}

DTOs in LWC Components ​

When a Lightning component needs structured data from Apex, return it as a serialized DTO and parse it on the client. The Apex controller below builds a DTO, serializes it to JSON, and returns the string; the JavaScript that follows parses it back into a plain object.

apex
/**
 * @description LWC controller for customer dashboard
 */
public with sharing class CustomerDashboardController
{
	/**
	 * @description Get customer summary data
	 */
	@AuraEnabled(cacheable=true)
	public static String getCustomerSummary(Id customerId)
	{
		Account customer = (Account)new SEL_Accounts().findById(customerId);

		DTO_CustomerSummary summary = new DTO_CustomerSummary();
		summary.customerName = customer.Name;
		summary.industry = customer.Industry;
		summary.revenue = customer.AnnualRevenue;
		summary.phone = customer.Phone;

		return summary.serialize();
	}
}

/**
 * @description Customer summary DTO
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerSummary extends DTO_JsonBase
{
	@AuraEnabled
	public String customerName;

	@AuraEnabled
	public String industry;

	@AuraEnabled
	public Decimal revenue;

	@AuraEnabled
	public String phone;

	public override Type getObjectType()
	{
		return DTO_CustomerSummary.class;
	}
}

LWC JavaScript:

javascript
import { api, wire } from 'lwc';
import { ComponentBuilder } from 'kern/componentBuilder';
import getCustomerSummary from '@salesforce/apex/CustomerDashboardController.getCustomerSummary';

export default class CustomerDashboard extends ComponentBuilder('controller')
{
	@api recordId;
	customerData;

	@wire(getCustomerSummary, { customerId: '$recordId' })
	wiredCustomer({ error, data })
	{
		if(data)
		{
			this.customerData = JSON.parse(data);
		}
	}
}

Passing Complex DTOs as @AuraEnabled Parameters ​

Never pass a complex DTO directly as an @AuraEnabled method parameter. The call fails at runtime with messages such as "Unable to deserialize to specified type" or "cannot be deserialized from non-object type".

Here is why it breaks. LWC wraps reactive objects in a Proxy before serializing them. When the target type is a DTO that extends DTO_JsonBase (or any class with nested collections), Aura's parameter deserializer rejects that Proxy wrapper.

The pattern that works: accept a String requestJson parameter on the controller, then deserialize it with JSON.deserialize(...) inside the method. The client stringifies the DTO before calling. This is the pattern used throughout the framework.

apex
// CORRECT — accept String, deserialize server-side
@AuraEnabled
public static Id saveRecord(String requestJson)
{
	SaveRequest request = (SaveRequest)JSON.deserialize(requestJson, SaveRequest.class);
	// ... use request.className, request.cronExpression, ...
}

// WRONG — passing the DTO directly fails with LWC Proxy
@AuraEnabled
public static Id saveRecord(SaveRequest request) { /* runtime deserialization error */ }
javascript
// LWC caller stringifies before invoking
await this.callControllerMethod('saveRecord', {requestJson: JSON.stringify(this.request)});

This restriction applies only to input parameters. Return values are fine: an @AuraEnabled method can return a complex DTO, because Aura serializes DTO instances to JSON correctly on the way out, and LWC consumes them as plain JavaScript objects.


DTOs in Flow Invocables ​

When an admin calls your Apex from a flow, DTOs let you accept and return structured inputs instead of a long list of loose parameters. The invocable method below takes a request DTO (with a list of name-value merge fields) and returns a response DTO reporting success or failure.

apex
/**
 * @description Send email with dynamic merge fields (Flow invocable)
 */
@SuppressWarnings('PMD.AvoidGlobalModifier')
global inherited sharing class FLOW_SendCustomEmail
{
	@InvocableMethod(category='Email' label='Send Custom Email' description='Sends an email with dynamic merge fields.')
	global static List<DTO_Response> execute(List<DTO_Request> requests)
	{
		if(requests == null || requests.size() != 1)
		{
			throw new IllegalArgumentException('FLOW_SendCustomEmail expects a single request');
		}
		DTO_Request request = requests.iterator().next();

		DTO_Response response = new DTO_Response();

		try
		{
			String emailBody = request.templateBody;

			for(DTO_NameValue mergeField : request.mergeFields)
			{
				String placeholder = '{!' + mergeField.name + '}';
				emailBody = emailBody.replace(placeholder, mergeField.value);
			}

			Messaging.SingleEmailMessage email = new Messaging.SingleEmailMessage();
			email.setToAddresses(new List<String>{request.recipientEmail});
			email.setSubject(request.subject);
			email.setPlainTextBody(emailBody);

			Messaging.sendEmail(new List<Messaging.SingleEmailMessage>{email});

			response.success = true;
			response.message = 'Email sent successfully';
		}
		catch(Exception error)
		{
			response.success = false;
			response.message = 'Error: ' + error.getMessage();
			LOG_Builder.build().error(error).emitAt('FLOW_SendCustomEmail.execute');
		}

		return new List<DTO_Response> {response};
	}

	global inherited sharing class DTO_Request
	{
		@InvocableVariable(label='Recipient Email' description='The email address to send to' required=true)
		global String recipientEmail;

		@InvocableVariable(label='Subject' description='The email subject line' required=true)
		global String subject;

		@InvocableVariable(label='Template Body' description='The email body template with merge field placeholders' required=true)
		global String templateBody;

		@InvocableVariable(label='Merge Fields' description='Name-value pairs for template merge fields')
		global List<DTO_NameValue> mergeFields;
	}

	global inherited sharing class DTO_Response
	{
		@InvocableVariable(label='Success' description='Whether the email was sent successfully')
		global Boolean success;

		@InvocableVariable(label='Message' description='Status or error message')
		global String message;
	}
}

Testing ​

Aim your tests at the behaviour you wrote: your populate() and transform() overrides, plus a quick round-trip check that your DTO survives serialize-then-deserialize. You do not need to test the parts of a DTO that the framework already covers: the base classes (DTO_Base, DTO_JsonBase) come tested.

In practice you test DTOs through the place they are used: a web service test, a Lightning controller test, or a flow invocable test.

Testing serialize/deserialize round-trips:

apex
@IsTest
private static void shouldSerializeAndDeserializeSuccessfully()
{
	DTO_OrderSummary original = new DTO_OrderSummary();
	original.orderId = 'ORD-001';
	original.totalAmount = 250.00;

	String json = original.serialize();
	DTO_OrderSummary deserialized = (DTO_OrderSummary)new DTO_OrderSummary().deserialize(json);

	Assert.areEqual(original.orderId, deserialized.orderId, 'Order ID should survive round-trip');
	Assert.areEqual(original.totalAmount, deserialized.totalAmount, 'Total amount should survive round-trip');
}

Testing populate() with TST_Mock:

When your DTO's populate() method reads records through a selector, you can test it without inserting any data. Register the record you expect with TST_Mock, then call populate() and assert on the result. This example tests the DTO_Account class from Implementing populate() Methods:

apex
@IsTest
private static void shouldPopulateFromRecord()
{
	Account mock = (Account)TST_Mock.of(Account.SObjectType)
		.withOverride(Account.Name, 'Acme Corp')
		.build();

	DTO_Account dto = new DTO_Account();
	dto.populate(mock.Id, null);

	Assert.areEqual('Acme Corp', dto.accountName, 'Account name should be populated from record');

	TST_Mock.clear();
}

Testing transform():

apex
@IsTest
private static void shouldTransformBetweenFormats()
{
	DTO_AccountInternal internal = new DTO_AccountInternal();
	internal.name = 'Acme Corp';
	internal.industryCode = 'TECH';

	DTO_AccountExternal external = new DTO_AccountExternal();
	external.transform(internal);

	Assert.areEqual('Acme Corp', external.companyName, 'Company name should be mapped');
	Assert.areEqual('Technology', external.industry, 'Industry code should be translated');
}

Testing DTOs in web service context:

For DTOs used inside API classes, test through API_OutboundTestHelper assertions. The framework populates and serializes the DTO for you, so your test checks the whole call end to end rather than the DTO on its own. See Web Services - Guide for patterns.


Anti-Patterns ​

The common mistakes with DTOs, what goes wrong in each case, and what to do instead:

Anti-PatternWhy It's WrongInstead
Missing @JsonAccess on DTOs in your orgSerialisation fails at runtime with a security error in managed package contextAlways add @JsonAccess(serializable='always' deserializable='always') on every DTO extending a framework base class
Business logic inside populate()Makes the DTO untestable in isolation and violates single responsibilityKeep populate() limited to data mapping; move logic to service classes or trigger actions
Skipping type resolver registration in your orgDeserialisation fails with IllegalArgumentException because the managed package cannot resolve your class namesRegister a ClassTypeResolver__mdt record or implement a custom UTIL_TypeResolver
Using raw Map<String, Object> instead of typed DTOsNo compile-time safety, hard to refactor, error-prone key accessCreate a DTO class extending DTO_JsonBase for structured data
Null-unsafe access to DTO propertiesCauses NullPointerException at runtime when optional fields are missingUse null checks or default values before accessing optional DTO properties
Passing a complex DTO directly as an @AuraEnabled parameterLWC Proxy-wraps the object and Aura cannot deserialize it into the DTO type, so the call fails with "Unable to deserialize to specified type"Accept String requestJson on the controller, call JSON.deserialize(...) server-side; stringify in the LWC caller

Best Practices ​

Habits that keep DTOs easy to read, test, and maintain.

Use Appropriate DTO Type ​

apex
// GOOD: JSON API
@JsonAccess(serializable='always' deserializable='always')
public class DTO_ApiRequest extends DTO_JsonBase { }

Implement getObjectType() for Private Classes (OR Use Type Resolver) ​

Option A: Override getObjectType() in each DTO (simple approach):

apex
// GOOD for small number of DTOs
private class DTO_InternalData extends DTO_JsonBase
{
	public String data;

	public override Type getObjectType()
	{
		return DTO_InternalData.class;
	}
}

Option B: Register custom type resolver (recommended for 10+ DTOs):

apex
// BETTER for many DTOs - no getObjectType() needed in your public DTOs
// Just register CustomDTOTypeResolver in ClassTypeResolver__mdt

@JsonAccess(serializable='always' deserializable='always')
public class DTO_ExternalData extends DTO_JsonBase
{
	public String data;
	// No getObjectType() method needed - the registered resolver finds this class
}

// A private class still needs its own getObjectType() override
private class DTO_InternalData extends DTO_JsonBase
{
	public String data;

	public override Type getObjectType()
	{
		return DTO_InternalData.class;
	}
}

See Type Resolution: CRITICAL Requirement in Your Org for setup details.

Use @AuraEnabled for LWC ​

For a DTO field to be readable from a Lightning Web Component, mark it with @AuraEnabled. Fields without it are invisible to the front end:

apex
// GOOD
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Data extends DTO_JsonBase
{
	@AuraEnabled
	public String fieldName;
}

Initialize Collections ​

apex
// GOOD
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Order extends DTO_JsonBase
{
	public List<DTO_OrderItem> lineItems;

	public DTO_Order()
	{
		lineItems = new List<DTO_OrderItem>();
	}
}

Handle Null Values ​

apex
// GOOD
this.industry = String.isNotBlank(account.Industry) ? account.Industry : 'Unknown';

// BAD
this.industry = account.Industry.toUpperCase(); // Null pointer risk

Use Clear Naming ​

apex
// GOOD
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrderRequest extends DTO_JsonBase { }

// BAD
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Data extends DTO_JsonBase { } // Vague

Document Complex DTOs ​

apex
/**
 * @description Customer order request DTO for external order management system
 */
@JsonAccess(serializable='always' deserializable='always')
public class DTO_CustomerOrderRequest extends DTO_JsonBase
{
	/**
	 * @description Unique order ID from external system
	 */
	public String externalOrderId;
}

Validate DTO Data ​

apex
public override List<String> getValidationErrors()
{
	List<String> errors = new List<String>();
	DTO_Request dto = (DTO_Request)requestPayload;

	if(String.isBlank(dto.customerName))
	{
		errors.add('Customer name is required');
	}

	return errors;
}

Keep DTOs Focused ​

apex
// GOOD: Focused DTO
@JsonAccess(serializable='always' deserializable='always')
public class DTO_AccountBasic extends DTO_JsonBase
{
	public String name;
	public String industry;
}

// BAD: Over-complicated
@JsonAccess(serializable='always' deserializable='always')
public class DTO_Everything extends DTO_JsonBase
{
	// Too many unrelated fields
}

Troubleshooting ​

These errors cover almost every problem people run into with DTOs.

Issue: "Type cannot be deserialized as it is not globally visible" or "System.JSONException: Type cannot be constructed" ​

Cause: Your DTO extends an installed managed package base class but is missing the @JsonAccess annotation.

This is the most common error people hit with KernDX DTOs from an installed package.

Error Example:

text
System.JSONException: Type cannot be deserialized as it is not globally visible - DTO_CustomerOrder

Solution: Add @JsonAccess(serializable='always' deserializable='always') to your DTO class. See the full WRONG/CORRECT example in Creating JSON DTOs.

If the message is Unable to resolve type for class instead, the cause is different: the framework cannot find your class. See Type Resolution: CRITICAL Requirement in Your Org.

Why this is required: When your code extends a managed package class (for example YourNamespace.DTO_JsonBase) and the package's code then tries to serialize or deserialize your class, Salesforce security requires you to grant explicit permission with the @JsonAccess annotation. Without it, the operation fails with a security error.


Issue: "Unable to deserialize to specified type" ​

Cause: Missing getObjectType() implementation for private DTO class.

Solution Option 1 - Override getObjectType() in each DTO:

apex
public override Type getObjectType()
{
	return DTO_MyClass.class;
}

Solution Option 2 - Register custom type resolver (recommended for 10+ DTOs):

  1. Create custom resolver (see the complete implementation in Type Resolution)
  2. Register in ClassTypeResolver__mdt with ClassName__c = 'CustomDTOTypeResolver'
  3. Remove getObjectType() from all DTOs - type resolution is now automatic!

Issue: "Null pointer exception when accessing DTO fields" ​

Cause: Collection not initialised.

Solution:

apex
public DTO_Order()
{
	lineItems = new List<DTO_OrderItem>();
}

Issue: "DTO fields not visible in LWC" ​

Cause: Missing @AuraEnabled.

Solution:

apex
@AuraEnabled
public String fieldName;

Reference ​

DTO Framework Classes ​

ClassPurposeExtends
DTO_BaseVirtual base for all DTOs-
DTO_JsonBaseJSON serializationDTO_Base
DTO_NameValuesKey-value collectionsDTO_JsonBase
DTO_BaseTableLightning datatableDTO_JsonBase
DTO_PickListPicklist metadata-

Key Methods ​

DTO_Base:

apex
global virtual String serialize()
global virtual DTO_Base deserialize(String dtoString)
global virtual void populate(Id recordId)
global virtual void transform(DTO_Base dtoBase)