Referência de qualidade de dados

Tipos de regra de validação

O relatório de qualidade agrega a pontuação por tipo de entidade.

Tipo	Restringe	Configuração
Expressão regular	Formato	Um padrão
Faixa	Limites	Mínimo, máximo
Comprimento	Comprimento de texto	Mínimo, máximo
Lookup	Pertencimento a uma lista controlada	O tipo de lookup
Unicidade	Não repetição dentro de um escopo	O escopo
Entre campos	Uma condição sobre um atributo dado outro	Uma condição e uma consequência
Personalizada	Uma função nomeada	O nome da função e seus parâmetros

O catálogo de funções personalizadas é servido pela plataforma. Consulte-o em vez de transcrevê-lo — uma lista copiada para um documento diverge do software.

O que os pacotes distribuídos realmente configuram

Regras como aparecem nos pacotes, para que os formatos abaixo sejam os que a plataforma aceita:

{ "attribute": "lei",            "ruleType": "regex",
  "ruleConfig": { "pattern": "^[A-Z0-9]{18}[0-9]{2}$" },
  "severity": "error",  "errorMessageKey": "errors.LEI_FORMAT" }

{ "attribute": "npi",            "ruleType": "regex",
  "ruleConfig": { "pattern": "^[0-9]{10}$" },
  "severity": "error" }

{ "attribute": "chassis",        "ruleType": "regex",
  "ruleConfig": { "pattern": "^[A-HJ-NPR-Z0-9]{17}$" },
  "severity": "error" }

{ "attribute": "date_of_birth",  "ruleType": "range",
  "ruleConfig": { "min": "1900-01-01", "max": "today" },
  "severity": "error" }

{ "ruleType": "cross_field",
  "ruleConfig": {
    "if":   { "attribute": "address.country", "op": "eq", "value": "US" },
    "then": { "attribute": "address.state", "condition": "required" } },
  "severity": "warning" }

Três delas merecem segunda leitura. O padrão de veículo exclui I, O e Q porque um chassi nunca os contém. max: "today" é um limite relativo, não uma data que você precise manter. E a regra entre campos é estruturada, não uma expressão em texto livre, o que permite à plataforma recusar uma regra malformada ao salvar em vez de falhar silenciosamente na avaliação.

Duas regras num mesmo atributo

Regras se compõem. Um identificador recebe uma regra de formato e uma regra que recusa valores de preenchimento conhecidos:

{ "attribute": "ssn", "ruleType": "regex",
  "ruleConfig": { "pattern": "^\\d{3}-?\\d{2}-?\\d{4}$" },
  "severity": "error", "errorMessageKey": "errors.SSN_FORMAT" }

{ "attribute": "ssn", "ruleType": "regex",
  "ruleConfig": { "pattern": "^(?!(\\d)\\1{8}$)\\d{3}-?\\d{2}-?\\d{4}$" },
  "severity": "error", "errorMessageKey": "errors.SSN_PLACEHOLDER" }

A segunda recusa nove dígitos repetidos — 111-11-1111, 000-00-0000. Isso importa muito mais do que parece: um identificador de preenchimento que passa na validação vira um identificador compartilhado, e um identificador compartilhado é o que consolida duas pessoas sem relação num mesmo registro.

Validadores de dígito verificador existem, mas nenhum pacote os usa

A plataforma registra validadores nomeados de dígito verificador — para o dígito Luhn do NPI, roteamento ABA, o dígito ISO 17442 do LEI e MOD-97 do IBAN — e o único que algum pacote distribuído configura é validate_calendar_date, que recusa datas impossíveis como 30 de fevereiro.

Então, de fábrica, as regras de identificador acima verificam formato, não dígito verificador. Um NPI bem formado com dígito errado passa. Ligar os validadores de dígito verificador a esses atributos é um endurecimento inicial razoável, e é mudança de configuração, não de código.

Campos de uma regra de validação

Todos os campos que uma regra de validação aceita.

