Mapper Creator

Preflight: Spring MCP

This skill is part of the Spring Agent Toolkit and is designed to work with the Spring MCP server (provided by the Amplicode IntelliJ plugin). Before doing anything else, check your tool list for any Spring MCP tool — they are exposed under the amplicode MCP server (e.g. get_project_summary, list_module_dependencies, get_entity_details); harnesses that flatten MCP tools into the tool list use the mcp__amplicode__ prefix on the same names.

• If at least one Amplicode tool is available — MCP is connected. Proceed with the skill below.
• If none are available — stop and invoke the `amplicode-install` skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the MCP tools become available — resume this skill.
• If amplicode-install is not registered in your skill list, tell the user (in their language): "This skill needs the Amplicode IntelliJ plugin and its MCP server. Install it from https://amplicode.ru/marketplace into IntelliJ IDEA Ultimate/Community or GigaIDE, open any project, click «Настроить Spring Agent» on the Amplicode welcome screen, then restart your MCP client."

---

Mapper Creator

Creates a mapper (MapStruct interface/abstract class or custom converter) for converting between an entity and a DTO.

---

CRITICAL: Code ONLY from examples/ files. If no matching example -- STOP and ask user.

CRITICAL: For questions with a fixed set of choices, prefer `AskUserQuestion` > its analogue > plain text list. Plain numbered text lists are the last resort when no interactive tool is available.

CRITICAL: Read the conversation context BEFORE running Step 1. Half the questions in Steps 2–3 may already be answered by the user's prompt and prior turns. Re-asking what was already said is the #1 reason this skill feels slow.

---

Defaults

Smart defaults: If the user says "use defaults", "all defaults", "default settings" -- skip all questions where "Always ask?" = NO. Ask only the required ones.

Smart answer recognition: When the user directly provides a value instead of choosing from a list -- accept it. Examples:

• Question "Which entity?" -> user answers "Order" -> that IS the entity
• Question "Mapper type?" -> user answers "mapstruct" -> that IS the choice
• If the user gave multiple answers in one message -> accept all, skip the answered questions
• NEVER re-ask what the user has already answered (even indirectly)

Batch questions: Group related questions into a single AskUserQuestion call (up to 4 questions):

• The main question (mapper type) is always asked SEPARATELY
• Do not group questions from DIFFERENT decision branches
• Prefer AskUserQuestion; fall back to plain text only if the tool is unavailable

---

Step 0 -- Conversation context first (REQUIRED, no tool calls)

Before any MCP call, before any question, re-read the user's prompt and the prior turns of this conversation and extract whatever is already stated. This step costs nothing and prevents the most common failure mode of this skill — asking the user something they already said.

Build a mental checklist of inputs and tick off everything the user has already provided, explicitly or implicitly:

For every input that is explicitly or strongly implicitly answered: mark it as decided and skip the corresponding question in Steps 2–3. Do NOT ask "which entity?" if the user wrote "create a mapper for Order to OrderDto" — both entity and DTO are answered. Do NOT ask "MapStruct or Custom?" if the user wrote "create a MapStruct mapper".

For every input that is not answered: defer to the Decision-making principle below — try to derive it from project context first (Step 1), and only then ask.

Step 0 is mental, not a tool call. Do not announce it to the user. Do not write "Step 0 done". Just internalize what the user already said before proceeding to Step 1.

---

Decision-making principle — context first, then ask

Before asking the user any question, attempt to derive the answer from the context already gathered: project summary, module dependencies, entity details, existing files in the package, prior turns of this conversation, and the user's original prompt. Only ask when the context yields no clear default or when the choice is genuinely user-specific (e.g. which entity, which DTO).

Hierarchy of decisions:

1. Context is unambiguous → decide silently, do NOT ask. Examples: language and module from get_project_summary; MapStruct presence from list_module_dependencies; mapper package from the DTO's package; className from {Entity}Mapper; componentModel from Spring presence; mapperType when the user said "MapStruct" or "Custom" outright.

2. Context gives a strong signal → state the decision + alternatives in one line, let the user override or stay silent. Format:

   Will create `OrderMapper` (MapStruct, componentModel=spring, in the same package as `OrderDto`).
   Alternatives: Custom mapper. OK?

The user can answer "ok" / "yes" / silence → accept; or name an alternative → switch.

3. Context yields no clear default → ask with `AskUserQuestion` (preferred) or its analogue, with the recommended option first and `(Recommended)` appended. Fall back to plain text if no interactive tool is available.

4. Context is fully empty for a critical input → ask plainly. This applies to: which entity, which DTO (when neither was mentioned), the user's intent itself.

How to ask — prefer AskUserQuestion

When a question must be asked, prefer the `AskUserQuestion` tool (or its analogue) over writing a numbered list in the response body. Fall back to plain text only if no interactive choice tool is available.

Rules for AskUserQuestion calls in this skill:

• Each call may contain up to 4 questions that are independent of each

other (the tool will render them together). Use this to batch related decisions in one round-trip.

• Each question has 2–4 options. The tool auto-adds an "Other" choice

for free-form input — never include it manually.

• Mark the recommended option by putting it first with (Recommended)

appended to the label.

• header is a 12-char chip label (e.g. "Mapper", "Methods", "Package").
• Each option has a description explaining what the choice means.

When AskUserQuestion is not the right tool:

• Free-form input where there is no enumerable set of options

(e.g. arbitrary class name) — ask in plain text.

• The "single confirmation line" form from principle 2 — that is a plain

yes/no, not an enumerated choice.

The screen-driven question lists in Steps 2–3 below are a fallback for case 4. They are NOT a script to execute top-to-bottom. If a question's answer is already determined by principles 1–3, skip the question.

---

Step 1 -- Gather minimal project context (automatic, no questions)

Call only the MCP tools whose result is actually consumed by a later step. Do not pre-fetch "in case we need it" — every variable here must have a concrete downstream user.

That is the entire Step 1. Do NOT fetch:

• Spring Boot version — no branching depends on it
• application.properties path — Step 5 writes nothing to properties
• mainPackage — Step 4 derives the mapper package from the DTO's

package, not from the project root

• get_entity_details / list_class_members — these depend on knowing

the entity and DTO, which happens in Step 2. Defer them to Step 2.

• list_entity_mappers — needed only at Step 13 of the MapStruct

reference (uses = {...} resolution) and only per association entity, which is unknown until entityDetails is fetched. Defer to Step 13, do NOT pre-fetch in Step 1.

If multi-module project (multiple modules in get_project_summary): Ask which module to use. Then re-call list_module_dependencies for that module.

componentModel — simplified

Determine componentModel from presentDeps:

• Spring (any spring-boot-starter* or spring-context) → SPRING
• Otherwise → DEFAULT

CDI is intentionally not auto-detected. If the user has a CDI project and wants componentModel = "cdi", they will say so explicitly; the skill should not branch on it by default.

---

Step 2 -- Entity and DTO

By Step 0 you should already know entity and DTO if the user mentioned them. Most common cases:

• User wrote "create a mapper for Order to OrderDto" → both known, skip

the questions, go straight to the parallel fetch below.

• `dto-creator` just delegated → entity and DTO are passed in by the

delegating skill. Never ask, never re-derive.

• User wrote "create a mapper for Order" → entity is Order. The DTO

is the most recently created/discussed DTO for that entity in this conversation, OR — if there are multiple candidates — call list_entity_dtos(orderFqn) and pick the unique one. Only ask if there are multiple and no other signal.

