@Xml(format) Annotation

The @Xml(format) annotation tweaks how a POJO is rendered in XML. Its value is one of the enum constants defined in XmlFormat, and it can be applied to both bean classes and individual bean properties.

At the class level, a format changes the default treatment of every property on the bean (for example, rendering all properties as attributes). At the property level, a format changes the treatment of that one property (for example, promoting a single property to an XML attribute or flattening a collection into the parent element). Property-level formats override class-level defaults, so the two levels can be combined.

The XmlFormat values

The table below summarizes every XmlFormat value and where each is documented in detail. Because the formats fall into a handful of related families, the worked examples are organized by family across the pages listed in the last column.

Value	Applies to	Summary	Documented in
DEFAULT	Class & property	Normal formatting. On a class it behaves like FREEFORM; on a property it behaves like ELEMENT. This is the behavior when no @Xml(format) is specified.	—
ATTR	Property	Render a property as an XML attribute instead of a child element.	Attribute Formats
ATTRS	Class & property	On a class, render all properties as attributes; on a Map property, render arbitrary attributes from the map entries.	Attribute Formats
ELEMENT	Property	Render a property as a child element, overriding an ATTRS default set on the class.	Attribute Formats
COLLAPSED	Property	Serialize the members of an array/collection directly inside the bean element, without an enclosing wrapper.	Collapsed Format
FREEFORM	Property	Serialize free-form child elements. All other properties on the bean must be attributes.	Element & Mixed Formats
MIXED	Property	Like FREEFORM, but element names are stripped from primitive values to produce mixed content.	Element & Mixed Formats
MIXED_PWS	Property	Same as MIXED, but whitespace in text nodes is preserved during parsing.	Element & Mixed Formats
TEXT	Property	Render a single value as the text content of the element.	Text Formats
TEXT_PWS	Property	Same as TEXT, but whitespace in the text node is preserved during parsing.	Text Formats
XMLTEXT	Property	Like TEXT, but the string is treated as fully-formed XML and serialized as-is.	Text Formats
VOID	Class	Marks an element that never contains content (e.g. HTML <br/>). Affects how empty elements are collapsed by the HTML serializer.	—

In this section

The remaining @Xml(format) pages document each family with worked before/after examples:

• Attribute Formats — ATTR, ATTRS, and ELEMENT for moving values between attributes and elements.
• Collapsed Format — COLLAPSED for flattening arrays and collections into the bean element.
• Element & Mixed Formats — FREEFORM, MIXED, and MIXED_PWS for free-form and mixed content.
• Text Formats — TEXT, TEXT_PWS, and XMLTEXT for text-node and raw-XML content.
• Whitespace Handling — how empty strings and whitespace are preserved (or lost) across the MIXED and TEXT families.