Data Formats
XML Comments: Syntax, Rules, and Examples
An XML comment starts with <!-- and ends with -->. Comments can document a file, but they are markup rather than character data and have stricter syntax than comments in many programming languages.
Published
XML comment syntax
Comments may appear outside other markup and, in permitted positions, inside the document type declaration. They are not part of an element's character data.
<!-- Explain why this value is fixed -->
<timeout>30</timeout>A comment cannot contain --
XML 1.0 forbids the double-hyphen sequence inside a comment. Its grammar also rejects a comment that closes with three hyphens.
Valid: <!-- retry policy: fixed -->
Invalid: <!-- retry -- policy -->
Invalid: <!-- retry policy --->Where comments can appear
- Before or after the document element.
- Between child elements inside a document.
- Not inside a start tag, end tag, attribute value or another comment.
- Not before the XML declaration, which must be first when present.
What happens to comments during conversion
An XML processor may expose comments to an application, but applications are not required to keep them. Application-friendly XML-to-JSON mappings commonly omit comments; a fidelity-oriented mapping may preserve them explicitly.
Do not store required business data only in a comment if the downstream JSON must retain it.
Try the example
Convert XML that contains a comment
Compare document markup with the application-friendly JSON mapping.
<config><!-- seconds --><timeout>30</timeout></config>Expected result: Smart mapping keeps timeout and omits the comment from the application data.
Inspect parser behavior
Convert XML that contains comments
Load a commented XML document and see which mapping profiles preserve or omit comment information.
Commenting out XML markup
A comment can temporarily surround markup only when the enclosed text contains no comment of its own and no -- sequence. XML has no nested-comment syntax.