Ask only when context is genuinely empty. When asking, prefer plain text (entity/DTO names are free-form input — AskUserQuestion is the wrong tool here):

Which entity should I create a mapper for? And which DTO to map to?

After both entity FQN and DTO FQN are known, call (in parallel):

Both calls are deferred to Step 2 because they require Step 2's inputs. They are NOT part of Step 1.

---

Step 3 -- Mapper type and variant settings

Mapper type — context first

Apply the Decision-making principle. Decide silently when context is clear:

Only fall back to AskUserQuestion when none of the rows above matches. Use it with these options:

Variant settings — defaults are usually correct

For both MapStruct and Custom variants the defaults are almost always correct:

• className = {EntityName}Mapper
• packageName = same package as the DTO
• partialUpdate = no
• updateWithNull = no

Do NOT batch-ask these settings unless the user explicitly requested configuration ("configure methods", "I want partial update") or said something that contradicts a default.

When the user did ask for configuration, use a single AskUserQuestion call (multiSelect: true) with the relevant subset:

Class name and package are free-form — ask in plain text only when the user said "I want a different name" or "in a different package".

---

Step 4 -- Generate code

Determine the reference file based on mapper type and language:

• MapStruct + Java -> read references/mapstruct-java.md
• MapStruct + Kotlin -> read references/mapstruct-kotlin.md
• Custom + Java -> read references/custom-java.md
• Custom + Kotlin -> read references/custom-kotlin.md

Read the corresponding reference file and follow its Generation order exactly.

Building @Mapping annotations

Read references/mapping-annotations.md for rules on how to build @Mapping annotations.

Compare entity fields from entityDetails with DTO fields from dtoFields: 1. Match DTO fields to entity fields by name 2. For fields with different names, add @Mapping(source, target) 3. For association ID fields (e.g. customerId -> customer.id), add appropriate mapping 4. For flat fields (e.g. customerName -> customer.name), add expression or source.target mapping

Reading skeleton and fragments

1. Read the skeleton file from examples/_skeletons/{variant}-{language}.md 2. Apply variable substitutions 3. Write the file 4. For each fragment in the generation order:

• Check if the fragment's condition is met
• Read the fragment from examples/_fragments/{fragment-name}/{language}.md
• Apply variable substitutions
• Insert/edit into the created file

Variable substitution rules

• {packageName} -> from Step 1 context or user answer
• {className} -> from user answer or default {EntityName}Mapper
• {entityClassFqn} -> entity FQN from context
• {dtoClassFqn} -> DTO FQN from context
• {entityParamName} -> decapitalized entity short name
• {dtoParamName} -> decapitalized DTO short name
• {methodName} -> from naming conventions (see references/method-naming.md)
• NEVER substitute anything not listed in Variables section of the example file
• NEVER add imports, methods, or code not in the example
• FQN handling (CRITICAL): examples contain FQNs (e.g. org.mapstruct.Mapper,

org.mapstruct.Mapping, org.mapstruct.ReportingPolicy, org.mapstruct.MappingConstants.ComponentModel.SPRING, entity/DTO FQNs). When writing the final file, you MUST: 1. Replace every FQN in the body with its short name (e.g. @org.mapstruct.Mapper(...) -> @Mapper(...), org.mapstruct.ReportingPolicy.IGNORE -> ReportingPolicy.IGNORE, {entityClassFqn} -> entity short name, {dtoClassFqn} -> DTO short name). 2. Collect every FQN you shortened and emit a corresponding import line right after the package statement, sorted, no duplicates. 3. Classes from the same package as the mapper (entity, DTO if collocated) must NOT be imported — just use the short name. 4. Types from java.lang must NOT be imported. 5. Kotlin: same rules — shorten in the body and add import lines at the top. Kotlin does not need imports for classes in the same package. 6. The IDE will NOT optimize imports for you — the file is saved as-is.

---

Step 5 -- Add MapStruct dependencies (automatic, MapStruct variant only)

For Custom mapper: skip this step entirely. Custom mappers have no external dependencies.

For MapStruct: check presentDeps and add missing artifacts to the project's build file.

Required artifacts

If neither artifact is missing from presentDeps, skip the rest of this step — nothing to add.

How to edit the build file

Use the buildFile path captured in Step 1 — that is the exact file the skill must edit. Do NOT guess; do NOT search the project for build files.

Pick the editing strategy by file extension:

• `build.gradle.kts` — add implementation("org.mapstruct:mapstruct:{version}")

inside the existing dependencies { … } block. For the processor:

• Java project → annotationProcessor("org.mapstruct:mapstruct-processor:{version}")
• Kotlin project → kapt("org.mapstruct:mapstruct-processor:{version}") (apply kotlin("kapt") plugin if not present) or ksp(...) if KSP is already configured
• `build.gradle` (Groovy) — same as above, with single-quoted Groovy syntax
• `pom.xml` — add a <dependency> entry inside <dependencies> with <scope> matching the role (compile for mapstruct, processor configured via maven-compiler-plugin <annotationProcessorPaths>)

For the version: do NOT hardcode. Read the latest stable MapStruct version from the project's existing version catalogue (e.g. gradle/libs.versions.toml) if present; otherwise use the version that matches the Spring Boot BOM / project parent if Maven; otherwise emit a property/variable placeholder and ask the user to confirm.

Use the Edit tool with {buildFile} as file_path. Make the edit minimally — insert the new lines into the existing dependencies block, do not rewrite the file.

No properties needed

Mapper creation does not write any application.properties entries.

Report: "Created mapper {className} in package {packageName}. Type: {mapperType}. Methods: {list of methods}."

---

Anti-hallucination checklist

Before writing ANY code, verify:

• [ ] The code comes from an examples/ file (cite which one)
• [ ] Only declared variables were substituted
• [ ] No framework API calls were added "from knowledge"
• [ ] Import list matches the example exactly
• [ ] Method signatures match the example exactly
• [ ] No comments or convenience methods were added
• [ ] FQNs from examples are shortened in the body AND corresponding import lines were added after package (IDE will NOT do this for you)
• [ ] @Mapping annotations match entity-DTO field comparison, not guessed
• [ ] Kotlin: multiple @Mapping wrapped in @Mappings(value = [...])
• [ ] @AfterMapping only added when entity has non-owner associations with mappedBy + sub-DTO
• [ ] toDto uses individual @Mapping(source, target) pairs by default — @InheritInverseConfiguration only when the user explicitly asked for it
• [ ] Flat collection helper is generated only in toDto direction; toEntity does NOT try to load entities by id (no repository injection)
• [ ] Flat collection helper name follows {assocFieldName}To{capitalize(flatDtoFieldName)} (e.g. petsToPetIds, not petsToId)

@AfterMapping method (Java)

Insert Point

Default method in mapper interface body.

Code

skip this fragment (only added when entity has non-owner OneToOne/OneToMany with mappedBy + sub-DTO)

OneToMany association

@org.mapstruct.AfterMapping
default void link{entityAttrNameCapitalized}(@org.mapstruct.MappingTarget {entityClassFqn} {entityParamName}) {
    {entityParamName}.get{entityAttrNameCapitalized}().forEach({unpluralizedAttrName} -> {unpluralizedAttrName}.set{inverseAttributeNameCapitalized}({entityParamName}));
}

OneToOne association

