Facturen en bonnen delen dezelfde ingang. Hoe voorkom je dat de twee structuren met elkaar vermengd raken?

Facturen en ontvangstbewijzen worden vaak in dezelfde interface geplaatst voor verwerking, maar als alleen een breed object met "alle velden optioneel" wordt gebruikt om het te ontvangen, kan het elke invoer bevatten, maar kan het niet vertellen wat voor soort document wordt ontvangen. Dit artikel is bedoeld voor ontwikkelaars en zakelijk personeel dat een documentontvangstinterface moet ontwerpen of JSON-schemavalidatieregels moet onderhouden. Nadat u dit heeft gelezen, leert u hoe u twee onafhankelijke contracten kunt behouden, er één met een expliciet typeveld kunt selecteren en hoe u met branch-conflicten en onbekende typen kunt omgaan.

In de voorbeelden in dit artikel worden synthetische monsters gebruikt om verwerkingsmethoden te demonstreren. De code is gecontroleerd met voorbeelden in een geïsoleerde omgeving, maar dit is geen garantie voor alle echte bestanden of productprestaties. Voordat u belangrijke documenten verwerkt, dient u de originelen te bewaren en deze te controleren op basis van de grenzen en acceptatie-items in de tekst.

Hoe om te gaan met het gezamenlijk invoeren van facturen en bonnetjes? Conclusie in één zin

Wanneer u twee documenten van hetzelfde portaal ontvangt, is het duidelijker om twee afzonderlijke contracten te bewaren en het vereiste kind-veld te gebruiken om er één te selecteren, in plaats van een breed object te gebruiken dat alles kan bevatten.

Waarom kun je geen breed object gebruiken?

Risico dat alle velden optioneel worden gemaakt

Wanneer een interface zowel facturen als kwitanties accepteert, is het eenvoudig om grote objecten te schrijven met 'alle velden optioneel'. Zo'n object kan inderdaad verschillende inputs ontvangen, maar dit gaat ten koste van:

• Uit de structuur is niet op te maken welk document wordt ontvangen.
• De vereiste items en optionele items van de twee documenten worden met elkaar vermengd en de verificatieregels worden steeds vager.
• Wanneer er een fout optreedt, is het moeilijk uit te leggen waar de invoer precies niet is zoals verwacht.

Het zou duidelijker zijn om twee afzonderlijke contracten te behouden en er één te selecteren met een expliciet typeveld.

oneOf is niet zomaar iemand

Overlappende vertakkingen zullen ervoor zorgen dat juridische invoer mislukt.

oneOf vereist dat de invoer exact overeenkomt met één vertakking. Als beide vestigingen tegelijkertijd slagen, mislukt de algehele verificatie.

Als vertakkingen slechts enkele optionele velden bevatten, is de kans groot dat deze aanzienlijk overlappen. Op dit moment slaagt de juridische inbreng er niet in om de verificatie te doorstaan.

Gebruik vriendelijk en const om overlap te elimineren

Door het vereiste kind-veld plus de vaste waarde van const te gebruiken, kunnen duidelijke grenzen tussen vertakkingen worden vastgesteld en dergelijke overlappingen vooraf worden geëlimineerd.

Voor meer details over de combinatieregels, zie Combinatieregels voor JSON-schema.

Een uitvoerbaar offload-protocol

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"})

Dit is een vereenvoudigd voorbeeldrecord en geen volledig veldmodel van een echte factuur. De code demonstreert vertakkingsselectie en afwijzing van redundante velden. Het belastingtarief, de kop en het bedrag moeten afzonderlijk worden gedefinieerd.

Als het bedrijf extra velden toestaat, moeten de naamruimten voor deze velden expliciet worden gemaakt in plaats van alle beperkingen stilletjes op te heffen.

Geef niet alleen"geen overeenkomst"weer in het foutbericht