Campo	Aceita	Padrão	Alterável	O que faz
entityTypeId	Um tipo de entidade	—	Não	A qual tipo a regra se aplica.
attributeDefId	Um atributo, ou vazio	—	Não	Qual atributo a regra restringe. Fica vazio para regras que não tratam de um único atributo — uma regra entre campos abrange dois, então não se vincula a nenhum.
ruleType	Um dos sete tipos acima	—	Sim	Que espécie de restrição é esta.
ruleConfig	Um objeto	{}	Sim	As configurações da restrição. O formato segue o tipo — veja os exemplos acima.
severity	error, warning, info	error	Sim	Se uma violação bloqueia a gravação. Veja o aviso adiante.
errorMessageKey	Até 255 caracteres	—	Sim	A mensagem exibida quando a regra falha, como chave de tradução, para que apareça no idioma do leitor.
sourceTypeFilter	Até 100 caracteres	—	Sim	Restringe a regra a registros de um sistema de origem. É isto que permite um campo ser obrigatório vindo de um sistema e opcional vindo de outro.
isActive	verdadeiro ou falso	true	Sim	Se a regra é avaliada. Desativar é a alternativa reversível a excluir.
metadata	Um objeto	{}	Sim	Suas próprias anotações, armazenadas e devolvidas sem interpretação.

O tipo e o atributo são fixos depois de criados. Para restringir outro atributo, crie outra regra.

Uma regra nova bloqueia gravações a menos que você diga o contrário

severity assume error por padrão, e uma violação de severidade error recusa o registro. Ou seja, uma regra adicionada sem definir a severidade passa a rejeitar dados de entrada assim que é salva.

Esse padrão é o correto — uma restrição que você quis impor deve impor — mas se você está introduzindo uma regra contra dados ainda não higienizados, salve-a primeiro como warning. Assim você obtém as contagens de violação sem recusar registros, e pode promovê-la a error quando a fila estiver limpa.

Delimitar uma regra a um sistema de origem

sourceTypeFilter é o campo mais esquecido. Sem ele a regra vale para todo registro do tipo, venha de que sistema vier — o que raramente é o desejado quando um sistema é a autoridade sobre um campo e outro sequer o carrega.

Com ele, o mesmo atributo pode ser obrigatório vindo do sistema que o governa e ausente nos demais, sem que nenhum dos lados reporte violação falsa.

Severidades

Severidade	Bloqueia a gravação	Registrada como violação
Erro	Sim	Sim
Aviso	Não	Sim
Informativo	Não	Sim

A severidade governa se a gravação prossegue. Nenhuma severidade altera a pontuação — a pontuação mede completude, não desfechos de regra. Violações são expostas por direito próprio.

Regras entre campos

Uma regra entre campos expressa "se isto, então aquilo" entre dois atributos — por exemplo, exigir uma região quando o país é um que as tem.

As duas metades são estruturadas em vez de expressões livres, e é isso que permite validar a configuração ao salvar em vez de falhar no momento da avaliação.

Pontuação

Sinal	Mede
Completude	Atributos preenchidos como fração dos esperados. É a pontuação.
Atualidade	Recência, decaindo com a idade. Reportada separadamente.

Não é um composto ponderado

A pontuação não é uma mistura ponderada de várias dimensões, e não há ponderação por organização a configurar. Acurácia, consistência e unicidade não são dimensões de pontuação — resultados de validação são registrados como violações, e a duplicação é assunto da comparação.

Violações em atributos multivalorados

Situação	Severidade
Um valor sem tipo de uso onde o atributo espera um	Aviso — registrado, não bloqueante
Um valor com tipo de uso fora da lista vinculada	Erro

A assimetria é deliberada. Um tipo de uso ausente é dado incompleto que vale sinalizar; um não reconhecido é inequivocamente errado, e aceitá-lo descartaria silenciosamente a intenção de quem chamou.

Validade da configuração

Uma regra cuja configuração não pode ser avaliada é rejeitada ao salvar. Uma regra que nunca dispara é pior que nenhuma regra, porque parece cobertura.

A seguir

• Configure validação e pontuação

---

Última verificação no commit d3c2586b (2026-08-03)