@org.mapstruct.AfterMapping
default void link{entityAttrNameCapitalized}(@org.mapstruct.MappingTarget {entityClassFqn} {entityParamName}) {
    {attrTypeEntityFqn} {entityAttrName} = {entityParamName}.get{entityAttrNameCapitalized}();
    if ({entityAttrName} != null) {
        {entityAttrName}.set{inverseAttributeNameCapitalized}({entityParamName});
    }
}

Variables

@AfterMapping method (Kotlin)

Insert Point

Function in mapper abstract class body.

Code

skip this fragment (only added when entity has non-owner OneToOne/OneToMany with mappedBy + sub-DTO)

OneToMany association

@org.mapstruct.AfterMapping
fun link{entityAttrNameCapitalized}(@org.mapstruct.MappingTarget {entityParamName}: {entityClassFqn}) {
    {entityParamName}.{entityAttrName}.forEach { it.{inverseAttributeName} = {entityParamName} }
}

OneToOne association

@org.mapstruct.AfterMapping
fun link{entityAttrNameCapitalized}(@org.mapstruct.MappingTarget {entityParamName}: {entityClassFqn}) {
    {entityParamName}.{entityAttrName}?.{inverseAttributeName} = {entityParamName}
}

Variables

mapFromAggregateReference helper (Java)

Insert Point

Default method in mapper interface body.

Code

skip this fragment (only for Spring Data JDBC entities with AggregateReference attributes)

When entity has AggregateReference attributes with ID sub-DTO type

default <T, R> R mapFromAggregateReference(org.springframework.data.jdbc.core.mapping.AggregateReference<T, R> aggregateReference) {
    if (aggregateReference == null) {
        return null;
    }
    return aggregateReference.getId();
}

Variables

None (generic helper method).

mapFromAggregateReference helper (Kotlin)

Insert Point

Function in mapper abstract class body.

Code

skip this fragment (only for Spring Data JDBC entities with AggregateReference attributes)

When entity has AggregateReference attributes with ID sub-DTO type

fun <T, R> mapFromAggregateReference(aggregateReference: org.springframework.data.jdbc.core.mapping.AggregateReference<T, R>): R {
    return aggregateReference?.id
}

Variables

None (generic helper method).

mapToAggregateReference helper (Java)

Insert Point

Default method in mapper interface body.

Code

skip this fragment (only for Spring Data JDBC entities with AggregateReference attributes)

When entity has AggregateReference attributes with ID sub-DTO type

default <T, R> org.springframework.data.jdbc.core.mapping.AggregateReference<T, R> mapToAggregateReference(R id) {
    if (id == null) {
        return null;
    }
    return org.springframework.data.jdbc.core.mapping.AggregateReference.to(id);
}

Variables

None (generic helper method).

mapToAggregateReference helper (Kotlin)

Insert Point

Function in mapper abstract class body.

Code

skip this fragment (only for Spring Data JDBC entities with AggregateReference attributes)

When entity has AggregateReference attributes with ID sub-DTO type

fun <T, R> mapToAggregateReference(id: R): org.springframework.data.jdbc.core.mapping.AggregateReference<T, R> {
    return id?.let(org.springframework.data.jdbc.core.mapping.AggregateReference::to)
}

Variables

None (generic helper method).

Context inner record + helper methods (Java)

Insert Point

Inner record in mapper interface body + helper methods.

Code

skip this fragment (only when entity has AggregateReference attributes with non-ID sub-DTO type)

Context inner record

record {dtoName}LoadedContext({type1} {field1}, java.util.Collection<{type2}> {field2s}) {
}

Context helper methods are generated per aggregate reference attribute. Their exact form depends on whether the attribute is a collection, child of collection, etc. Each attribute generates one helper method that uses the context record fields.

Variables

Context inner data class + helper methods (Kotlin)

Insert Point

Inner data class in mapper abstract class body + helper methods.

Code

skip this fragment (only when entity has AggregateReference attributes with non-ID sub-DTO type)

Context inner data class

data class {dtoName}LoadedContext(val {field1}: {type1}?, val {field2s}: java.util.Collection<{type2}>)

Context helper methods are generated per aggregate reference attribute. Their exact form depends on whether the attribute is a collection, child of collection, etc.

Variables

Custom toDto method (Java)

Insert Point

Static method in custom mapper class body.

Code

Always generated for Custom mapper.

Standard form

Extract every direct entity property into a local first, then call the DTO constructor with the locals (and any chained accessors) in positional order.

public static {dtoClassFqn} {methodName}({entityClassFqn} {entityParamName}) {
    {dtoFieldType1} {entityParamName}{field1Cap} = {entityParamName}.get{field1Cap}();
    {dtoFieldType2} {entityParamName}{field2Cap} = {entityParamName}.get{field2Cap}();
    {dtoClassFqn} {dtoParamName} = new {dtoClassFqn}(
        {entityParamName}{field1Cap},
        {entityParamName}{field2Cap}
    );
    return {dtoParamName};
}

Local-variable rule

For direct property access (entity.getName()) extract a local. For chained access through a flat ToOne association (entity.getType().getId()) inline the expression directly into the constructor call — do not introduce a petType.id local. Example with one direct field and one flat field:

public static PetDto toPetDto(Pet pet) {
    String petName = pet.getName();
    PetDto petDto = new PetDto(petName, pet.getType().getId());
    return petDto;
}

If you would rather always extract locals (slightly more uniform, slightly more lines) that is functionally identical and acceptable — but the canonical form inlines the chained call.

Java Record DTO

The toDto side does not depend on whether the DTO is a record vs class — both are constructed via the canonical constructor. The same extract-locals-then-construct shape works unchanged. (Records change only the toEntity side, where DTO values are read via component accessors — see custom-to-entity/java.md.)

Variables

Custom toDto method (Kotlin)

Insert Point

Extension function in the mapper file (not inside a class).

Code

Always generated for Custom mapper.

fun {entityClassFqn}.{methodName}() = {dtoClassFqn}(
    {field1} = this.{field1},
    {field2} = this.{field2}
)

Variables

Custom toEntity method (Java)

Insert Point

Static method in custom mapper class body.

Code

Always generated for Custom mapper.

Standard form

Extract every DTO value into a local first, then construct the entity and apply setters. This mirrors custom-to-dto and is the canonical style. Use this form by default.

public static {entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName}) {
    {dtoFieldType1} {dtoParamName}{dtoField1Cap} = {dtoParamName}.{dtoField1Accessor};
    {dtoFieldType2} {dtoParamName}{dtoField2Cap} = {dtoParamName}.{dtoField2Accessor};
    {entityClassFqn} {entityParamName} = new {entityClassFqn}();
    {entityParamName}.set{field1Cap}({dtoParamName}{dtoField1Cap});
    {entityParamName}.set{field2Cap}({dtoParamName}{dtoField2Cap});
    return {entityParamName};
}

{dtoFieldNAccessor} — record vs class

• DTO is a regular class → use the getter: getName(), getTypeId(), …
• DTO is a Java record → use the record component accessor, no

get prefix: name(), typeId(), …

Use the bare-component form for records and the getX() form for classes. The choice is determined statically from the DTO declaration: a public record PetDto(...) always uses the component-accessor form.

Flat ToOne — JPA stub pattern

When the DTO contains flat fields from a ToOne association (e.g. only the id, or id+name extracted from Pet.type), do NOT call a repository or fetch the association. Build a stub of the association entity, set ONLY the flat fields, and assign it. JPA treats the stub as a known-id reference; loading the real row is the persistence layer's job.