Er wordt alleen "mismatch" weergegeven en noch gebruikers, noch beheerders weten waar het probleem ligt. De volgende tabel bevat een aantal algemene invoerfuncties en bijbehorende feedbackmethoden:

Onbepaalde soorten hebben ook een uitlaatklep nodig

Als de classificator geen onderscheid kan maken tussen facturen en kwitanties, moet hij de onbekende status behouden in plaats van een willekeurige tak te kiezen om "succes" te raden.

Er zijn hier drie verschillende niveaus die afzonderlijk moeten worden bekeken:

• Classificatievertrouwen: hoe zeker is het systeem bij het beoordelen van het documenttype.
• Structuurverificatie: of de invoer voldoet aan het geselecteerde contract.
• Zakelijke authenticiteit: of het document zelf authentiek en geldig is.

Het slagen voor de structurele verificatie kan niet bewijzen dat de classificatie correct is, noch kan het bewijzen dat het document authentiek is.

Het documenttype moet ook behouden blijven tijdens het vertaalproces

In hetzelfde veld moeten mogelijk verschillende termen in verschillende documenten worden gebruikt. Bij gebruik van de terminologie en tweetalige beoordelingsworkflows van OmniDoc helpt het verstrekken van het documenttype samen met de leveringslijst reviewers de context van de cijfers en bedragen te begrijpen.

Laat een breed JSON-object deze verschillen niet uitwissen.

📊 Kernvergelijking

🎯 Welke methode is geschikt voor jou?

Als u zowel facturen als kwitanties wilt ontvangen

Houd twee afzonderlijke contracten aan en maak van kind een verplicht veld.

Als uw filiaalvelden elkaar veel overlappen

Repareer kind met const in elke vertakking om te voorkomen dat legale invoer tegelijkertijd met meerdere vertakkingen overeenkomt.

Als uw systeem extra velden toestaat

Verduidelijk eerst de naamruimte van de aanvullende velden en beslis vervolgens hoe u de beperkingen kunt versoepelen.

Als uw classificator niet voldoende vertrouwen heeft

Laat de status onbekend, stuur het document naar de wachtrij om te worden gesorteerd en selecteer niet met geweld een filiaal.

❓ Veelgestelde vragen (FAQ)

1. Waarom gebruik je niet gewoon een object waarbij alle velden optioneel zijn?

Zo'n object kan van alles bevatten, maar het is moeilijk te zeggen wat het precies wordt ontvangen.

2. Waarom faalt oneOf in juridische inbreng?

Voor oneOf is het matchen van precies één vertakking vereist. Als beide vestigingen tegelijkertijd slagen, mislukt de algehele verificatie. Deze situatie kan gemakkelijk optreden als de filiaalvelden elkaar veel overlappen.

3. Waar moet u op letten bij het toestaan van extra velden?

De naamruimte van aanvullende velden moet expliciet worden gemaakt in plaats van alle beperkingen stilzwijgend op te heffen.

4. Wat moet ik doen als de classificator het documenttype niet kan bepalen?

Behoud de onbekende status en ga naar een onafhankelijke wachtrij om te worden geclassificeerd. Selecteer niet willekeurig een tak om succes te behalen.

5. Als de structuurverificatie slaagt, betekent dit dan dat het document authentiek is?

kan niet. Classificatievertrouwen, structuurverificatie en zakelijke authenticiteit zijn drie verschillende niveaus. Het passeren van de structuur kan niet bewijzen dat het document authentiek is.

📝 Samenvatting

Wanneer u facturen en ontvangstbewijzen in dezelfde boeking plaatst, bewaar dan twee afzonderlijke contracten en selecteer deze met het vereiste veld kind, zodat het ingevoerde type document duidelijk zichtbaar is. Vertakkingsverificatie, foutfeedback en uitgangen van een onbekend type moeten ook samen worden ontworpen.

Probeer het nu: upload het document om de vertaling te starten, waarbij de oorspronkelijke lay-out behouden blijft