Računi i potvrde imaju isti ulaz. Kako izbjeći miješanje dviju struktura?

Jedno sučelje prihvaća i fakture i potvrde, a lako je pisati velike objekte sa "sva polja izborno". Takav predmet može držati bilo što, ali je teško reći što je točno primljeno. Bilo bi jasnije zadržati dva odvojena ugovora i odabrati jedan od njih s eksplicitnim poljem tipa.

Fakture i potvrde često se stavljaju u isto sučelje za obradu, ali ako se za primanje koristi samo široki objekt sa "sva polja opcionalna", može primiti bilo koji unos, ali ne može reći koja je vrsta dokumenta primljena. Ovaj je članak namijenjen programerima i poslovnom osoblju koji trebaju dizajnirati sučelje za primanje dokumenata ili održavati pravila provjere valjanosti JSON sheme. Nakon što ovo pročitate, naučit ćete kako zadržati dva nezavisna ugovora, odabrati jedan s eksplicitnim poljem tipa i rukovati sukobima grana i nepoznatim tipovima.

Primjeri u ovom članku koriste sintetičke uzorke za demonstraciju metoda obrade. Kôd je provjeren s primjerima u izoliranom okruženju, ali to nije jamstvo svih stvarnih datoteka ili performansi proizvoda. Prije obrade važnih dokumenata, molimo vas da sačuvate izvornike i pregledate ih prema granicama i stavkama prihvaćanja u tekstu.

Kako se nositi sa zajedničkim unosom faktura i računa? Zaključak jedne rečenice

Kada primate dva dokumenta s istog portala, jasnije je držati dva odvojena ugovora i koristiti potrebno polje kind za odabir jednog od njih, umjesto korištenja širokog objekta koji može sadržavati sve.

vaša situacijaPreporučene prakserazlog
Isto sučelje treba primati fakture i potvrdeČuvajte dva odvojena ugovora, odabrana u polju potrebne vrsteVeliki objekt sa svim opcijskim poljima može držati bilo što, ali je teško objasniti što se prima.
Organizirajte grane s oneOfSvaka grana koristi const za popravljanje vrsteoneOf zahtijeva podudaranje točno jedne grane. Preklapanje polja grana uzrokovat će neuspjeh pravnog unosa.
Vrsta unosa nedostaje ili je polje u sukobuVrati jasnu poruku o pogrešci koja prikazuje proturječna polja i izvoreSamo prikazivanje "nema podudaranja" ne može pomoći u lociranju problema
Klasifikator ne može razlikovati vrste dokumenataZadržite nepoznati status i unesite neovisni red čekanja za klasificiranjeNasumični odabir grane samo će proizvesti lažni "uspjeh"
Provjera strukture prošlaTo ne znači da je klasifikacija ispravna, niti znači da su dokumenti autentični.Klasifikacijska pouzdanost, provjera strukture i poslovna autentičnost tri su različite razine

Zašto ne možete koristiti široki objekt?

Rizik da sva polja budu izborna

Kada sučelje prihvaća i fakture i potvrde, lako je pisati velike objekte sa "sva polja nisu obavezna". Takav objekt doista može primiti niz inputa, ali po cijenu:

  • Iz strukture se ne može razlučiti koji se dokument prima.
  • Obavezne stavke i izborne stavke dvaju dokumenata miješaju se jedna s drugom, a pravila provjere postaju sve nejasnija.
  • Kada se dogodi greška, teško je objasniti gdje točno unos nije očekivan.

Bilo bi jasnije zadržati dva odvojena ugovora i odabrati jedan od njih s eksplicitnim poljem tipa.

oneOf nije bilo koji

Grane koje se preklapaju uzrokovat će neuspjeh pravnog unosa.

oneOf zahtijeva da se unos podudara s točno jednom granom. Ako obje grane prođu u isto vrijeme, cjelokupna provjera neće uspjeti.

Ako grane sadrže samo nekoliko izbornih polja, vjerojatno će se značajno preklapati. U ovom trenutku pravni unos ne prolazi provjeru.

Koristite kind i const za uklanjanje preklapanja

Korištenje potrebnog polja kind plus fiksne vrijednosti const može uspostaviti jasne granice između grana i unaprijed eliminirati takva preklapanja.

Za više pojedinosti o pravilima kombinacije, pogledajte Pravila kombinacije JSON sheme.

Izvršni protokol preusmjeravanja

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

Ovo je pojednostavljeni primjer zapisa, a ne potpuni terenski model stvarne fakture. Kod demonstrira odabir grananja i odbacivanje redundantnih polja; porezne stope, zaglavlja i iznosi moraju biti definirani zasebno.

Ako poslovanje dopušta dodatna polja, imenski prostori za ta polja trebaju biti jasno definirani, a ne tiho uklanjati sva ograničenja.

Nemojte samo prikazivati poruke o pogrešci "nepodudarnosti"

