name	xml
description	XML/MyBatis mapper rules: namespace integrity, mapper-interface sync, well-formedness, embedded-SQL alignment.

Shared examples and formatting reference: references/EXAMPLE.md.
Keep new guidance, snippets, and edits aligned with that file.

Scope

Use this rule when:

editing .xml files: Maven POM, Spring config, MyBatis mapper XML, log4j/logback config
editing embedded SQL inside MyBatis mapper XML (<select>, <insert>, <update>, <delete>)
changing element attributes, namespace declarations, or schema references
adding or removing nodes that callers or frameworks depend on

When XML contains embedded SQL, apply the sql skill in addition to this one.

Core Rules

Preserve existing namespace declarations and xsi:schemaLocation unless explicitly changing them.
Keep element indentation consistent (2 spaces preferred; match the file if already established).
Do not self-close elements whose content model expects children.
Use attributes for identity or metadata; use child elements for content or structured data.
Validate that added elements match the expected schema or DTD.
Do not break CDATA sections unnecessarily; preserve literal content inside <![CDATA[...]]>.

MyBatis Mapper Contract

Treat the mapper interface and XML as one contract.
Keep namespace, id, parameterType, and resultType / resultMap synchronized with the mapper interface.
Preserve column aliases and resultMap behavior when callers depend on them.
Review <if>, <choose>, and <foreach> carefully — null, empty, and optional fragments included.
Do not create <sql> snippets unless explicitly requested.

For SQL inside mapper XML — keyword casing, JOIN/WHERE single-line rules, alias conventions, performance rules, and dynamic-SQL guidance — follow the sql skill. This file does not duplicate those rules.

Layering Boundary

MyBatis mapper XML is for data retrieval and persistence only.
Business logic and utility processing belong in Java (see java skill).
Do not implement format conversion, string manipulation, conditional branching, calculation, or code mapping inside mapper XML queries.

Formatting

Never use vertical alignment. Do not pad spaces to align attribute values or element content into columns.
Compact, standard style — no unnecessary whitespace padding.
One attribute per line when an element has more than two attributes.
Closing tag on its own line when the element contains block-level children.
Exactly one space on both sides of binary operators inside embedded SQL and OGNL/test expressions.
Do not use tabs, repeated spaces, or column alignment for visual formatting in any embedded expression.

Validation Focus

namespace correctness after changes
MyBatis mapper/XML contract alignment (method name ↔ statement id, parameter type, result shape)
embedded SQL parameter binding and result column stability
dynamic SQL branch behavior (<if>, <choose>, <foreach>)
well-formedness: unclosed tags, mismatched nesting, illegal characters
schema or DTD validation when a validator is available

Scope

Use this rule when:

editing .xml files: Maven POM, Spring config, MyBatis mapper XML, log4j/logback config

editing embedded SQL inside MyBatis mapper XML (<select>, <insert>, <update>, <delete>)

changing element attributes, namespace declarations, or schema references

adding or removing nodes that callers or frameworks depend on

When XML contains embedded SQL, apply the sql skill in addition to this one.

Core Rules

Preserve existing namespace declarations and xsi:schemaLocation unless explicitly changing them.

Keep element indentation consistent (2 spaces preferred; match the file if already established).

Do not self-close elements whose content model expects children.

Use attributes for identity or metadata; use child elements for content or structured data.

Validate that added elements match the expected schema or DTD.

Do not break CDATA sections unnecessarily; preserve literal content inside <![CDATA[...]]>.

MyBatis Mapper Contract

Treat the mapper interface and XML as one contract.

Keep namespace, id, parameterType, and resultType / resultMap synchronized with the mapper interface.

Preserve column aliases and resultMap behavior when callers depend on them.

Review <if>, <choose>, and <foreach> carefully — null, empty, and optional fragments included.

Do not create <sql> snippets unless explicitly requested.

Formatting

Never use vertical alignment. Do not pad spaces to align attribute values or element content into columns.

Compact, standard style — no unnecessary whitespace padding.

One attribute per line when an element has more than two attributes.

Closing tag on its own line when the element contains block-level children.

Exactly one space on both sides of binary operators inside embedded SQL and OGNL/test expressions.

Do not use tabs, repeated spaces, or column alignment for visual formatting in any embedded expression.

Validation Focus

namespace correctness after changes

MyBatis mapper/XML contract alignment (method name ↔ statement id, parameter type, result shape)

embedded SQL parameter binding and result column stability

dynamic SQL branch behavior (<if>, <choose>, <foreach>)

well-formedness: unclosed tags, mismatched nesting, illegal characters

schema or DTD validation when a validator is available