XML Schema enumeration

O que é uma enumeration no XML Schema?

Um XML Schema, também chamado de XSD, é um arquivo que descreve como um documento XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de dado cada um aceita. A enumeration é uma das regras que esse esquema pode impor a um campo.

Na prática, ela funciona como um menu de opções fechado. Em vez de aceitar qualquer texto ou número, o campo só aceita os valores listados no esquema. É parecido com um formulário em que você escolhe uma opção de uma lista suspensa, sem poder digitar algo livremente.

Como funciona a enumeration dentro de um XSD?

No XSD, o campo recebe um tipo simples com uma restrição. Dentro dessa restrição aparecem várias linhas do elemento xs:enumeration, cada uma com um valor permitido. Se um campo tem as enumerations 1 e 2, apenas esses dois valores passam na validação.

O tipo de base continua valendo. Se a restrição é feita sobre um texto, o valor precisa ser exatamente igual ao listado, inclusive em letras maiúsculas e minúsculas, sem espaços extras. Um 1 com espaço antes ou depois, por exemplo, pode ser recusado.

Onde a enumeration aparece nos documentos fiscais eletrônicos?

Os esquemas oficiais de NF-e, NFC-e, CT-e, MDF-e e da NFS-e usam enumerations em muitos campos que representam códigos padronizados. Exemplos comuns na NF-e são o tipo de ambiente (1 para produção e 2 para homologação), o tipo de operação (0 para entrada e 1 para saída) e o modelo do documento (55 para NF-e e 65 para NFC-e).

Também são definidos por lista a modalidade do frete, a finalidade da nota, o indicador de presença do comprador e os códigos de UF, entre outros. Isso garante que todos os emissores do país usem os mesmos códigos e que o fisco consiga interpretar cada documento sem ambiguidade.

O que acontece quando um valor não está na lista?

Quando o XML é validado contra o esquema e um campo traz um valor que não consta da enumeration, o documento é considerado inválido. No envio à SEFAZ ou à prefeitura, isso resulta em rejeição por falha de schema, e o documento não é autorizado.

Esse tipo de erro costuma acontecer quando o sistema usa um código desatualizado, digita a descrição no lugar do código (escrever Saída em vez de 1, por exemplo) ou envia um valor válido em outro layout, mas não na versão vigente do esquema.

Qual a diferença entre enumeration e outras restrições do XSD?

O XSD tem outras regras, chamadas facetas, que também limitam valores. A pattern define um formato por meio de expressão regular, como exigir 44 dígitos numéricos na chave de acesso. As facetas de tamanho limitam a quantidade de caracteres, e as de valor mínimo e máximo limitam faixas numéricas.

A diferença é que a enumeration não descreve um formato: ela lista explicitamente cada valor aceito. Use enumeration quando as opções são poucas e conhecidas; pattern e tamanho quando há muitas combinações possíveis seguindo uma regra.

Como lidar com enumerations em uma integração fiscal por API?

Em uma emissão fiscal por API, o sistema do cliente costuma enviar os dados em JSON, e a infraestrutura de emissão monta o XML no layout oficial. Mesmo assim, os códigos enviados precisam corresponder às listas do esquema, por isso é útil manter tabelas internas de conversão entre os cadastros do ERP e os códigos fiscais.

Os esquemas mudam com novas versões de layout e notas técnicas, que podem incluir ou retirar valores. Validar os dados antes do envio e testar no ambiente de homologação ajuda a identificar enumerations desatualizadas antes que elas causem rejeições em produção.

Exemplos de XML Schema enumeration

• Um ERP envia uma NF-e com o campo de tipo de ambiente igual a 3. Como o esquema só aceita 1 ou 2, o documento é rejeitado por falha de schema.
• Uma plataforma de vendas grava a modalidade de frete como texto (FOB) em vez do código numérico definido na enumeration, e o XML gerado não passa na validação.
• Uma equipe de desenvolvimento consulta o XSD oficial para montar uma tabela de conversão entre os status de pedido do sistema e os valores permitidos para a finalidade da NF-e.
• Após a publicação de uma nova versão de layout, um software de gestão atualiza suas listas internas para incluir novos códigos aceitos em um campo de enumeration.