Como Validar XML Contra um Esquema XSD: Erros, Ferramentas e CI/CD

XSD significa XML Schema Definition. É um padrão do W3C que permite descrever a estrutura exata que um documento XML deve seguir: quais elementos são permitidos, em que ordem aparecem, a quais tipos de dados o conteúdo deve corresponder e quais atributos são obrigatórios ou opcionais. Quando você valida um documento XML contra um XSD, um parser lê ambos os arquivos e relata cada ponto em que o documento desvia do contrato do esquema.

O XSD substituiu o antigo formato DTD (Document Type Definition) como a principal linguagem de esquemas XML porque ele próprio é escrito em XML, suporta um rico conjunto de tipos de dados integrados (`xs:integer`, `xs:date`, `xs:boolean`, etc.) e pode expressar restrições complexas como padrões de string, faixas numéricas e requisitos condicionais de elementos. DTDs ainda são encontrados em sistemas legados, mas o XSD é o padrão para qualquer intercâmbio de dados baseado em XML construído nos últimos quinze anos.

Onde a validação XSD é usada

A validação XSD aparece onde quer que dados XML estruturados cruzem uma fronteira de sistema. Exemplos comuns incluem requisições e respostas de serviços web SOAP (descritas por WSDL, que embute esquemas XSD), formatos de faturamento eletrônico e compras como UBL 2.1 e EDIFACT, intercâmbio de dados de saúde com perfis XML HL7 CDA e FHIR, declarações XML governamentais (impostos, alfândega) e arquivos de configuração de software corporativo como o `pom.xml` do Maven ou o XML de contexto de aplicação do Spring.

• Serviços SOAP / WSDL: cada elemento de requisição e resposta é definido em um XSD embutido.
• Faturamento eletrônico (UBL, CII): formatos de compras e faturas carregam esquemas XSD públicos contra os quais os parceiros comerciais validam.
• Saúde (HL7, FHIR XML): o intercâmbio de documentos clínicos exige conformidade XSD estrita antes da aceitação.
• Declarações governamentais: autoridades fiscais e alfandegárias publicam esquemas XSD que os documentos enviados devem satisfazer.
• Ferramentas de build: o pom.xml do Maven, o build.xml do Ant e muitos outros formatos de configuração usam XSD para auto-completar e validação no IDE.

Todo documento XML deve primeiro ter boa formação antes de poder ser validado. A boa formação é verificada pelo próprio parser XML, sem necessidade de esquema. A validade é uma camada adicional verificada contra um esquema específico. Entender a distinção economiza tempo significativo de depuração: um validador XSD que recebe um documento mal formado frequentemente relata erros de esquema confusos em vez do verdadeiro problema de análise.

Um objeto textual é um documento XML bem formado se corresponde à produção rotulada document e satisfaz todas as restrições de boa formação dadas na especificação.

O que a boa formação verifica

• Pareamento de tags: toda tag de abertura tem uma tag de fechamento correspondente (`<item>` → `</item>`).
• Aninhamento correto: as tags devem fechar em ordem reversa - `<a><b></b></a>` é válido; `<a><b></a></b>` não é.
• Elemento raiz único: o documento tem exatamente um elemento de nível superior.
• Atributos entre aspas: todos os valores de atributo estão envoltos em aspas simples ou duplas.
• Caracteres especiais escapados: `<`, `>`, `&`, `"` e `'` dentro do conteúdo de texto devem usar referências de entidade ou seções CDATA.
• Nomes de elementos e atributos válidos: os nomes começam com letra ou sublinhado, não com dígito ou hífen.

O que a validade XSD acrescenta por cima

Uma vez que a boa formação passa, a validação XSD sobrepõe o contrato do esquema. Isso inclui verificar que todo elemento declarado como obrigatório por `minOccurs="1"` está realmente presente, que o conteúdo de texto em elementos tipados corresponde ao `xs:type` declarado (nada de strings em campos inteiros), que os valores numéricos caem dentro dos limites `xs:minInclusive` e `xs:maxInclusive`, que o conteúdo de string satisfaz as restrições regex `xs:pattern`, e que os elementos filhos aparecem na sequência, escolha ou grupo all definidos no esquema.