public static Pet toEntity(PetDto petDto) {
    String petDtoName = petDto.getName();
    PetType petType = new PetType();
    petType.setId(petDto.getTypeId());
    Pet pet = new Pet();
    pet.setName(petDtoName);
    pet.setType(petType);
    return pet;
}

If multiple flat fields come from the same association (typeId and typeName), set them on the same stub:

PetType petType = new PetType();
petType.setId(petDto.getTypeId());
petType.setName(petDto.getTypeName());
pet.setType(petType);

Java Record + flat ToOne (combined)

public static Pet toEntity(PetDto petDto) {
    String petDtoName = petDto.name();
    PetType petType = new PetType();
    petType.setId(petDto.typeId());
    Pet pet = new Pet();
    pet.setName(petDtoName);
    pet.setType(petType);
    return pet;
}

Variables

Custom toEntity method (Kotlin)

Insert Point

Extension function in the mapper file (not inside a class).

Code

Always generated for Custom mapper.

fun {dtoClassFqn}.{methodName}() = {entityClassFqn}().also {
    it.{field1} = this.{field1}
    it.{field2} = this.{field2}
}

Variables

Custom updateWithNull method (Java)

Insert Point

Static method in custom mapper class body.

Code

skip by default (only generated when user explicitly requests full update method)

When UPDATE_WITH_NULL_VALUES requested

public static {entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName}, {entityClassFqn} {entityParamName}) {
    {entityParamName}.set{field1Cap}({dtoParamName}.get{dtoField1Cap}());
    {entityParamName}.set{field2Cap}({dtoParamName}.get{dtoField2Cap}());
    return {entityParamName};
}

Variables

Custom updateWithNull method (Kotlin)

Insert Point

Extension function in the mapper file (not inside a class).

Code

skip by default (only generated when user explicitly requests full update method)

When UPDATE_WITH_NULL_VALUES requested

fun {entityClassFqn}.{methodName}({dtoParamName}: {dtoClassFqn}) = apply {
    {field1} = {dtoParamName}.{field1}
    {field2} = {dtoParamName}.{field2}
}

Variables

MAPPER factory field (Java)

Insert Point

Field inside the mapper interface body. Only when componentModel = DEFAULT.

Code

skip this fragment (componentModel is SPRING by default)

When componentModel = DEFAULT

{className} MAPPER = org.mapstruct.factory.Mappers.getMapper({className}.class);

Variables

MAPPER factory field (Kotlin)

Insert Point

Companion object inside the mapper abstract class body. Only when componentModel = DEFAULT.

Code

skip this fragment (componentModel is SPRING by default)

When componentModel = DEFAULT

companion object {
    @kotlin.jvm.JvmStatic
    val MAPPER: {className} = org.mapstruct.factory.Mappers.getMapper({className}::class.java)
}

Variables

Flat expression method (Java)

Insert Point

Default method in mapper interface body. Added together with the corresponding @Mapping(target=..., expression="java(...)") line on toDto (see examples/_fragments/to-dto-method/java.md).

⚠ Scope — collections only

This fragment applies only to flat ToMany fields (List<Integer> petIds, Set<Integer> specialtyIds, etc.). For flat ToOne fields (Integer typeId, String typeName flattened from Pet.type) do not emit a helper method or expression = .... Instead, use MapStruct dot-notation in the regular @Mapping(source, target) annotation — see examples/_fragments/to-entity-method/java.md ("With @Mapping dot-notation for ToOne flat fields"). MapStruct generates the intermediate new PetType(); petType.setId(...); itself.

Code

skip this fragment (only for DTOs with flat **collection** attributes where subDtoType == FLAT)

Flat collection mapping method

default {collectionFqn}<{attrDtoTypeFqn}> {functionName}(java.util.Collection<{mappedEntityFqn}> {assocFieldName}) {
    return {assocFieldName}.stream().map({mappedEntityName}::get{mappedAttrNameCap}){aggregateReferenceMapper}{toCollectionExpression};
}

The parameter type is always java.util.Collection — not the concrete collection type from the entity field. The method only calls .stream(), so the concrete type is irrelevant. This also avoids mismatches when the entity getter returns a different collection type than the field declaration (e.g. field is Set<Specialty> but getter returns List<Specialty>).

Where {toCollectionExpression}:

• .toList() for List on JDK 16+
• .collect(java.util.stream.Collectors.toList()) for List on JDK < 16
• .collect(java.util.stream.Collectors.toSet()) for Set

Where {aggregateReferenceMapper}:

• .map(org.springframework.data.jdbc.core.mapping.AggregateReference::getId) if mapped attr is AggregateReference
• empty otherwise

Naming rule (CRITICAL)

The helper function name is built from the entity association field name and the flat DTO field name — not from the nested attribute name. This guarantees uniqueness even when the same association is flattened in multiple ways:

{functionName} = {assocFieldName} + "To" + capitalize({flatDtoFieldName})

For example, if Owner.pets is flattened twice into petIds and petNames, you get two distinct helpers petsToPetIds and petsToPetNames. A naming scheme based on the nested attribute (petsToId, petsToName) would NOT collide here either, but it does collide as soon as two different flat fields use the same nested attribute on different associations — so use the DTO-field-based scheme unconditionally.

Worked examples

// Vet.specialties: Set<Specialty> -> VetDto.specialtyIds: Set<Integer>
default Set<Integer> specialtiesToSpecialtyIds(Collection<Specialty> specialties) {
    return specialties.stream().map(Specialty::getId).collect(java.util.stream.Collectors.toSet());
}

// Owner.pets: List<Pet> -> OwnerDto.petIds: List<Integer> (JDK 16+)
default List<Integer> petsToPetIds(Collection<Pet> pets) {
    return pets.stream().map(Pet::getId).toList();
}

Variables

Flat expression method (Kotlin)

Insert Point

Function in mapper abstract class body. Added via postProcess.

Code

skip this fragment (only for DTOs with flat collection attributes where subDtoType == FLAT)

Flat collection mapping function

fun {functionName}({mappedFieldName}: Collection<{mappedEntityFqn}>): {collectionFqn}<{attrKotlinType}?> {
    return {mappedFieldName}.mapNotNull{ it.{mappedAttrName} }{aggregateReferenceMapper}.toMutable{collectionClassName}()
}

The parameter type is always Collection — not the concrete collection type from the entity field. The method only iterates, so the concrete type is irrelevant. This also avoids mismatches when the entity getter returns a different collection type than the field declaration.

Where {aggregateReferenceMapper}:

• .map { it.id } if mapped attr is AggregateReference
• empty otherwise

Variables

updateWithNull MapStruct method (Java)

Insert Point

Abstract method in mapper interface body.

Code

skip by default (only generated when user explicitly requests full update method)

When UPDATE_WITH_NULL_VALUES requested

@org.mapstruct.InheritConfiguration(name = "{firstUpdateMethodName}")
{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName}, @org.mapstruct.MappingTarget {entityClassFqn} {entityParamName});

Variables

updateWithNull MapStruct method (Kotlin)

Insert Point

Abstract function in mapper abstract class body.

Code

skip by default (only generated when user explicitly requests full update method)

When UPDATE_WITH_NULL_VALUES requested

