Definição
Schema de validação é um conjunto de regras formais que descreve como um arquivo ou mensagem deve ser estruturado: quais campos existem, quais são obrigatórios, que tipo de dado cada um aceita e em que ordem aparecem. Na emissão fiscal, ele é usado para conferir XML e JSON antes do envio à SEFAZ ou à prefeitura.
Também conhecido como: Validation schema, Schema, Esquema de validação, Esquema de dados, Arquivo de schema
O que é um schema de validação, em palavras simples?
Pense no schema como um formulário oficial com instruções de preenchimento. Ele diz, por exemplo, que o CNPJ deve ter 14 dígitos, que a data precisa seguir um formato específico e que o valor total não pode ficar em branco. Qualquer documento que não respeite essas instruções é considerado inválido.
A diferença é que o schema é escrito em uma linguagem que computadores entendem. Assim, um programa consegue comparar automaticamente um arquivo com as regras e apontar exatamente onde está o problema, sem que alguém precise revisar campo por campo.
Para que serve o schema de validação na emissão de notas fiscais?
Documentos como NF-e, NFC-e, CT-e, MDF-e e NFS-e são enviados em formato XML e precisam seguir um leiaute definido pelos órgãos responsáveis. O schema é a tradução técnica desse leiaute. Se o XML não estiver de acordo com ele, a SEFAZ ou a prefeitura rejeita o documento logo na recepção.
Validar antes de enviar evita rejeições desnecessárias, economiza tempo e dá ao sistema emissor a chance de corrigir o erro ou avisar o usuário com uma mensagem clara, em vez de esperar a resposta do órgão autorizador.
Como funciona a validação por schema na prática?
O sistema monta o documento, carrega o schema correspondente à versão do leiaute em uso e roda um validador. Esse validador percorre o arquivo e verifica estrutura, tipos de dados, tamanhos, valores permitidos e obrigatoriedade de cada campo.
Se tudo estiver correto, o documento segue para assinatura e envio. Se houver falhas, o validador devolve uma lista de erros indicando o campo e o motivo, como um campo obrigatório ausente ou um texto maior do que o permitido.
Em uma API fiscal, costuma haver duas camadas: primeiro o payload JSON recebido do sistema do cliente é validado; depois, o XML gerado a partir dele é conferido contra o schema oficial do documento.
Qual a diferença entre esquema XML (XSD) e JSON Schema?
O esquema XML, geralmente em arquivos com extensão .xsd, valida documentos XML. É o formato usado pelos órgãos fiscais para publicar as regras oficiais de NF-e, CT-e, MDF-e e outros documentos.
O JSON Schema faz o mesmo papel para mensagens em JSON, formato mais comum em APIs REST. Uma API de emissão fiscal pode receber os dados em JSON, validá-los com JSON Schema e só depois convertê-los no XML exigido pelo fisco. Os dois tipos se complementam.
O que o schema de validação não consegue verificar?
O schema confere forma, não conteúdo de negócio. Ele sabe que um campo de CFOP deve ter quatro dígitos, mas não sabe se aquele CFOP faz sentido para a operação. Também não verifica se a soma dos itens bate com o total, se a inscrição estadual está ativa ou se o certificado digital é válido.
Essas checagens são feitas por regras de negócio adicionais, tanto no emissor quanto no órgão autorizador. Por isso, um XML pode passar no schema e ainda assim receber uma rejeição fiscal por outro motivo.
Por que a versão do schema é importante?
Os leiautes fiscais mudam com frequência por meio de notas técnicas, que criam, alteram ou removem campos. A cada mudança, um novo conjunto de schemas é publicado. Validar com uma versão desatualizada pode aprovar um arquivo que o fisco vai recusar, ou recusar um arquivo correto.
Manter os schemas atualizados é uma das tarefas que um emissor por API assume pelo sistema do cliente, reduzindo o trabalho de acompanhar cada nova versão.
Exemplos de Schema de validação
- Um ERP envia à API fiscal um pedido de emissão de NF-e sem o campo de NCM em um item; a validação por JSON Schema bloqueia a requisição e devolve uma mensagem indicando o item e o campo faltante.
- Após uma nota técnica incluir novos grupos de tributação, o emissor atualiza os arquivos XSD da NF-e para que os XMLs gerados sejam validados conforme a nova versão do leiaute.
- Um desenvolvedor, testando no ambiente de homologação, recebe erro de schema porque enviou a data de emissão sem o fuso horário exigido pelo formato oficial.
- Uma plataforma de vendas valida localmente o XML de uma NFC-e antes de transmiti-lo, evitando que um campo com texto acima do tamanho máximo gere rejeição na SEFAZ.
Perguntas frequentes
Schema de validação e leiaute fiscal são a mesma coisa?
Não exatamente. O leiaute é a especificação do documento, geralmente descrita em manuais e notas técnicas. O schema é a versão técnica e automatizável de parte dessas regras, usada por programas para conferir a estrutura do arquivo.
Se o XML passou no schema, a nota será autorizada?
Não necessariamente. O schema verifica estrutura e formato. A autorização depende também de regras de negócio, cálculos, cadastro do emissor, certificado e situação fiscal, que são conferidos pelo órgão autorizador.
Quem precisa usar schemas de validação?
Qualquer sistema que gere documentos fiscais eletrônicos. Ao usar uma API de emissão, boa parte dessa validação é feita pelo próprio emissor, mas o sistema cliente ainda se beneficia de validar seus dados antes do envio.
Onde ficam os schemas oficiais dos documentos fiscais?
Eles são publicados pelos órgãos responsáveis por cada documento, normalmente junto aos manuais de orientação e notas técnicas de cada versão do leiaute.
Atualizado em · Como produzimos este glossário