Campos ausentes e campos nulos são duas falhas diferentes.

Se o campo não for encontrado ou tiver valor nulo, ele poderá exibir apenas um espaço em branco na interface, mas o significado é completamente diferente após entrar no programa. Se o espaço em branco for preenchido com o número zero, o downstream receberá um valor legal, mas erroneamente pensa que vem do texto original, tornando o problema mais difícil de encontrar.

Este artigo é direcionado a desenvolvedores e documentadores que precisam entregar os resultados da extração a programas para processamento. Ele explica como usar o esquema JSON para distinguir três estados e usar vários exemplos de entrada para fazer verificações de regressão. Depois de ler isto, você pode definir os limites para valores ausentes, nulos e zero para seu próprio protocolo de dados.

As amostras neste artigo são dados sintéticos e o código foi verificado pela amostra em um ambiente isolado, mas isso não representa uma garantia de todos os arquivos reais ou efeitos do produto. Antes de processar documentos importantes, guarde os originais e revise-os de acordo com os limites e itens de aceitação do texto.

Conclusão de uma frase

O campo está faltando, o valor é null e o valor é 0. Deve haver três estados diferentes. O contrato deve utilizar a existência da chave e do tipo de valor para separá-los. Ele não pode confiar na interface ou em suposições posteriores.

Primeiro separe os três estados

No contrato de composição deste artigo deverá estar presente amount, sendo permitidos valores numéricos ou null. Os significados dos três estados são os seguintes:

• Sem chave amount: a estrutura de saída está incompleta e é uma exceção de contrato.
• amount para null: a chave existe, mas nenhum valor está disponível no momento.
• amount é 0: existe um valor zero inequívoco.

Outros protocolos podem ser usados para negócios reais, mas devem ser claramente escritos e não podem ser deixados para cada chamador adivinhar.

required do esquema JSON é responsável por verificar se a chave existe e type é responsável por verificar o tipo do valor. Dois equívocos comuns requerem atenção especial:

• Apenas escrever required não desativa automaticamente null.
• Somente o campo está definido em properties, e não é obrigatório aparecer.

Ambos os pontos são adequados para serem gravados diretamente em testes de regressão. Para a definição completa de objetos e required, consulte Objetos do esquema JSON e obrigatórios.

Verifique o contrato com quatro entradas

from jsonschema import Draft202012Validator

schema = {"type": "object", "required": ["amount"],
          "properties": {"amount": {"type": ["number", "null"]}},
          "additionalProperties": False}
validator = Draft202012Validator(schema)
valid = lambda value: not list(validator.iter_errors(value))

assert valid({"amount": None})
assert valid({"amount": 0})
assert not valid({})
assert not valid({"amount": "unknown"})
assert not valid({"amount": None, "guessed": True})

jsonschema precisa ser instalado antes de ser executado. Este código apenas faz uma verificação de estrutura na memória, não chama o modelo de extração e não pode provar que uma determinada quantidade é consistente com o texto original.

Se o valor exigir representação decimal precisa, o protocolo de cadeia decimal poderá ser usado. Não pense nos cálculos de ponto flutuante binário apenas como uma solução financeira só porque o exemplo usa number.

A interface também deve indicar o status claramente.

A exibição na interface também precisa distinguir entre estados, caso contrário, os usuários interpretarão mal significados diferentes como o mesmo resultado.

Não insira motivos faltantes em campos numéricos

Se precisar distinguir entre "texto original não fornecido", "imagem ilegível", "conflito de candidato" etc., você pode adicionar um campo status ou reason adicional e definir valores permitidos para ele.

Não escreva o motivo em uma sequência de valores e depois peça ao downstream que extraia os números dela. Desconhecido não é o mesmo que falha: alguns documentos não possuem este campo, e o resultado correto é deixá-lo desconhecido.

📊 Comparação principal

🎯 Qual método é adequado para você?

Se você precisar verificar se a saída da interface está completa

Use required para verificar se a chave existe. Uma chave ausente é considerada diretamente uma exceção de contrato.

Se o seu documento muitas vezes não possui um determinado campo

Permita que o valor deste campo seja null e especifique o motivo com status ou reason.

Se o valor precisar ser calculado com precisão

Considere o protocolo de string decimal e não confie diretamente em números flutuantes binários.

Se você quiser fazer tradução ou verificação após a extração

Verifique em conjunto a moeda, a proveniência e as etiquetas correspondentes para confirmar que os números-chave não foram alterados por engano.

❓ Perguntas frequentes (FAQ)

1. Se você escrever apenas como obrigatório, isso significa que nulo é proibido?

não. required apenas verifica se a chave existe, a desativação de null precisa ser definida separadamente em type.

2. Qual é a diferença entre um campo ser nulo e um campo ser 0?

null significa que atualmente não há valor disponível, 0 é um valor inequívoco. Ambos devem ser representados no contrato e na interface, respectivamente.

3. JSON legal significa que o resultado da extração é preciso?

Não significa. A fiscalização estrutural só pode confirmar se o formato é consistente com o contrato, mas não pode provar que o valor é consistente com o texto original.

4. O campo pode ser exibido diretamente como 0 quando estiver faltando?

Não recomendado. Ausente significa que a estrutura de saída está incompleta. Preencher 0 fará com que o downstream o trate como o valor real.

📝 Resumo

Valores ausentes, nulos e zero têm significados próprios e devem ser expressos separadamente por meio de contratos e interfaces. Após a aprovação da estrutura, ainda será necessário verificar a moeda, a origem e a etiqueta correspondente do valor.

Experimente agora: carregue o documento para iniciar a tradução, mantendo o layout original