@org.mapstruct.InheritConfiguration(name = "{firstUpdateMethodName}")
abstract fun {methodName}({dtoParamName}: {dtoClassFqn}, @org.mapstruct.MappingTarget {entityParamName}: {entityClassFqn}): {entityClassFqn}

Variables

@Mapper annotation (Java)

Insert Point

Annotation on the mapper interface created from skeleton.

Code

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = org.mapstruct.MappingConstants.ComponentModel.SPRING)

SPRING component model (MappingConstants available)

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = org.mapstruct.MappingConstants.ComponentModel.SPRING)

SPRING component model (MappingConstants NOT available, older MapStruct)

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = "spring")

CDI component model

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = "cdi")

DEFAULT component model (no Spring, no CDI)

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE)

Variables

Note — recommended default

Prefer the SPRING (modern) variant (MappingConstants.ComponentModel.SPRING) whenever Spring is on the classpath. The DEFAULT and CDI variants are listed for completeness but are rarely needed in practice.

@Mapper annotation (Kotlin)

Insert Point

Annotation on the mapper abstract class created from skeleton.

Code

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = org.mapstruct.MappingConstants.ComponentModel.SPRING)

SPRING component model (MappingConstants available)

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = org.mapstruct.MappingConstants.ComponentModel.SPRING)

SPRING component model (MappingConstants NOT available)

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = "spring")

CDI component model

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = "cdi")

DEFAULT component model

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE)

Variables

Parent interface extends clause (Java)

Insert Point

Modifies the interface declaration to add extends clause.

Code

skip this fragment (no parent interface by default)

When parent interface selected

public interface {className} extends {parentFqn}<{dtoClassFqn}, {entityClassFqn}> {

Variables

Parent interface supertypes clause (Kotlin)

Insert Point

Modifies the abstract class declaration to add supertype.

Code

skip this fragment (no parent interface by default)

When parent interface selected

abstract class {className} : {parentFqn}<{dtoClassFqn}, {entityClassFqn}>() {

Variables

partialUpdate MapStruct method (Java)

Insert Point

Abstract method in mapper interface body.

Code

skip by default (only generated when user explicitly requests partial update method)

When PARTIAL_UPDATE requested

Always one method, controlled by ONE @BeanMapping annotation. The nullValuePropertyMappingStrategy enum value is selected by the user (SET_TO_NULL / IGNORE / SET_TO_DEFAULT). Do not emit @InheritConfiguration — the inherited mappings are not needed for the canonical Pet/Owner-style DTOs.

@org.mapstruct.BeanMapping(nullValuePropertyMappingStrategy = org.mapstruct.NullValuePropertyMappingStrategy.{strategyEnum})
{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName}, @org.mapstruct.MappingTarget {entityClassFqn} {entityParamName});

Worked examples (one per strategy — only one is emitted)

// SET_TO_NULL  (the most common — null in DTO clears the field)
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_NULL)
Owner partialUpdate(OwnerDto ownerDto, @MappingTarget Owner owner);

// IGNORE  (null in DTO keeps the existing value)
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
Owner partialUpdate(OwnerDto ownerDto, @MappingTarget Owner owner);

// SET_TO_DEFAULT  (null in DTO resets to type default — 0 for int, "" for String, etc.)
@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_DEFAULT)
Owner partialUpdate(OwnerDto ownerDto, @MappingTarget Owner owner);

Variables

partialUpdate MapStruct method (Kotlin)

Insert Point

Abstract function in mapper abstract class body.

Code

skip by default (only generated when user explicitly requests partial update method)

When PARTIAL_UPDATE requested

@org.mapstruct.BeanMapping(nullValuePropertyMappingStrategy = org.mapstruct.NullValuePropertyMappingStrategy.IGNORE)
@org.mapstruct.InheritConfiguration(name = "{toEntityMethodName}")
abstract fun {methodName}({dtoParamName}: {dtoClassFqn}, @org.mapstruct.MappingTarget {entityParamName}: {entityClassFqn}): {entityClassFqn}

Variables

toDto MapStruct method (Java)

Insert Point

Abstract method in mapper interface body, after toEntity method.

Code

Always generated by default.

Without any annotations (all fields map directly) — preferred when applicable

{dtoClassFqn} {methodName}({entityClassFqn} {entityParamName});

With @Mapping annotations (default whenever any field needs remapping)

For each entity-field/DTO-field pair that requires a non-default mapping, emit a separate @Mapping line. Use this even when toEntity already has the inverse — see references/mapping-annotations.md for why.

@org.mapstruct.Mapping(source = "{entityFieldName}", target = "{dtoFieldName}")
{dtoClassFqn} {methodName}({entityClassFqn} {entityParamName});

With @Mapping(expression) for flat collection fields

Used together with the helper from examples/_fragments/flat-expression/java.md. For each flat collection DTO field, add one of these @Mapping lines on toDto. The helper method itself is added to the same mapper interface as a default method.

@org.mapstruct.Mapping(target = "{flatDtoFieldName}", expression = "java({functionName}({entityParamName}.get{AssocFieldCap}()))")
{dtoClassFqn} {methodName}({entityClassFqn} {entityParamName});

Where:

• {flatDtoFieldName} — the flat collection field on the DTO (e.g. specialtyIds, petIds)
• {functionName} — the helper method name from the flat-expression fragment (e.g. specialtiesToSpecialtyIds, petsToPetIds)
• {AssocFieldCap} — capitalized association field name on the entity (e.g. Specialties, Pets)

With @Context parameter (aggregate references with context)

{dtoClassFqn} {methodName}({entityClassFqn} {entityParamName}, @org.mapstruct.Context {dtoName}LoadedContext context);

With @InheritInverseConfiguration — preferred when toEntity has 2+ flat ToOne mappings

When toEntity carries only invertible @Mapping(source, target) pairs (the dot-notation flat-ToOne case from to-entity-method/java.md), emit @InheritInverseConfiguration on toDto instead of duplicating the annotations. Use this form when:

• toEntity has at least one @Mapping and ALL of its mappings are plain

(source, target) pairs that MapStruct can invert losslessly (no expression, constant, defaultValue, ignore = true, qualifiedBy, or condition).

For the single-@Mapping case the duplication is so cheap that either form is fine; default to inheritance only when there are 2+ mappings, which is where the benefit becomes visible.

@org.mapstruct.InheritInverseConfiguration(name = "{toEntityMethodName}")
{dtoClassFqn} {methodName}({entityClassFqn} {entityParamName});

Worked example (paired with the Pet toEntity(PetDto) from to-entity-method/java.md):

@InheritInverseConfiguration(name = "toEntity")
PetDto toPetDto(Pet pet);

If toEntity mixes invertible and non-invertible mappings (expression, ignore = true, etc.), do not use inheritance — fall back to the explicit @Mapping form documented above. See references/mapping-annotations.md for the failure modes.

Variables

toDto MapStruct method (Kotlin)

Insert Point

Abstract function in mapper abstract class body, after toEntity function.

Code

Always generated by default.

With @InheritInverseConfiguration (when toEntity was created first and has mappings)

@org.mapstruct.InheritInverseConfiguration(name = "{toEntityMethodName}")
abstract fun {methodName}({entityParamName}: {entityClassFqn}): {dtoClassFqn}

With @Mappings annotations (when toEntity was not created or has no mappings)

@org.mapstruct.Mappings(
    org.mapstruct.Mapping(source = "{entityFieldName}", target = "{dtoFieldName}")
)
abstract fun {methodName}({entityParamName}: {entityClassFqn}): {dtoClassFqn}