Antes de poder validar XML contra um XSD, você precisa entender o que um arquivo XSD contém. Um arquivo de esquema é ele próprio um documento XML válido, com um elemento raiz `xs:schema` no namespace `http://www.w3.org/2001/XMLSchema`. Tudo dentro do esquema descreve como os documentos XML de destino devem ser.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Root element declaration --&gt;
  <xs:element name="Invoice">
    <xs:complexType>
      <xs:sequence>
        <!-- Required string - must be present exactly once --&gt;
        <xs:element name="InvoiceNumber" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <!-- Required date --&gt;
        <xs:element name="IssueDate"     type="xs:date"   minOccurs="1" maxOccurs="1"/>
        <!-- Required positive integer --&gt;
        <xs:element name="TotalAmount"   type="xs:decimal" minOccurs="1" maxOccurs="1"/>
        <!-- Optional - 0 to many line items --&gt;
        <xs:element name="LineItem"      type="LineItemType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <!-- Required attribute --&gt;
      <xs:attribute name="currency" type="xs:string" use="required"/>
    </xs:complexType>
  </xs:element>

  <!-- Reusable complex type definition --&gt;
  <xs:complexType name="LineItemType">
    <xs:sequence>
      <xs:element name="Description" type="xs:string"/>
      <xs:element name="Quantity"    type="xs:positiveInteger"/>
      <xs:element name="UnitPrice"   type="xs:decimal"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>

Conceitos-chave do XSD

• xs:element: declara um elemento por nome e tipo. `minOccurs` e `maxOccurs` controlam a cardinalidade.
• xs:complexType: define um elemento que contém elementos filhos ou atributos (não apenas texto).
• xs:simpleType: define um tipo derivado de um tipo integrado - usado para adicionar restrições como padrões ou enumerações.
• xs:sequence: os elementos filhos devem aparecer na ordem exata listada.
• xs:choice: exatamente um dos elementos filhos listados deve aparecer.
• xs:all: todos os elementos filhos listados devem aparecer, em qualquer ordem, cada um exatamente uma vez.
• xs:attribute: declara um atributo em um elemento complexo. `use="required"` o torna obrigatório.
• xs:restriction: adiciona restrições a um tipo base - `xs:pattern`, `xs:minInclusive`, `xs:enumeration`, etc.

Há três formas práticas de validar um documento XML contra um esquema XSD: uma ferramenta baseada em navegador para verificações rápidas, uma ferramenta de linha de comando para desenvolvimento local e scripting, e uma abordagem programática para integração no código da aplicação ou pipelines de CI. Todas as três abordagens relatam as mesmas categorias de erros - a diferença está em onde e como você executa a validação.

# Validate document.xml against schema.xsd using xmllint
xmllint --schema schema.xsd document.xml --noout

# Output on success:
document.xml validates

# Output on failure:
document.xml:12: element TotalAmount: Schemas validity error:
Element 'TotalAmount': 'abc' is not a valid value of the
atomic type 'xs:decimal'.

Os erros de validação XSD caem em categorias previsíveis. Entender o que cada tipo de erro significa permite localizar e corrigir o problema no documento de origem rapidamente, em vez de decodificar saída desconhecida do validador linha por linha.

Erros de incompatibilidade de tipos

Erros de tipo ocorrem quando o conteúdo de um elemento ou atributo não corresponde ao `xs:type` declarado. Os mais comuns: uma string como `"N/A"` em um campo declarado como `xs:integer`, uma data no formato errado (por exemplo, `15/06/2026` em vez de `2026-06-15`) em um campo `xs:date`, ou um decimal em um campo declarado como `xs:positiveInteger`. Corrija ajustando o valor no documento de origem ou modificando a declaração de tipo no esquema se o tipo atual for restritivo demais.

Elementos obrigatórios ausentes

Quando `minOccurs="1"` (o padrão de `xs:element`) e o elemento está ausente do documento de instância, o validador relata: `Element 'X': This element is not expected. Expected is one of ( Y )` ou `Element 'X' is missing`. Isso normalmente significa que o produtor do XML omitiu um campo obrigatório. Consulte o `xs:sequence` do esquema para confirmar quais elementos são obrigatórios e em qual posição.

Elementos inesperados ou não declarados

Se seu esquema não usa `xs:any` e não define `processContents="lax"`, qualquer elemento não declarado no esquema produzirá: `Element 'X': This element is not expected`. Este é o erro mais comum quando um produtor de XML adiciona um novo campo sem atualizar o esquema, ou quando o documento contém um prefixo de namespace não declarado. Verifique o nome do elemento, o contexto do elemento pai e as declarações de namespace no topo do documento.

Violações de padrão e enumeração

O XSD suporta `xs:pattern` (uma regex) e `xs:enumeration` (uma lista de valores permitidos) como facetas em tipos simples. Uma violação se parece com: `Element 'Status': [facet 'enumeration'] The value 'ACTIVE' is not an element of the set active', 'inactive', 'pending`. Verifique se o esquema usa valores de enumeração sensíveis a maiúsculas e se o documento de instância corresponde exatamente às maiúsculas esperadas.

