OmniDocRechnungen und Quittungen teilen sich den gleichen Eingang. Wie kann eine Vermischung der beiden Strukturen vermieden werden?
Eine Schnittstelle empfängt sowohl Rechnungen als auch Quittungen, und es ist einfach, große Objekte mit „alle Felder optional“ zu schreiben. Ein solches Objekt kann alles enthalten, aber es ist schwierig zu sagen, was genau es erhält. Es wäre klarer, zwei separate Verträge beizubehalten und einen davon mit dem expliziten Typfeld auszuwählen.
Rechnungen und Quittungen werden häufig zur Verarbeitung in dieselbe Schnittstelle eingegeben. Wenn jedoch nur ein breites Objekt mit der Option „Alle Felder optional"für den Empfang verwendet wird, kann es zwar alle Eingaben aufnehmen, aber nicht erkennen, welche Art von Dokument empfangen wird. Dieser Artikel richtet sich an Entwickler und Geschäftsmitarbeiter, die eine Dokumentempfangsschnittstelle entwerfen oder JSON-Schema-Validierungsregeln verwalten müssen. Nachdem Sie dies gelesen haben, erfahren Sie, wie Sie zwei unabhängige Verträge verwalten, einen mit einem expliziten Typfeld auswählen und mit Zweigkonflikten und unbekannten Typen umgehen.
Die Beispiele in diesem Artikel verwenden synthetische Proben, um Verarbeitungsmethoden zu demonstrieren. Der Code wurde anhand von Beispielen in einer isolierten Umgebung überprüft, dies ist jedoch keine Garantie für alle echten Dateien oder die Produktleistung. Bevor Sie wichtige Dokumente bearbeiten, bewahren Sie bitte die Originale auf und überprüfen Sie sie anhand der Grenzen und Akzeptanzpunkte im Text.
Wie gehe ich mit dem gemeinsamen Eingang von Rechnungen und Belegen um? Fazit in einem Satz
Wenn Sie zwei Dokumente vom selben Portal empfangen, ist es klarer, zwei separate Verträge zu behalten und das erforderliche Feldkind zu verwenden, um einen davon auszuwählen, anstatt ein breites Objekt zu verwenden, das alles enthalten kann.
| Ihre Situation | Empfohlene Praktiken | Grund |
|---|---|---|
| Für den Empfang von Rechnungen und Quittungen muss dieselbe Schnittstelle verwendet werden | Behalten Sie zwei separate Verträge bei, die mit dem erforderlichen Feld für die Art ausgewählt sind | Ein großes Objekt, bei dem alle Felder optional sind, kann alles enthalten, aber es ist schwierig zu erklären, was empfangen wird. |
| Organisieren Sie Filialen mit oneOf | Jeder Zweig verwendet const, um die Art festzulegen | oneOf erfordert, dass genau ein Zweig übereinstimmt. Überlappende Zweigfelder führen dazu, dass die zulässige Eingabe fehlschlägt. |
| Fehlender Eingabetyp oder Feldkonflikt | Geben Sie eine eindeutige Fehlermeldung mit widersprüchlichen Feldern und Quellen zurück | Nur die Anzeige „keine Übereinstimmung"hilft nicht bei der Lokalisierung des Problems |
| Der Klassifikator kann nicht zwischen Dokumenttypen unterscheiden | Behalten Sie den unbekannten Status bei und geben Sie die zu klassifizierende unabhängige Warteschlange ein | Die zufällige Auswahl eines Zweigs führt nur zu einem vorgetäuschten „Erfolg". |
| Strukturüberprüfung bestanden | Dies bedeutet weder, dass die Klassifizierung korrekt ist, noch dass die Dokumente authentisch sind. | Klassifizierungsvertrauen, Strukturverifizierung und Geschäftsauthentizität sind drei verschiedene Ebenen |
Warum können Sie kein breites Objekt verwenden?
Risiko, alle Felder optional zu machen
Wenn eine Schnittstelle sowohl Rechnungen als auch Quittungen akzeptiert, ist es einfach, große Objekte mit „alle Felder optional"zu schreiben. Ein solches Objekt kann tatsächlich eine Vielzahl von Eingaben empfangen, allerdings auf Kosten von:
- Anhand der Struktur lässt sich nicht erkennen, welches Dokument eingegangen ist.
- Die erforderlichen und optionalen Elemente der beiden Dokumente werden miteinander vermischt und die Verifizierungsregeln werden immer unschärfer.
- Wenn ein Fehler auftritt, ist es schwierig, genau zu erklären, warum die Eingabe nicht den Erwartungen entspricht.
Es wäre klarer, zwei separate Verträge beizubehalten und einen davon mit einem expliziten Typfeld auszuwählen.
oneOf ist nicht irgendein
Überlappende Zweige führen dazu, dass die zulässige Eingabe fehlschlägt.
oneOf erfordert, dass die Eingabe genau mit einem Zweig übereinstimmt. Wenn beide Zweige gleichzeitig bestehen, schlägt die Gesamtüberprüfung fehl.
Wenn Zweige nur wenige optionale Felder enthalten, ist es wahrscheinlich, dass sie sich erheblich überschneiden. Derzeit bestehen rechtliche Eingaben die Überprüfung nicht.
Verwenden Sie kind und const, um Überlappungen zu vermeiden
Durch die Verwendung des erforderlichen kind-Felds und des festen Werts von const können klare Grenzen zwischen Zweigen festgelegt und solche Überlappungen im Voraus beseitigt werden.
Weitere Einzelheiten zu den Kombinationsregeln finden Sie unter JSON-Schema-Kombinationsregeln.
Ein ausführbares Offload-Protokoll
from jsonschema import Draft202012Validator
def branch(kind, identity):
return {
"type": "object", "additionalProperties": False,
"required": ["kind", identity],
"properties": {"kind": {"const": kind},
identity: {"type": "string", "minLength": 1}}
}
schema = {"oneOf": [branch("invoice", "invoice_number"),
branch("receipt", "receipt_number")]}
v = Draft202012Validator(schema)
valid = lambda x: not list(v.iter_errors(x))
assert valid({"kind": "invoice", "invoice_number": "I-1"})
assert valid({"kind": "receipt", "receipt_number": "R-1"})
assert not valid({"kind": "invoice", "receipt_number": "R-1"})
assert not valid({"kind": "receipt", "receipt_number": ""})
assert not valid({"kind": "invoice", "invoice_number": "I-1",
"receipt_number": "R-1"})
assert not valid({"kind": "unknown"})Dies ist ein vereinfachter Beispieldatensatz und kein vollständiges Feldmodell einer echten Rechnung. Der Code demonstriert die Zweigauswahl und die Ablehnung redundanter Felder. Steuersatz, Kopf und Betrag müssen separat definiert werden.
Wenn das Unternehmen zusätzliche Felder zulässt, sollten die Namespaces für diese Felder explizit angegeben werden, anstatt stillschweigend alle Einschränkungen aufzuheben.
Zeigen Sie in der Fehlermeldung nicht einfach „keine Übereinstimmung"an
Es wird nur „Nichtübereinstimmung"angezeigt und weder Benutzer noch Betreuer wissen, wo das Problem liegt. In der folgenden Tabelle sind mehrere gängige Eingabefunktionen und entsprechende Feedbackmethoden aufgeführt:
| Eingabefunktionen | Tatsächliche Zweifel | Vorschläge und Feedback |
|---|---|---|
| Art fehlt | Protokoll kann nicht ausgewählt werden | Bitte geben Sie den Dokumenttyp an |
| Typkonflikt mit Zahlenfeld | Die beiden Strukturen sind gemischt | Zeigen Sie widersprüchliche Felder und Quellen an |
| Nummer leerer String | Der Schlüssel ist vorhanden, hat aber keinen Wert | Schauen Sie noch einmal auf den nummerierten Bereich |
| unbekannter Typ | Nicht durch die aktuelle Vereinbarung abgedeckt | Betreten Sie die unabhängige Warteschlange |
Auch unbestimmte Typen benötigen eine Steckdose
Wenn der Klassifikator nicht zwischen Rechnungen und Belegen unterscheiden kann, sollte er den unbekannten Status verlassen, anstatt einen zufälligen Zweig auszuwählen, um „Erfolg"zu erraten.
Dabei gibt es drei verschiedene Ebenen, die gesondert betrachtet werden müssen:
- Klassifizierungssicherheit: Wie sicher ist das System bei der Beurteilung des Dokumenttyps?
- Strukturüberprüfung: Ob die Eingabe dem ausgewählten Vertrag entspricht.
- Geschäftliche Authentizität: Ob das Dokument selbst authentisch und gültig ist.
Das Bestehen der Strukturprüfung kann nicht beweisen, dass die Klassifizierung korrekt ist, und auch nicht, dass das Dokument echt ist.
Der Dokumenttyp muss auch im Übersetzungsprozess beibehalten werden
Für dasselbe Feld müssen möglicherweise in verschiedenen Dokumenten unterschiedliche Begriffe verwendet werden. Bei Verwendung der Terminologie und der zweisprachigen Prüfabläufe von OmniDoc hilft die Bereitstellung des Dokumenttyps zusammen mit der Lieferliste den Prüfern, den Kontext der Zahlen und Beträge zu verstehen.
Lassen Sie nicht zu, dass ein breites JSON-Objekt diese Unterschiede löscht.
📊 Kernvergleich
| üben | Können Sie den Dokumenttyp klären? | Verhalten bei Überlappung von Zweigen | Umgang mit unbekannten Typen |
|---|---|---|---|
| Ein breites Objekt, bei dem alle Felder optional sind | Es ist schwer zu erklären, was ich erhalten habe. | Nicht anwendbar, keine Zweiggrenzen zwischen Feldern | Wird von einer Vielzahl von Objekten leicht verschluckt und ist schwer zu erkennen |
| Zwei unabhängige Verträge + erforderliche Art | Explizite Auswahl über Art-Feld | Verwenden Sie const, um den Wert festzulegen und Überlappungen zu reduzieren | Behalten Sie den unbekannten Status bei und geben Sie die zu klassifizierende Warteschlange ein |
🎯 Welche Methode ist für Dich geeignet?
Wenn Sie sowohl Rechnungen als auch Quittungen erhalten müssen
Behalten Sie zwei separate Verträge bei und machen Sie kind zu einem Pflichtfeld.
Wenn sich Ihre Zweigfelder stark überschneiden
Korrigieren Sie kind mit const in jedem Zweig, um zu verhindern, dass zulässige Eingaben gleichzeitig mit mehreren Zweigen übereinstimmen.
Wenn Ihr System zusätzliche Felder zulässt
Klären Sie zunächst den Namensraum der zusätzlichen Felder und entscheiden Sie dann, wie die Einschränkungen gelockert werden.
Wenn Ihr Klassifikator nicht sicher genug ist
Lassen Sie den Status unbekannt, senden Sie das Dokument zur Sortierung in die Warteschlange und wählen Sie nicht zwangsweise einen Zweig aus.
❓ Häufig gestellte Fragen (FAQ)
1. Warum nicht einfach ein Objekt verwenden, bei dem alle Felder optional sind?
Ein solches Objekt kann alles enthalten, aber es ist schwierig zu sagen, was genau es erhält.
2. Warum scheitert oneOf an der zulässigen Eingabe?
oneOf erfordert die Übereinstimmung mit genau einem Zweig. Wenn beide Zweige gleichzeitig bestehen, schlägt die Gesamtüberprüfung fehl. Diese Situation kann leicht auftreten, wenn sich Zweigfelder stark überschneiden.
3. Was ist beim Zulassen zusätzlicher Felder zu beachten?
Der Namespace zusätzlicher Felder sollte explizit gemacht werden, anstatt alle Einschränkungen stillschweigend aufzuheben.
4. Was soll ich tun, wenn der Klassifikator den Dokumenttyp nicht ermitteln kann?
Behalten Sie den unbekannten Status bei und geben Sie eine unabhängige Warteschlange zur Klassifizierung ein. Wählen Sie nicht zufällig einen Zweig aus, um Erfolg zu haben.
5. Wenn die Strukturüberprüfung erfolgreich ist, bedeutet das, dass das Dokument authentisch ist?
kann nicht. Klassifizierungsvertrauen, Strukturverifizierung und Geschäftsauthentizität sind drei verschiedene Ebenen. Das Bestehen der Struktur kann nicht beweisen, dass das Dokument authentisch ist.
📝 Zusammenfassung
Wenn Sie Rechnungen und Quittungen im selben Eintrag platzieren, behalten Sie zwei separate Verträge bei und wählen Sie diese mit dem erforderlichen kind-Feld aus, damit die Art des eingegebenen Dokuments deutlich sichtbar ist. Verzweigungsüberprüfung, Fehlerrückmeldung und Exits unbekannter Art sollten ebenfalls gemeinsam entworfen werden.