With @Context parameter (aggregate references with context)

abstract fun {methodName}({entityParamName}: {entityClassFqn}, @org.mapstruct.Context context: {dtoName}LoadedContext): {dtoClassFqn}

Without any annotations (all fields map directly)

abstract fun {methodName}({entityParamName}: {entityClassFqn}): {dtoClassFqn}

Variables

toEntity MapStruct method (Java)

Insert Point

Abstract method in mapper interface body.

Code

Always generated by default.

With @Mapping annotations (first method, or no inverse available)

@org.mapstruct.Mapping(source = "{dtoFieldName}", target = "{entityFieldName}")
{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName});

With @Mapping dot-notation for ToOne flat fields — preferred for ToOne FLAT

When DTO has one or more flat fields from a single ToOne association (e.g. PetDto with typeId / typeName flattened from Pet.type), emit one @Mapping per flat field using dot-notation in target. No Java-expression, no helper method. MapStruct itself synthesizes the intermediate new PetType() and the field setters.

@org.mapstruct.Mapping(source = "{flatDtoFieldName}", target = "{assocFieldName}.{nestedFieldName}")
@org.mapstruct.Mapping(source = "{flatDtoFieldName2}", target = "{assocFieldName}.{nestedFieldName2}")
{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName});

Worked example — PetDto(typeId, typeName) flattens Pet.type (which points at PetType):

@Mapping(source = "typeName", target = "type.name")
@Mapping(source = "typeId", target = "type.id")
Pet toEntity(PetDto petDto);

Note: the order of @Mapping annotations does not matter functionally. Any consistent ordering is acceptable.

With @InheritInverseConfiguration (when toDto was created first)

@org.mapstruct.InheritInverseConfiguration(name = "{inverseMethodName}")
{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName});

Without any annotations (all fields map directly, no remapping needed)

{entityClassFqn} {methodName}({dtoClassFqn} {dtoParamName});

Variables

toEntity MapStruct method (Kotlin)

Insert Point

Abstract function in mapper abstract class body.

Code

Always generated by default.

With @Mappings annotations (first method, or no inverse available)

@org.mapstruct.Mappings(
    org.mapstruct.Mapping(source = "{dtoFieldName}", target = "{entityFieldName}")
)
abstract fun {methodName}({dtoParamName}: {dtoClassFqn}): {entityClassFqn}

With @InheritInverseConfiguration (when toDto was created first)

@org.mapstruct.InheritInverseConfiguration(name = "{inverseMethodName}")
abstract fun {methodName}({dtoParamName}: {dtoClassFqn}): {entityClassFqn}

Without any annotations (all fields map directly)

abstract fun {methodName}({dtoParamName}: {dtoClassFqn}): {entityClassFqn}

Variables

@Mapper(uses = ...) attribute (Java)

Insert Point

Modifies existing @Mapper annotation to add uses attribute.

Code

skip this fragment (no sub-mappers by default)

When sub-mappers exist for association DTOs

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = ..., uses = {SubMapper1.class, SubMapper2.class})

Variables

@Mapper(uses = ...) attribute (Kotlin)

Insert Point

Modifies existing @Mapper annotation to add uses attribute.

Code

skip this fragment (no sub-mappers by default)

When sub-mappers exist for association DTOs

@org.mapstruct.Mapper(unmappedTargetPolicy = org.mapstruct.ReportingPolicy.IGNORE, componentModel = ..., uses = [SubMapper1::class, SubMapper2::class])

Variables

Custom mapper class (Java)

Code

package {packageName};

public class {className} {
}

Variables

Custom mapper file (Kotlin)

Code

package {packageName}

Variables

MapStruct mapper interface (Java)

Code

package {packageName};

public interface {className} {
}

Variables

MapStruct mapper abstract class (Kotlin)

Code

package {packageName}

abstract class {className} {
}

Variables

Custom Mapper -- Java

Skeleton

Read examples/_skeletons/custom-java.md. Write the file to src/main/java/{packagePath}/{className}.java.

Generation order

1. Create file from skeleton (plain class) 2. Add toDto static method from examples/_fragments/custom-to-dto/java.md

• For each DTO field: extract value from entity via getter into a local variable
• Create DTO via constructor call with all extracted variables
• Return the DTO

3. Add toEntity static method from examples/_fragments/custom-to-entity/java.md

• For each direct DTO field: extract value into a local using the DTO accessor (getX() for class DTOs, x() for record DTOs)
• Create new entity instance
• Call entity setters with the locals
• For flat ToOne fields: build a JPA stub of the association entity (new PetType(); petType.setId(...);) and pass it to the parent setter
• Return the entity

4. If UPDATE_WITH_NULL_VALUES requested: add from examples/_fragments/custom-update-with-null/java.md

• Takes both DTO and entity as parameters
• Calls entity setters with DTO getter values
• Returns the entity

Method body construction

toDto method:

• Init expressions: {DtoFieldType} {entityParam}{FieldCap} = {entityParam}.get{FieldCap}(); for each DTO field
• Result: new {DtoClassFqn}({entityParam}{Field1Cap}, {entityParam}{Field2Cap}, ...)

toEntity method:

• For each direct DTO field: {DtoFieldType} {dtoParam}{DtoFieldCap} = {dtoParam}.{accessor};
• {accessor} = get{DtoFieldCap}() for class DTO, {dtoFieldName}() for record DTO
• Init: {EntityClassFqn} {entityParam} = new {EntityClassFqn}();
• For each direct field: {entityParam}.set{FieldCap}({dtoParam}{DtoFieldCap});
• For each flat ToOne assoc with fields {f1, f2, ...} from {Assoc}:
• {Assoc} {assocVar} = new {Assoc}();
• {assocVar}.set{F1Cap}({dtoParam}.{f1Accessor});
• {assocVar}.set{F2Cap}({dtoParam}.{f2Accessor});
• {entityParam}.set{AssocCap}({assocVar});
• Return: {entityParam}

updateWithNull method:

• Body: same setter pattern as toEntity, but entity is a parameter (not new)
• Return: {entityParam}

Method naming

Same defaults as MapStruct variant (see references/mapstruct-java.md).

Custom Mapper -- Kotlin

Skeleton

Read examples/_skeletons/custom-kotlin.md. Write the file to src/main/kotlin/{packagePath}/{className}.kt.

Note: Kotlin custom mapper is a file with extension functions, not a class.

Generation order

1. Create file from skeleton (just package declaration) 2. Add toDto extension function from examples/_fragments/custom-to-dto/kotlin.md

• Extension on entity class
• Returns DTO via named constructor arguments: DtoFqn(field1 = this.field1, field2 = this.field2)

3. Add toEntity extension function from examples/_fragments/custom-to-entity/kotlin.md

• Extension on DTO class
• Returns EntityFqn().also { it.field1 = this.field1; ... }

4. If UPDATE_WITH_NULL_VALUES requested: add from examples/_fragments/custom-update-with-null/kotlin.md

• Extension on entity class with DTO parameter
• Uses apply { field1 = dtoParam.field1; ... }

Kotlin-specific patterns

• toDto: fun EntityFqn.toOrderDto() = DtoFqn(field1 = this.field1, field2 = this.field2)
• toEntity: fun DtoFqn.toEntity() = EntityFqn().also { it.field1 = this.field1; it.field2 = this.field2 }
• updateWithNull: fun EntityFqn.updateWithNull(orderDto: DtoFqn) = apply { field1 = orderDto.field1; ... }