A validação manual serve para verificações pontuais, mas os fluxos XML de produção precisam de validação automatizada em cada ponto de integração. Adicionar validação XSD ao seu código de aplicação e pipeline de CI garante que documentos inválidos sejam rejeitados antes de causarem corrupção de dados, falhas de processamento ou violações de conformidade a jusante.

Validando em Python com lxml

from lxml import etree

def validate_against_xsd(xml_path: str, xsd_path: str) -> list[str]:
    """Returns a list of validation error messages, empty if valid."""
    with open(xsd_path, 'rb') as f:
        schema_doc = etree.parse(f)
    schema = etree.XMLSchema(schema_doc)

    with open(xml_path, 'rb') as f:
        doc = etree.parse(f)

    schema.validate(doc)
    return [str(e) for e in schema.error_log]

errors = validate_against_xsd('invoice.xml', 'invoice.xsd')
if errors:
    for err in errors:
        print(err)
else:
    print('Document is valid.')

Adicionando validação XSD ao GitHub Actions

Para fluxos CI/CD que processam ou geram XML, uma etapa de validação impede que documentos quebrados sejam mesclados. O comando `xmllint` está disponível nos runners Ubuntu do GitHub Actions via `sudo apt-get install -y libxml2-utils`. Adicione uma etapa que executa `xmllint --schema schema.xsd document.xml --noout` em cada pull request que tocar arquivos XML. Um código de saída não zero falha a verificação e bloqueia a mesclagem.

name: Validate XML
on:
  pull_request:
    paths:
      - '**/*.xml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install xmllint
        run: sudo apt-get install -y libxml2-utils
      - name: Validate XML against XSD
        run: |
          xmllint --schema schemas/invoice.xsd \
                  data/invoices/*.xml \
                  --noout

Usando XPath para inspecionar valores específicos antes da validação

Antes de executar uma passagem XSD completa, você pode usar o Localizador e Testador de XPath para localizar o valor de um elemento ou atributo específico em um documento XML grande. Consultas XPath como `//Invoice/TotalAmount/text()` recuperam um campo sem precisar analisar o arquivo inteiro manualmente. Isso é especialmente útil ao diagnosticar uma incompatibilidade de tipos em um documento com centenas de elementos - localize primeiro o valor problemático e aplique depois a correção.

Comparação de abordagens de validação

Um esquema XSD bem projetado torna os documentos mais fáceis de validar, de estender e de manter entre versões do esquema. Essas práticas se aplicam tanto se você está escrevendo um esquema do zero quanto mantendo um recebido de um parceiro externo.

Use tipos nomeados em vez de tipos anônimos em linha

Defina tipos complexos com `xs:complexType name="..."` em vez de aninhá-los anonimamente dentro das declarações de elementos. Tipos nomeados podem ser reutilizados em várias declarações de elementos, reduzindo a repetição e facilitando mudanças no esquema - atualize a definição do tipo uma vez e todos os elementos que o usam herdam a mudança.

Prefira xs:sequence a xs:all para contratos estritos

`xs:all` permite que elementos apareçam em qualquer ordem, o que parece permissivo mas introduz ambiguidade para produtores e consumidores. `xs:sequence` é mais explícito e corresponde à ordem natural de leitura da maioria dos formatos XML. Use `xs:all` apenas quando a ordem dos elementos genuinamente não importa e você está escrevendo o esquema para um sistema que controla; prefira `xs:sequence` para qualquer esquema que cruze fronteiras organizacionais.

Versione seus esquemas com um namespace

Use um URI de target namespace que inclua um indicador de versão, como `targetNamespace="urn:example:invoice:v2"`. Isso torna explícitas as mudanças de esquema que quebram compatibilidade - consumidores na v1 verão um mismatch de namespace em vez de validar silenciosamente contra a versão errada do esquema. Mantenha o esquema antigo disponível para implantações retrocompatíveis durante a janela de migração.

• Declare um targetNamespace: evita colisões de nomes de elementos quando esquemas são compostos via xs:import.
• Use xs:documentation: adicione descrições legíveis dentro de blocos xs:annotation para que os consumidores do esquema entendam cada campo.
• Defina minOccurs/maxOccurs explícitos: nunca dependa do padrão - declare a cardinalidade explicitamente para comunicar a intenção.
• Use xs:restriction para strings restritas: um campo de CEP deveria usar xs:pattern, não xs:string - a validação captura erros de formato na fronteira.
• Divida esquemas grandes: use xs:include para partir um esquema de 500 linhas em arquivos por domínio (addresses.xsd, line-items.xsd) para facilitar a manutenção.