Todos os artigos

XML Entities: escapar caracteres em documentos XML

Assim como o HTML, o XML usa colchetes angulares e o "e comercial" para marcar tags, então esses caracteres não podem aparecer crus dentro do texto — o documento deixa de ser XML válido e o parser para com erro em vez de simplesmente ignorar o problema.

As cinco entidades obrigatórias

Diferente do HTML, que define centenas de entidades nomeadas, a especificação XML exige apenas cinco:

  • &lt; — no lugar de <
  • &gt; — no lugar de >
  • &amp; — no lugar de &
  • &apos; — no lugar da aspa simples '
  • &quot; — no lugar da aspa dupla "

As aspas só precisam ser escapadas dentro de valores de atributo, enquanto < e & precisam ser escapados em qualquer conteúdo de texto.

Onde isso aparece na prática

A Nota Fiscal eletrônica (NF-e), usada em todo o Brasil, é um documento XML — e o nome de uma empresa com "&" (como "Silva & Cia") invalida a nota inteira se não for escapado corretamente. O mesmo problema aparece em feeds RSS de sites de notícias: uma manchete com um & sem escapar quebra o feed inteiro para quem tenta lê-lo.

Por que o XML é mais rígido que o HTML

Navegadores costumam tolerar HTML malformado e tentam renderizar a página mesmo com erros. Parsers de XML não fazem isso: um único & ou colchete angular sem escapar torna o documento inteiro inválido, e o processamento para com erro.

Quando isso é necessário

  • Preparar texto vindo do usuário antes de inserir num documento XML (feeds, arquivos de configuração, mensagens SOAP).
  • Depuração: ver o texto real escondido atrás das entidades num XML recebido.
  • Editar arquivos XML manualmente sem quebrar a estrutura do documento.

A alternativa às entidades: a seção CDATA

Quando um bloco de texto contém muitos caracteres especiais — um trecho de HTML ou código embutido no XML — costuma ser mais prático envolvê-lo em <![CDATA[...]]>, onde < e & não precisam de escape e são tratados como texto comum. A exceção é a sequência ]]>, que fecha o CDATA e por isso não pode aparecer dentro do próprio conteúdo da seção.

Experimentar a ferramenta