Відсутні поля та нульові поля — це дві різні помилки.

Якщо поле не знайдено або поле має нульове значення, в інтерфейсі може відображатися лише порожнє значення, але значення буде зовсім іншим після входу в програму. Якщо порожнє місце заповнюється числом нуль, нижчий за потоком отримає юридичне значення, але помилково вважатиме, що воно походить з оригінального тексту, що ускладнить пошук проблеми.

Ця стаття призначена для розробників і працівників, які працюють з документами, яким необхідно передати результати вилучення в програми для обробки. Тут пояснюється, як використовувати схему JSON для розрізнення трьох станів і використання кількох вхідних зразків для регресійних перевірок. Прочитавши це, ви можете встановити межі для відсутніх, нульових і нульових значень для вашого власного протоколу даних.

Зразки в цій статті є синтетичними даними, а код було перевірено на прикладах в ізольованому середовищі, але це не є гарантією всіх реальних файлів або ефектів продукту. Перед обробкою важливих документів збережіть оригінали та перегляньте їх відповідно до меж і пунктів прийняття в тексті.

Висновок одним реченням

Поле відсутнє, значення null і значення 0. Має бути три різні стани. Контракт повинен використовувати наявність ключа та типу значення, щоб розділити їх. Він не може покладатися на інтерфейс або вгадування за потоком.

Спочатку розділіть три стани

У композиційному контракті цієї статті має бути присутнім amount, допускаються числові значення або null. Значення трьох станів такі:

• Немає ключа amount: структура виводу є неповною та є винятком контракту.
• amount для null: ключ існує, але сума наразі недоступна.
• amount дорівнює 0: існує однозначне нульове значення.

Інші протоколи можна використовувати для справжнього бізнесу, але вони мають бути чітко прописані та не залишатися на розсуд кожного абонента.

required схеми JSON відповідає за перевірку наявності ключа, а type відповідає за перевірку типу значення. Особливої уваги заслуговують дві поширені помилки:

• Просто написання required не вимикає null автоматично.
• У properties визначено лише поле, і воно не є обов’язковим.

Обидві ці точки підходять для запису безпосередньо в регресійні тести. Щоб отримати повне визначення об’єктів і required, зверніться до Необхідні об’єкти схеми JSON.

Перевірте договір за допомогою чотирьох входів

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 потрібно встановити перед запуском. Цей код лише перевіряє структуру в пам’яті, не викликає модель вилучення та не може довести, що певна кількість узгоджується з вихідним текстом.

Якщо кількість вимагає точного десяткового представлення, замість нього можна використовувати протокол десяткового рядка. Не думайте про двійкові обчислення з плаваючою комою як про фінансове рішення лише тому, що в прикладі використовується number.

Інтерфейс має також чітко вказувати статус.

Відображення на інтерфейсі також має розрізняти стани, інакше користувачі неправильно інтерпретуватимуть різні значення як той самий результат.

Не вставляйте пропущені причини в числові поля

Якщо вам потрібно розрізняти «оригінальний текст не надано», «зображення нечитабельне», «конфлікт кандидатів» тощо, ви можете додати додаткове поле status або reason і визначити для нього дозволені значення.

Не записуйте причину в рядок суми, а потім нехай нижчий за потоком витягує з нього числа. Невідоме – це не те ж саме, що помилка: деякі документи не мають цього поля, і правильний результат – залишити його невідомим.

📊 Основне порівняння

🎯 Який спосіб вам підходить?

Якщо вам потрібно перевірити, чи повний вихід інтерфейсу

Використовуйте required, щоб перевірити, чи існує ключ. Відсутній ключ безпосередньо вважається винятком контракту.

Якщо у вашому документі часто немає певного поля

Дозвольте цьому полю мати значення null і вкажіть причину за допомогою status або reason.

Якщо потрібно точно розрахувати суму

Розгляньте протокол десяткових рядків і не покладайтеся безпосередньо на двійкові числа з плаваючою точкою.

Якщо ви хочете зробити переклад або перевірку після вилучення

Перевірте разом валюту, походження та відповідні мітки, щоб переконатися, що номери ключів не були змінені помилково.

❓ Часті запитання (FAQ)

1. Якщо ви пишете лише обов’язковий, чи означає це, що null заборонено?

немає required лише перевіряє, чи існує ключ, вимкнення null потрібно визначити окремо в type.

2. Яка різниця між нульовим полем і нульовим значенням?

null означає, що наразі немає доступного значення, 0 є однозначним значенням. Обидва мають бути представлені в контракті та інтерфейсі відповідно.

3. Чи означає легальний JSON, що результат вилучення точний?

не означає. Структурна перевірка може лише підтвердити, що формат відповідає контракту, але не може підтвердити, що сума відповідає оригінальному тексту.

4. Чи може поле відображатися як 0, якщо воно відсутнє?

Не рекомендується. Відсутній означає, що вихідна структура неповна. Заповнення 0 призведе до того, що низхідна частина розглядатиме його як реальну суму.

📝 Підсумок

Відсутні, нульові та нульові значення мають власні значення та повинні бути виражені окремо через контракти та інтерфейси. Після затвердження структури все ще потрібно перевірити валюту, джерело та відповідну позначку суми.

Спробуйте зараз: завантажте документ, щоб розпочати переклад, зберігаючи вихідний макет