Definição
XML Schema restriction é o mecanismo da linguagem XSD (XML Schema Definition) que cria um tipo de dado a partir de outro já existente, limitando os valores aceitos por meio de regras chamadas facetas, como tamanho máximo, lista de opções, padrão de caracteres e casas decimais. Nos documentos fiscais eletrônicos, essas restrições definem o formato válido de cada campo.
Também conhecido como: XML Schema restriction, Restrição de esquema XML, Restrição XSD, xs:restriction, Derivação por restrição, Faceta de restrição
O que é uma restriction em XML Schema?
Um XML Schema, ou esquema XSD, é um arquivo que descreve como um documento XML deve ser montado: quais campos existem, em que ordem aparecem e que tipo de valor cada um aceita. A restriction (restrição) é uma das ferramentas desse esquema para dizer exatamente o que pode ou não pode ir dentro de um campo.
Ela funciona partindo de um tipo básico, como texto, número inteiro ou decimal, e estreitando as possibilidades. Por exemplo: em vez de aceitar qualquer texto, o campo passa a aceitar apenas 14 dígitos numéricos, o formato de um CNPJ.
Como funciona uma restriction na prática?
Dentro do arquivo XSD, a restrição é declarada com o elemento xs:restriction, que indica um tipo de base (por exemplo, xs:string ou xs:decimal) e, em seguida, lista as regras que limitam esse tipo. Essas regras são chamadas de facetas.
Quando um sistema gera um XML, um validador compara cada campo com o esquema. Se o valor respeita todas as facetas, o campo é aceito. Se viola qualquer uma delas, o documento inteiro é considerado inválido em relação ao schema, mesmo que o resto esteja correto.
Quais são as facetas mais usadas em uma restriction?
As principais facetas são: length, minLength e maxLength, que controlam a quantidade de caracteres; pattern, que define um padrão por expressão regular; enumeration, que lista os únicos valores permitidos; minInclusive e maxInclusive, que estabelecem faixas numéricas; totalDigits e fractionDigits, que limitam o total de dígitos e as casas decimais; e whiteSpace, que define como espaços em branco são tratados.
Várias facetas podem ser combinadas no mesmo tipo. Um campo de valor monetário, por exemplo, pode exigir no máximo 15 dígitos no total, com até 2 casas decimais, e um padrão que proíba zeros desnecessários à esquerda.
Por que restrictions importam nos documentos fiscais eletrônicos?
NF-e, NFC-e, CT-e, MDF-e e NFS-e são arquivos XML validados contra esquemas oficiais. Esses esquemas usam restrictions em grande parte dos campos: chave de acesso com 44 dígitos, código de UF limitado a valores válidos, datas em formato específico, valores com casas decimais definidas e textos com tamanho mínimo e máximo.
Se o XML enviado desrespeita alguma restrição, a autoridade fiscal rejeita o documento por falha de schema antes mesmo de analisar regras tributárias. Por isso, entender essas restrições ajuda desenvolvedores a montar documentos corretos e a interpretar mensagens de rejeição.
Qual a diferença entre restriction e validação de regras de negócio?
A restriction verifica apenas o formato: se o campo tem o tamanho certo, os caracteres permitidos ou um valor dentro da lista. Ela não sabe, por exemplo, se o CNPJ informado existe, se o CFOP combina com a operação ou se o imposto foi calculado corretamente.
Essas verificações de conteúdo são feitas depois, pelas regras de validação do fisco. Na prática, um documento passa primeiro pela checagem de schema e só então pelas regras de negócio, e cada etapa gera tipos diferentes de rejeição.
Como evitar erros causados por restrictions?
O caminho mais seguro é validar o XML localmente contra a versão correta do esquema antes de enviá-lo, usando bibliotecas de validação disponíveis na maioria das linguagens de programação. Também é importante acompanhar atualizações dos pacotes de schemas, pois novas versões podem alterar facetas.
Quando a emissão é feita por uma API fiscal, parte desse trabalho costuma ficar com a própria API, que monta o XML a partir de dados enviados em outro formato, como JSON, e aponta campos fora do padrão antes do envio ao fisco.
Exemplos de XML Schema restriction
- O campo de CNPJ do emitente da NF-e usa uma restriction com pattern que aceita exatamente 14 dígitos numéricos; um valor com pontos, barra e hífen é rejeitado por falha de schema.
- A justificativa de cancelamento de uma NF-e tem restriction de tamanho, exigindo no mínimo 15 caracteres; um texto como 'erro' faz o evento ser recusado.
- O código da UF é definido por uma restriction do tipo enumeration, que só aceita os códigos numéricos oficiais dos estados.
- Um campo de valor do produto restrito a 2 casas decimais é rejeitado quando o sistema envia 150.3456 em vez de 150.35.
Perguntas frequentes
Posso alterar uma restriction de um esquema fiscal oficial?
Não. Os esquemas dos documentos fiscais são definidos pelos órgãos responsáveis e o XML precisa obedecê-los exatamente. Alterar o XSD localmente só esconde o erro, que continuará aparecendo na validação feita pelo fisco.
O que acontece se um campo violar uma restriction?
O documento é rejeitado por falha de schema e não é autorizado. A mensagem de retorno geralmente indica o campo problemático, permitindo corrigir o valor e reenviar o documento.
Restriction existe também em JSON?
O conceito equivalente existe no JSON Schema, com palavras-chave como maxLength, pattern, enum e minimum. A sintaxe é diferente, mas a ideia de limitar valores aceitos por campo é a mesma.
Uma restriction garante que o documento está fiscalmente correto?
Não. Ela garante apenas que o formato dos campos está correto. Cálculo de tributos, coerência entre campos e situação cadastral são verificados por regras de negócio separadas.
Atualizado em · Como produzimos este glossário