OmniDocフィールドの欠落と null フィールドは 2 つの異なる失敗です。
「フィールドが見つかりません」と「フィールドは null 値です」はどちらもインターフェイス上で空白に表示される場合がありますが、プログラムに入った後に混同しないようにしてください。次に、空白を数値 0 で埋めると、問題はより微妙になります。ダウンストリームは正当な値を受け取りますが、それが元のテキストから来たものであると考えます。
フィールドが見つからない場合、またはフィールドに null 値がある場合は、インターフェイス上に空白が表示されるだけですが、プログラムに入った後の意味はまったく異なります。その後、空白に数字の 0 を入力すると、下流側は正当な値を取得しますが、それが元のテキストから来たものであると誤って認識し、問題の発見がさらに困難になります。
この記事は、抽出結果をプログラムに引き渡して処理する必要がある開発者およびドキュメント ワーカーを対象としています。 JSON スキーマを使用して 3 つの状態を区別し、複数の入力サンプルを使用して回帰チェックを行う方法について説明します。これを読んだ後は、独自のデータ プロトコルの欠損値、null 値、ゼロ値の境界を設定できます。
この記事のサンプルは合成データであり、コードは隔離された環境でサンプルによってチェックされていますが、これはすべての実際のファイルや製品の効果を保証するものではありません。重要な書類を処理する前に、原本を保管し、本文の境界と許容事項に従って確認してください。
一文の結論
フィールドがありません。値は null、値は 0 です。3 つの異なる状態があるはずです。コントラクトでは、キーの存在と値のタイプを使用してそれらを区別する必要があります。インターフェイスやダウンストリームの推測に依存することはできません。
| あなたの状況 | 推奨される実践方法 | 理由 |
|---|---|---|
| 出力構造が完了しているかどうかを確認する必要があります | required でキーが存在するかどうかを確認します | キーが欠落している場合は、出力構造が不完全であり、量がゼロに等しくないことを示します。 |
| 元の記事には金額が記載されていません | 値をnullに設定します | null は、利用可能な値が取得されないことを意味し、0 を入力しないでください |
| 元のテキストでは明示的にゼロが与えられています | 値0を使用 | ゼロは、欠損値や null 値とは異なり、明確な値です。 |
| 抽出しない理由を説明する必要がある | 追加の status または reason フィールドを追加し、許可される値を定義します | ダウンストリームの逆アセンブリを減らすために、金額文字列に理由を入力しないようにします。 |
まず 3 つの状態を分離します
この記事の構成規約では、amount が存在する必要があり、数値または null が許可されます。 3 つの状態の意味は次のとおりです。
amountキーがありません: 出力構造は不完全であり、契約例外です。nullのamount: キーは存在しますが、現在利用可能な金額はありません。amountは 0: 明確なゼロ値があります。
他のプロトコルも実際のビジネスに使用できますが、明確に記述する必要があり、各呼び出し元に推測を任せることはできません。
JSON スキーマの required はキーが存在するかどうかを確認し、type は値の型を確認します。次の 2 つのよくある誤解には特別な注意が必要です。
requiredを書き込むだけでは、nullは自動的に無効になりません。propertiesではフィールドのみが定義されており、出現する必要はありません。
これらの点は両方とも、回帰テストに直接書き込むのに適しています。オブジェクトと required の完全な定義については、JSON スキーマ オブジェクトと必須を参照してください。
4 つの入力を使用してコントラクトを検証する
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 は実行前にインストールする必要があります。このコードはメモリ内の構造チェックを行うだけで、抽出モデルを呼び出していないため、元のテキストと一定量が一致していることを証明することはできません。
金額に正確な 10 進数表現が必要な場合は、代わりに 10 進数文字列プロトコルを使用できます。例で number が使用されているからといって、バイナリ浮動小数点計算を金融ソリューションとして単純に考えないでください。
インターフェイスにはステータスも明確に記載する必要があります。
インターフェイス上の表示でも状態を区別する必要があります。そうしないと、ユーザーが異なる意味を同じ結果として誤解してしまいます。
| データ | 表現すべき状態 | として表示されるべきではありません |
|---|---|---|
| 金額キーなし | 出力コントラクト例外 | 金額はゼロです |
| 金額がヌルです | 利用可能な値が取得されませんでした | 抽出に成功しました |
| 金額は0です | 明確なゼロ値がある | ない |
| 金額は不明な文字列です | この契約に準拠していない | 自動的に null に変換され、サイレントに渡されます |
欠落している理由を数値フィールドに挿入しないでください
「元のテキストが提供されていない」、「画像が読めない」、「候補の競合」などを区別する必要がある場合は、追加の status または reason フィールドを追加し、それに許可される値を定義できます。
理由を金額文字列に書き込んで、下流側でそこから数値を取り出させないでください。不明は失敗と同じではありません。一部のドキュメントにはこのフィールドがないため、不明のままにするのが正しい結果です。
📊 コアの比較
| 州 | 鍵は存在するのでしょうか？ | 価値 | 意味 |
|---|---|---|---|
| ない | いいえ | なし | 出力構造が不完全です |
| NULL値 | はい | null | 現在利用可能な値はありません |
| ゼロ値 | はい | 0 | 明示的な値ゼロ |
🎯 どの方法があなたに適していますか?
インターフェースの出力が完了したかどうかを確認する必要がある場合
required を使用してキーが存在するかどうかを確認します。キーが見つからない場合は、直接契約例外とみなされます。
ドキュメントに特定のフィールドが含まれていないことが多い場合
このフィールド値を null にして、その理由を status または reason で指定します。
金額を正確に計算する必要がある場合
10 進数の文字列プロトコルを考慮し、バイナリ浮動小数点数に直接依存しないでください。
抽出後に翻訳や検証を行いたい場合
通貨、出所、対応するラベルを合わせて確認し、キー番号が誤って変更されていないことを確認してください。
❓ よくある質問 (FAQ)
1. required としか書いていないということは、null は禁止ということでしょうか？
いいえ。 required はキーが存在するかどうかのみをチェックします。null を無効にする場合は、type で個別に定義する必要があります。
2. フィールドが null であることとフィールドが 0 であることの違いは何ですか?
null は現在使用可能な値がないことを意味し、0 は明確な値です。両方をそれぞれコントラクトとインターフェイスで表す必要があります。
3. 正当な JSON は、抽出結果が正確であることを意味しますか?
というわけではありません。構造検査は形式が契約書と一致していることを確認することしかできませんが、金額が原文と一致していることを証明することはできません。
4. フィールドが欠落している場合、フィールドを直接 0 として表示できますか?
お勧めしません。欠落しているということは、出力構造が不完全であることを意味します。 0 を入力すると、下流側で実際の金額として扱われます。
📝 概要
欠損値、null 値、ゼロ値にはそれぞれ独自の意味があり、コントラクトとインターフェイスを通じて個別に表現する必要があります。構造が承認された後も、通貨、ソース、および金額の対応するラベルを確認する必要があります。
