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 situacija | Preporučene prakse | razlog |
|---|---|---|
| Isto sučelje treba primati fakture i potvrde | Čuvajte dva odvojena ugovora, odabrana u polju potrebne vrste | Veliki objekt sa svim opcijskim poljima može držati bilo što, ali je teško objasniti što se prima. |
| Organizirajte grane s oneOf | Svaka grana koristi const za popravljanje vrste | oneOf zahtijeva podudaranje točno jedne grane. Preklapanje polja grana uzrokovat će neuspjeh pravnog unosa. |
| Vrsta unosa nedostaje ili je polje u sukobu | Vrati jasnu poruku o pogrešci koja prikazuje proturječna polja i izvore | Samo prikazivanje "nema podudaranja" ne može pomoći u lociranju problema |
| Klasifikator ne može razlikovati vrste dokumenata | Zadržite nepoznati status i unesite neovisni red čekanja za klasificiranje | Nasumični odabir grane samo će proizvesti lažni "uspjeh" |
| Provjera strukture prošla | To 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čajke | Stvarne sumnje | Predložite povratne informacije |
|---|---|---|
| vrsta nedostatka | Ne mogu birati sporazum | Molimo navedite vrstu dokumenta |
| Sukob tipova i brojevnih polja | Dvije strukture su miješane | Prikaz sukobljenih polja i njihovih izvora |
| Numerirani prazni nizovi | Ključ postoji, ali nema vrijednost | Pogled unatrag na označeno područje |
| Nepoznat tip | Trenutni sporazum to ne pokriva | Unesite 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
| Metoda | Može li se vrsta dokumenta jasno definirati? | Manifestacije kada se grane preklapaju | Rukovanje nepoznatim tipovima |
|---|---|---|---|
| Široki objekti s opcionalnim svim poljima | Teško je objasniti što je zapravo primljeno | Nije primjenjivo; nema granica grana između polja | Lako ih progutaju široke mete i teško ih je primijetiti |
| Dva neovisna ugovora + obavezna vrsta | Jasno odaberite koristeći polje za vrstu | Koristi const za fiksiranje vrijednosti kako bi se smanjilo preklapanje | Ostavite 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.


