Faktúry a účtenky zdieľajú rovnaký vchod. Ako sa vyhnúť zmiešaniu týchto dvoch štruktúr?
Jedno rozhranie akceptuje faktúry aj potvrdenky a je ľahké písať veľké objekty so „všetky polia voliteľné“. Takýto predmet môže držať čokoľvek, ale je ťažké povedať, čo presne je prijaté. Jasnejšie by bolo ponechať dve samostatné zmluvy a vybrať jednu z nich s poľom explicitného typu.
Faktúry a potvrdenky sa často vkladajú do rovnakého rozhrania na spracovanie, ale ak sa na ich príjem použije iba široký objekt s „všetky polia voliteľné", môže sa prispôsobiť ľubovoľnému vstupu, ale nedokáže povedať, aký druh dokumentu sa prijíma. Tento článok je určený pre vývojárov a obchodný personál, ktorí potrebujú navrhnúť rozhranie na príjem dokumentov alebo udržiavať pravidlá overovania schémy JSON. Po prečítaní tohto článku sa naučíte, ako zachovať dve nezávislé zmluvy, vybrať jednu s poľom explicitného typu a ako riešiť konflikty medzi vetvami a neznáme typy.
Príklady v tomto článku používajú syntetické vzorky na demonštráciu metód spracovania. Kód bol skontrolovaný pomocou príkladov v izolovanom prostredí, ale to nie je zárukou všetkých skutočných súborov alebo výkonu produktu. Pred spracovaním dôležitých dokumentov si uschovajte originály a skontrolujte ich podľa hraníc a akceptačných položiek v texte.
Ako sa vysporiadať so spoločným vstupom faktúr a účteniek? Záver jednou vetou
Pri prijímaní dvoch dokumentov z toho istého portálu je jasnejšie ponechať si dve samostatné zmluvy a použiť požadované polekind na výber jednej z nich, namiesto použitia širokého objektu, ktorý pojme všetko.
| vaša situácia | Odporúčané postupy | dôvod |
|---|---|---|
| Rovnaké rozhranie potrebuje prijímať faktúry a potvrdenky | Ponechajte si dve samostatné zmluvy vybraté s požadovaným poľom druhu | Veľký objekt so všetkými voliteľnými poľami môže obsahovať čokoľvek, ale je ťažké vysvetliť, čo sa prijíma. |
| Organizujte pobočky s oneOf | Každá vetva používa const na opravu druhu | oneOf vyžaduje, aby bola priradená práve jedna vetva. Prekrývajúce sa polia vetvy spôsobia zlyhanie právneho vstupu. |
| Chýbajúci typ vstupu alebo konflikt poľa | Vráti jasnú chybovú správu zobrazujúcu konfliktné polia a zdroje | Iba zobrazenie „žiadna zhoda"nemôže pomôcť nájsť problém |
| Klasifikátor nedokáže rozlíšiť medzi typmi dokumentov | Zachovajte neznámy stav a vstúpte do nezávislého frontu na klasifikáciu | Náhodný výber pobočky prinesie iba falošný „úspech" |
| Overenie štruktúry bolo úspešné | Neznamená to, že klasifikácia je správna, ani to, že dokumenty sú autentické. | Spoľahlivosť klasifikácie, overenie štruktúry a obchodná autenticita sú tri rôzne úrovne |
Prečo nemôžete použiť široký objekt?
Riziko, že všetky polia budú nepovinné
Keď rozhranie akceptuje faktúry aj potvrdenky, je ľahké písať veľké objekty so „všetky polia voliteľné". Takýto objekt môže skutočne prijímať rôzne vstupy, ale za cenu:
- Zo štruktúry nie je možné zistiť, ktorý dokument bol prijatý.
- Požadované položky a voliteľné položky týchto dvoch dokumentov sa navzájom miešajú a pravidlá overovania sú čoraz nejasnejšie.
- Keď sa vyskytne chyba, je ťažké presne vysvetliť, kde vstup nie je podľa očakávania.
Jasnejšie by bolo ponechať dve samostatné zmluvy a vybrať jednu z nich s explicitným typovým poľom.
oneOf nie je len tak hocijaký
Prekrývajúce sa vetvy môžu spôsobiť platné zlyhania vstupov
oneOf vyžaduje, aby vstup zodpovedal presne jednej vetve. Ak obe vetvy prejdú súčasne, celková validácia tiež zlyhá.
Ak vetva obsahuje len niekoľko voliteľných polí, pravdepodobne sa budú výrazne prekrývať. V tomto bode legitímny vstup v skutočnosti neprejde overením.
Používajte druh a konštant, aby ste odstránili prekrytie
Použitím požadovaného poľa kind plus const na stanovenie hodnôt môžete jasne vyznačiť hranice medzi vetvami a takéto prekryvy vopred eliminovať.
Pre viac informácií o pravidlách kombinácií pozri Pravidlá kombinácie schémy JSON.
Spustiteľný odklonový protokol
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"})
Toto je zjednodušený ukážkový záznam, nie kompletný terénny model skutočnej faktúry. Kód demonštruje výber vetiev a odmietanie redundantných polí; daňové sadzby, hlavičky a sumy musia byť definované samostatne.
Ak firma povolí ďalšie polia, menné priestory pre tieto polia by mali byť jasne definované, namiesto tichého odstraňovania všetkých obmedzení.
Nezobrazujte len chybové hlásenia "nezhoda"
Zobrazuje sa iba "nezhoda" a ani používatelia, ani údržbári nevedia, kde je problém. Tabuľka nižšie uvádza niekoľko bežných vstupných prvkov a ich zodpovedajúce metódy spätnej väzby:
| Vstupné funkcie | Skutočné pochybnosti | Navrhnite spätnú väzbu |
|---|---|---|
| druh nedostatku | Nemôžem si vybrať dohodu | Prosím, uveďte typ dokumentu |
| Konflikt typových a číselných polí | Tieto dve štruktúry sú zmiešané | Zobraziť konfliktné polia a ich zdroje |
| Očíslované prázdne reťazce | Kľúč existuje, ale nemá žiadnu hodnotu | Pohľad späť na očíslovanú oblasť |
| Neznámy typ | Súčasná dohoda to nepokrýva | Zadajte nezávislú frontu na klasifikáciu |
Neisté typy tiež potrebujú únik
Ak klasifikátor nedokáže rozlíšiť medzi faktúrami a účtenkami, neznámy stav by sa mal ponechať namiesto náhodného výberu vetvy na dosiahnutie "úspechu".
Tu sú tri rôzne úrovne, ktoré je potrebné posudzovať samostatne:
- Dôvera v kategóriu: Ako sebavedomý je systém pri hodnotení typov dokumentov.
- Overenie štruktúry: Zadať, či je vybraná zmluva splnená.
- Obchodná autenticita: Či sú samotné dokumenty pravé a platné.
Štrukturálne overenie nemožno spätne dokázať, že je správne, ani nemôže dokázať, že dokument je pravý.
Typ dokumentu by mal byť zachovaný aj v procese prekladu
Tá istá oblasť môže vyžadovať odlišnú terminológiu v rôznych dokumentoch. Pri používaní terminológie OmniDoc a bilingválnych hodnotiacich pracovných postupov pomáha poskytovanie typov dokumentov zoznamov dodaní recenzentom pochopiť kontext počtu a množstva.
Nedovoľte, aby široký objekt JSON vymazal tieto rozdiely.
📊 Porovnanie jadra
| Metóda | Dá sa presne definovať typ dokumentu? | Prejavy, keď sa vetvy prekrývajú | Manipulácia s neznámymi typmi |
|---|---|---|---|
| Široké objekty, pričom všetky polia sú voliteľné | Ťažko sa vysvetľuje, čo bolo prijaté | Nepoužiteľné; medzi poľami neexistujú hranice vetiev | Ľahko prehltnuté širokými terčmi a ťažko si ich všimnúť |
| Dve nezávislé zmluvy + povinný druh | Jasne vyberte pomocou poľa typu | Použi const na fixáciu hodnôt a zníženie prekryvu | Nechajte neznámy stav a vstúpte do fronty na zoradenie |
🎯 Ktorá metóda ti vyhovuje?
Ak potrebujete dostať faktúry aj účtenky naraz
Držte si dve samostatné zmluvy a nastavte kind ako povinné pole.
Ak sa vaše vetvové polia výrazne prekrývajú
Opravte kind s const v každej vetve, aby sa predišlo legitímnemu zhodovaniu viacerých vetiev súčasne.
Ak váš systém umožňuje ďalšie polia
Najprv objasniť menný priestor ďalšieho poľa a potom rozhodnúť, ako obmedzenia uvoľniť.
Ak tvoj klasifikátor nie je dostatočne istý
Nechajte neznámy stav a posielajte dokumenty do fronty na triedenie; nenásilne vyberajte vetvy.
❓ Často kladené otázky (FAQ)
1. Prečo jednoducho nepoužiť objekt, kde sú všetky polia voliteľné?
Takýto partner dokáže predstierať čokoľvek, no je ťažké presne povedať, čo dostáva.
2. Prečo oneOf spôsobuje platné zlyhanie vstupu?
oneOf vyžaduje presné zladenie vetvy. Ak obe vetvy prejdú súčasne, celková kontrola zlyhá. Táto situácia je pravdepodobná, keď sa vetvy výrazne prekrývajú.
3. Na čo by ste si mali dať pozor, keď povolujete ďalšie polia?
Menný priestor pre dodatočné pole by mal byť jasne definovaný, namiesto tichého odstraňovania všetkých obmedzení.
4. Čo ak klasifikátor nedokáže určiť typ dokumentu?
Zachovávajte neznámy stav a vstupujte do nezávislej fronty na klasifikáciu; nevyberajte náhodne vetvu na zostavenie úspešnej vetvy.
5. Dokazuje prechod štrukturálnym overením pravosť dokumentov?
Nie. Istota v klasifikácii, štrukturálna verifikácia a obchodná autenticita sú tri odlišné úrovne; štrukturálna verifikácia nemôže dokázať pravosť dokumentov.
📝 Zhrnutie
Pri vkladaní faktúr a dokladov do jedného záznamu uchovávajte dve samostatné zmluvy a vyberte ich pomocou požadovaného poľa kind, aby bol typ zadaného dokumentu jasne viditeľný. Overovanie vetiev, chybová spätná väzba a exporty neznámych typov by mali byť tiež navrhnuté spoločne.