Method naming

Same defaults as MapStruct variant (see references/mapstruct-java.md).

@Mapping Annotation Rules

Determining field mappings

Compare entity fields (from get_entity_details) with DTO fields (from list_class_members).

For each DTO field, determine the mapping type:

Direct match

Same name and compatible type in both entity and DTO. No @Mapping annotation needed.

Different name

DTO field name differs from entity field name.

@org.mapstruct.Mapping(source = "{sourceField}", target = "{targetField}")

SubDtoType = ID (association mapped to ID only)

DTO has an ID field for an entity association (e.g. Long customerId for Customer customer).

@org.mapstruct.Mapping(source = "{dtoIdField}", target = "{entityAssocField}.id")

For toDto (reverse): @Mapping(source = "{entityAssocField}.id", target = "{dtoIdField}")

SubDtoType = FLAT (flattened association fields)

DTO has individual fields extracted from a nested entity (e.g. String customerName from customer.name).

• For non-collection (ToOne): dot-notation in BOTH directions. Note that on toEntity the dot is on the target side, on toDto it's on the source side. MapStruct synthesizes the intermediate new {Assoc}() itself.
• toEntity: @Mapping(source = "{dtoFlatField}", target = "{entityAssocField}.{nestedField}")
• toDto: @Mapping(source = "{entityAssocField}.{nestedField}", target = "{dtoFlatField}") — or use @InheritInverseConfiguration (see below) when there are 2+ flat mappings.
• For collection (ToMany): uses expression with helper method (see flat-expression fragments). Dot-notation does not work for collections.

SubDtoType = NEW_CLASS / NEW_NESTED_CLASS / EXIST_CLASS

DTO uses another DTO for the association. MapStruct handles this implicitly by generating private nested-mapping methods inside the same mapper interface — no uses= and no separate sub-mapper file are needed by default. Do not emit uses for these cases — mapping will be handled implicitly. Add uses only when a real sibling mapper must be reused or a @Named qualifier is required.

@InheritInverseConfiguration — opt-in only, NOT the default

When toEntity is generated first (always true by default), it is technically possible for toDto to use:

@org.mapstruct.InheritInverseConfiguration(name = "toEntity")

This inherits all @Mapping annotations in reverse, avoiding duplication.

However, this is NOT the default in this skill. Reasons to prefer duplicated @Mapping(source, target) pairs on toDto:

1. Robust under refactoring. @InheritInverseConfiguration silently breaks (or starts producing wrong code) the moment toEntity gains any non-invertible mapping: ignore = true, expression = "...", constant = "...", defaultValue, qualifiedBy, dateFormat, numberFormat. None of these have a meaningful inverse. 2. Locally readable. A reviewer reading toDto sees its mappings inline; they do not have to scroll up to toEntity and mentally invert each line. 3. One fewer import (org.mapstruct.InheritInverseConfiguration). 4. Order-independent. If a future edit reorders steps 5 and 6 of the generation order, the duplicated @Mapping form keeps working; @InheritInverseConfiguration(name = "toEntity") would resolve to a forward reference.

Exception — multi-flat-ToOne case. When toEntity carries 2+ plain @Mapping(source, target) annotations (typically the dot-notation flat-ToOne case from to-entity-method/java.md) and ALL of them are losslessly invertible, prefer @InheritInverseConfiguration(name = "toEntity") on toDto. Worked example:

@Mapping(source = "typeName", target = "type.name")
@Mapping(source = "typeId", target = "type.id")
Pet toEntity(PetDto petDto);

@InheritInverseConfiguration(name = "toEntity")
PetDto toPetDto(Pet pet);

For the single-@Mapping case the duplication is so cheap that either form is fine — default to duplication for refactor-safety. For 2+ mappings, default to inheritance to reduce duplication.

partialUpdate has its OWN @BeanMapping — no @InheritConfiguration

The partialUpdate method is generated independently and carries exactly ONE annotation:

@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.{strategy})
{Entity} partialUpdate({Dto} dto, @MappingTarget {Entity} entity);

{strategy} is one of SET_TO_NULL (default) / IGNORE / SET_TO_DEFAULT, picked by the user. Do not add @InheritConfiguration(name = "toEntity") — chasing inherited mappings here only creates surprising failures when toEntity later acquires non-invertible mappings.

Kotlin wrapping rule

In Kotlin, multiple @Mapping annotations must be wrapped:

@org.mapstruct.Mappings(value = [
    org.mapstruct.Mapping(source = "field1", target = "field2"),
    org.mapstruct.Mapping(source = "field3", target = "field4")
])

Single @Mapping can be used directly without wrapping.

MapStruct Mapper -- Java

Skeleton

Read examples/_skeletons/mapstruct-java.md. Write the file to src/main/java/{packagePath}/{className}.java.

Generation order

1. Create file from skeleton 2. Add @Mapper annotation from examples/_fragments/mapper-annotation/java.md

• Determine componentModel: any spring-boot-starter* or spring-context in presentDeps → SPRING; otherwise → DEFAULT.
• CDI is not auto-detected. Use the CDI variant only when the user explicitly asked for componentModel = "cdi".
• For SPRING, use MappingConstants.ComponentModel.SPRING form (modern MapStruct).

3. If componentModel = DEFAULT: add MAPPER factory field from examples/_fragments/factory-field/java.md 4. If user selected parent interface: modify declaration from examples/_fragments/parent-interface/java.md 5. Add toEntity method from examples/_fragments/to-entity-method/java.md

• For each DTO field that maps to a different entity field name, add @Mapping(source, target) annotation
• If DTO field has SubDtoType = ID (association ID only), add @Mapping(source = "dtoField", target = "entityAssoc.id")
• If DTO field has SubDtoType = FLAT for a ToOne association (single object, e.g. typeId/typeName from Pet.type):

emit one @Mapping(source = "flatDtoField", target = "assoc.nestedField") per flat field — dot-notation, no helper method, no Java-expression. MapStruct synthesizes the intermediate new PetType() and the setters itself.

• If DTO field has SubDtoType = FLAT for a ToMany association (collection), use the helper-method form from examples/_fragments/flat-expression/java.md (collections cannot use dot-notation).

6. Add toDto method from examples/_fragments/to-dto-method/java.md

• Single `@Mapping` on toEntity → emit the symmetric @Mapping(source, target) on toDto. Duplication is one cheap line and refactor-safe.
• Two or more invertible `@Mapping`s on toEntity (the typical multi-flat-ToOne case) → emit @InheritInverseConfiguration(name = "{toEntityMethodName}") on toDto. This removes the duplication that grows linearly with flat fields.
• Mixed invertible / non-invertible mappings on toEntity (any expression, constant, defaultValue, ignore = true, qualifiedBy, condition) → fall back to explicit duplicated @Mappings on toDto. @InheritInverseConfiguration silently breaks in this case.
• If entity has AggregateReference attrs with non-ID sub-DTO, add @Context parameter

7. If PARTIAL_UPDATE requested: add from examples/_fragments/partial-update-method/java.md

• Pass {strategyEnum} from the user's partialUpdateNullStrategy answer (default SET_TO_NULL).
• Always emit ONE method with one @BeanMapping(nullValuePropertyMappingStrategy = ...) — never two methods, never @InheritConfiguration.