Prikazuje se samo "nepodudaranje", a ni korisnici ni osoblje za održavanje ne mogu znati gdje je problem. Tablica u nastavku navodi nekoliko uobičajenih ulaznih značajki i njihove odgovarajuće metode povratne informacije:

Ulazne značajkeStvarne sumnjePredložite povratne informacije
vrsta nedostatkaNe mogu birati sporazumMolimo navedite vrstu dokumenta
Sukob tipova i brojevnih poljaDvije strukture su miješanePrikaz sukobljenih polja i njihovih izvora
Numerirani prazni nizoviKljuč postoji, ali nema vrijednostPogled unatrag na označeno područje
Nepoznat tipTrenutni sporazum to ne pokrivaUnesite neovisni red za klasifikaciju

Nesigurni tipovi također trebaju izlaz

Ako klasifikator ne može razlikovati račune od računa, nepoznati status treba zadržati umjesto nasumičnog odabira grane za "uspjeh".

Ovdje postoje tri različite razine koje treba razmatrati zasebno:

  • Povjerenje u kategoriju: Koliko je sustav siguran u procjenu tipova dokumenata.
  • Verifikacija strukture: Unesite je li odabrani ugovor ispunjen.
  • Poslovna autentičnost: Jesu li sami dokumenti autentični i valjani.

Strukturna verifikacija ne može se opovrgnuti kao ispravna, niti može dokazati autentičnost dokumenta.

Tip dokumenta također treba zadržati u procesu prevođenja

Isto područje može zahtijevati različitu terminologiju u različitim dokumentima. Kada se koristi terminologija OmniDoc i dvojezični tijek rada pregleda, pružanje tipova dokumenata s popisima isporuke pomaže recenzentima razumjeti kontekst broja i iznosa.

Nemojte dopustiti da široki JSON objekt izbriše te razlike.

📊 Usporedba jezgre

MetodaMože li se vrsta dokumenta jasno definirati?Manifestacije kada se grane preklapajuRukovanje nepoznatim tipovima
Široki objekti s opcionalnim svim poljimaTeško je objasniti što je zapravo primljenoNije primjenjivo; nema granica grana između poljaLako ih progutaju široke mete i teško ih je primijetiti
Dva neovisna ugovora + obavezna vrstaJasno odaberite koristeći polje za vrstuKoristi const za fiksiranje vrijednosti kako bi se smanjilo preklapanjeOstavite nepoznat status i uđite u red za sortiranje

🎯 Koja ti metoda najviše odgovara?

Ako trebate primiti i račune i račune istovremeno

Drži dva odvojena ugovora i postavi kind kao obavezno područje.

Ako se vaša grana polja jako preklapaju

Popravite kind s const u svakoj grani kako biste izbjegli legitimno podudaranje više grana istovremeno.

Ako vaš sustav dopušta dodatna polja

Prvo, razjasnite imenski prostor dodatnog polja, zatim odlučite kako opustiti ograničenja.

Ako tvoj klasifikator nije dovoljno siguran

Zadržite nepoznat status i šaljite dokumente u red za sortiranje; nemojte prisilno birati grane.

❓ Često postavljana pitanja (FAQ)

1. Zašto jednostavno ne koristiti objekt gdje su sva polja opcionalna?

Takav partner može glumiti bilo što, ali teško je reći što točno dobiva.

2. Zašto oneOf uzrokuje valjani neuspjeh unosa?

oneOf zahtijeva točno podudaranje grananja. Ako obje grane prođu istovremeno, ukupna provjera neće uspjeti. Ova situacija vjerojatno će se dogoditi kada se granasta polja u velikoj mjeri preklapaju.

3. Na što biste trebali obratiti pažnju prilikom dopuštanja dodatnih polja?

Prostor imena za dodatno polje treba biti jasno definiran, umjesto da se tiho uklanjaju sva ograničenja.

4. Što ako klasifikator ne može odrediti tip dokumenta?

Zadržite nepoznat status i unesite neovisni red za klasifikaciju; nemojte nasumično birati granu za sastavljanje uspješne grane.

5. Dokazuje li prolazak strukturne provjere autentičnost dokumenata?

Ne. Povjerljivost u klasifikaciji, strukturna verifikacija i poslovna autentičnost su tri različite razine; strukturna verifikacija ne može dokazati autentičnost dokumenata.

📝 Sažetak

Kada stavljate račune i račune u isti unos, zadržite dva odvojena ugovora i odaberite ih pomoću potrebnog polja kind, čineći vrstu unesenog dokumenta jasno vidljivom. Verifikacija grananja, povratne informacije o pogreškama i izvoz nepoznatog tipa također bi trebali biti dizajnirani zajedno.

Iskustvo sada: Učitajte svoj dokument kako biste započeli prijevod, zadržavajući izvorno formatiranje

Ažurirano 2026-11-16