8. If UPDATE_WITH_NULL_VALUES requested: add from examples/_fragments/full-update-method/java.md 9. Check entity associations for @AfterMapping need:

• For each non-owner OneToOne or OneToMany with mappedBy where DTO uses sub-DTO (not ID, not FLAT):
• Add method from examples/_fragments/after-mapping/java.md

10. If entity has AggregateReference attrs with ID sub-DTO:

• Add mapToAggregateReference from examples/_fragments/aggregate-ref-to/java.md
• Add mapFromAggregateReference from examples/_fragments/aggregate-ref-from/java.md

11. If DTO has flat collection attributes (SubDtoType = FLAT + collection):

• Add flat expression method from examples/_fragments/flat-expression/java.md
• The toDto method gets @Mapping(target = "flatField", expression = "java(functionName(entity.getAssoc()))") instead of regular mapping
• Known limitation — one-way only. The flat collection helper is

generated only in the entity → DTO direction. The reverse (flatField → entityAssoc) is not generated, and unmappedTargetPolicy = IGNORE will silently leave the collection empty on toEntity. Loading entities by id is the responsibility of the calling service via the JPA repository — do not inject a repository or EntityManager into the mapper. If the user needs the reverse, point them at the service layer instead of trying to generate it. 12. If entity has AggregateReference attrs with non-ID sub-DTO:

• Add context record + helper methods from examples/_fragments/context-class/java.md

13. `uses = {...}` is rarely needed. MapStruct generates private nested-mapping methods implicitly when both the source and target sub-types are visible to the same mapper interface. Do not emit uses for NEW_CLASS / NEW_NESTED_CLASS sub-DTOs — mapping will be handled implicitly.

• Default: do not add `uses`. Do not call list_entity_mappers and do not generate a separate sub-mapper file for the association.
• Exceptions that DO warrant uses = {SomeMapper.class}:
• the user explicitly asks for an existing sibling mapper to be reused (e.g. complex per-association logic already lives there);
• the association mapping needs a @Named qualifier from another mapper;
• circular dependencies between mappers that you cannot resolve via implicit generation.
• When you DO need it, use examples/_fragments/uses-attribute/java.md.

@Mapping annotation rules

For each DTO field, determine mapping type based on entity-DTO field comparison:

• Direct match (same name and type): no @Mapping needed
• Different name: @Mapping(source = "dtoFieldName", target = "entityFieldName")
• SubDtoType = ID: @Mapping(source = "dtoField", target = "entityAssoc.id")
• SubDtoType = FLAT: @Mapping(source = "dtoField", target = "assoc.nestedField") or expression for collections
• SubDtoType = NEW_CLASS/NEW_NESTED_CLASS/EXIST_CLASS: MapStruct handles via sub-mapper in uses

Method naming

Default patterns:

• toEntity: "toEntity"
• toDto: "to{DtoShortName}" (e.g. toOrderDto)
• partialUpdate: "partialUpdate"
• updateWithNull: "updateWithNull"
• Collection methods: same as single (LIKE_SINGLE strategy)

MapStruct Mapper -- Kotlin

Skeleton

Read examples/_skeletons/mapstruct-kotlin.md. Write the file to src/main/kotlin/{packagePath}/{className}.kt.

Generation order

1. Create file from skeleton 2. Add @Mapper annotation from examples/_fragments/mapper-annotation/kotlin.md

• Determine componentModel: any spring-boot-starter* or spring-context in presentDeps → SPRING; otherwise → DEFAULT.
• CDI is not auto-detected. Use the CDI variant only when the user explicitly asked for componentModel = "cdi".

3. If componentModel = DEFAULT: add MAPPER companion object from examples/_fragments/factory-field/kotlin.md 4. If user selected parent interface: modify declaration from examples/_fragments/parent-interface/kotlin.md 5. Add toEntity method from examples/_fragments/to-entity-method/kotlin.md

• Multiple @Mapping annotations MUST be wrapped in @Mappings(value = [...])
• For each DTO field that maps to a different entity field, add Mapping(source, target) inside @Mappings

6. Add toDto method from examples/_fragments/to-dto-method/kotlin.md

• If toEntity was created and has @Mapping annotations, use @InheritInverseConfiguration(name = "toEntity")
• Otherwise add individual @Mapping/@Mappings annotations
• If entity has AggregateReference attrs with non-ID sub-DTO, add @Context parameter

7. If PARTIAL_UPDATE requested: add from examples/_fragments/partial-update-method/kotlin.md 8. If UPDATE_WITH_NULL_VALUES requested: add from examples/_fragments/full-update-method/kotlin.md 9. Check entity associations for @AfterMapping need:

• For each non-owner OneToOne or OneToMany with mappedBy where DTO uses sub-DTO:
• Add method from examples/_fragments/after-mapping/kotlin.md

10. If entity has AggregateReference attrs with ID sub-DTO:

• Add mapToAggregateReference from examples/_fragments/aggregate-ref-to/kotlin.md
• Add mapFromAggregateReference from examples/_fragments/aggregate-ref-from/kotlin.md

11. If DTO has flat collection attributes (SubDtoType = FLAT + collection):

• Add flat expression function from examples/_fragments/flat-expression/kotlin.md

12. If entity has AggregateReference attrs with non-ID sub-DTO:

• Add context data class + helper methods from examples/_fragments/context-class/kotlin.md

13. Add sub-mapper references to @Mapper(uses = ...) from examples/_fragments/uses-attribute/kotlin.md

• Lazy fetch: for each association entity used by the DTO via a sub-DTO type (NEW_CLASS / NEW_NESTED_CLASS / EXIST_CLASS), call list_entity_mappers(associationEntityFqn) at this step — not in Step 1 of SKILL.md. The call needs the association entity FQN, which is only known after entityDetails is fetched in Step 2.
• Add found mapper FQNs to the uses attribute. Skip associations with no existing mapper. If no association needs a sub-mapper, skip the uses attribute entirely.

Kotlin-specific differences from Java

• Mapper is abstract class, not interface
• Methods are abstract fun, not interface abstract methods
• Helper methods (afterMapping, aggregateRef) are regular functions, not default methods
• Multiple @Mapping annotations MUST be wrapped: @Mappings(value = [Mapping(...), Mapping(...)])
• MAPPER factory uses companion object with @JvmStatic
• Parent interface uses : ParentFqn<Dto, Entity>() (with ())
• Custom extension functions use this.field access
• @MappingTarget goes before param name: @MappingTarget entity: EntityFqn

@Mapping annotation rules

Same as Java (see references/mapstruct-java.md), but annotations wrapped in @Mappings(value = [...]) when multiple.

Method naming

Same as Java (see references/mapstruct-java.md).

Method Naming Conventions

Default patterns

${DTO_NAME} is replaced with the DTO short class name (e.g. OrderDto).

Parameter naming

Collection method naming strategy

Default: LIKE_SINGLE (same name as single-item method).

Other strategies (configurable, but rarely changed):

• PLURALIZE: toEntities, toOrderDtos
• COLLECTION_TYPE: toEntityList, toOrderDtoList

Custom extension function naming (Kotlin Custom mapper)

• toDto: fun EntityFqn.toOrderDto() -- extension on entity
• toEntity: fun DtoFqn.toEntity() -- extension on DTO
• updateWithNull: fun EntityFqn.updateWithNull(orderDto: DtoFqn) -- extension on entity with DTO param