Acasă Adult66 Validarea datelor cu schema JSON, partea a 2-a

Adult66

Validarea datelor cu schema JSON, partea a 2-a

159

In prima parte a acestui tutorial, ai invatat cum sa creezi scheme destul de avansate folosind toate cuvintele cheie de validare disponibile. Multe exemple din datele JSON din lumea reala sunt mai complexe decat exemplul utilizatorului nostru. Incercarea de a pune toate cerintele la astfel de date intr-un singur fisier poate duce la o schema foarte mare, care poate avea si o multime de duplicari.

Structurarea schemelor

Standardul JSON-schema va permite sa impartiti schemele in mai multe parti. Sa ne uitam la exemplul de date pentru navigarea pe site-ul de stiri:

{“nivel”: 1, “parent_id”: nul, “vizitatori”: “tot”, “culoare”: “alb”, “pagini”: [{“page_id”: 1, “nume scurt”: “acasa”, ” display_name “:” Acasa “,” url “:” / home “,” navigare “: {” nivel “: 2,” parent_id “: 1,” culoare “:” albastru “,” pagini “: [{” page_id ” : 11, “short_name”: “titluri”, “display_name”: “Ultimele titluri”, “url”: “/ home / recent”, “navigare”: {“nivel”: 3, “parent_id”: 11, “culoare “:” alb “,” pagini “: [{” page_id “: 111,” nume scurt “:” last_all “,” display_name “:” Toate “,”url”: “/ home / recent”}, …]}}, {“page_id”: 12, “nume_ scurt”: “evenimente”, “afisare nume”: “Evenimente”, “url”: “/ home / evenimente” } ] } }, … ] }

Structura de navigare de mai sus este oarecum similara cu cea pe care o puteti vedea pe site-ul http://dailymail.co.uk. Puteti vedea un exemplu mai complet in depozitul GitHub.

Structura de date este complexa si recursiva, dar schemele care descriu aceste date sunt destul de simple:

navigation.json:

{“$ schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://mynet.com/schemas/navigation.json#”, “title”: “Navigare”, “definitii”: {“positiveIntOrNull”: {“type”: [“null”, “integer”], “minimum”: 1}}, “type”: “obiect”, “adicionalProperties”: false, “necesar”: [“nivel”, “parent_id”, “culoare”, “pagini”], “proprietati”: {“level”: {“$ ref”: “defs.json # / definitions / positiveInteger”}, ” parent_id “: {” $ ref “:” # / definitii / positiveIntOrNull “},” vizitatori “: {” enum “: [” tot “,” abonati “,” varsta18 “]},” culoare “:{“$ ref”: “defs.json # / definitions / color”}, “pages”: {“type”: “array”, “items”: {“$ ref”: “page.json #”}}} }

page.json:

{“$ schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://mynet.com/schemas/page.json#”, “title”: “Pagina”, “tip”: “obiect”, “additionProperties”: fals, “obligatoriu”: [“pagina_id”, “nume scurt”, “afisare nume”, “cale”], “proprietati”: {“pagina_id”: { “$ ref”: “defs.json # / definitions / positiveInteger”}, “short_name”: {“type”: “string”, “pattern”: “^ [a-z _] + $”}, “display_name”: {“type”: “string”, “minLength”: 1}, “path”: {“type”: “string”, “pattern”: “^ (?: / [a-z _ \ -] +) + $ “},” color “: {” $ ref “:” defs.json # / definitions / color “},” navigation “: {” $ ref “:” navigation.json # “}}}

defs.json:

{“$ schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://mynet.com/schemas/defs.json#”, “title”: “Definitii”, “definitii”: {“positiveInteger”: {“type”: “numar intreg”, “minim”: 1}, “color”: {“anyOf”: [{“enum”: [“rosu”, ” verde “,” albastru “,” alb “]}, {” type “:” sir “,” model “:” ^ # (?: (?: [0-9a-fA-F] {1,2}) ) {3} $ “}]}}}

Aruncati o privire la schemele de mai sus si la datele de navigare pe care le descriu (care sunt valabile in functie de schema de navigare.json). Principalul lucru de remarcat este faptul ca schema navigation.json face referire la schema page.json care la randul sau face referire la prima.

Codul JavaScript pentru validarea inregistrarii utilizatorului cu schema ar putea fi:

var Ajv = necesita (‘ajv’); var ajv = Ajv ({allErrors: true, scheme: [necesita (‘./ navigation.json’), necesita (‘./ page.json’), necesita (‘./ defs.json’)]}); var validate = ajv.getSchema (“http://mynet.com/schemas/navigation.json#”); var valid = validate (navigationData); if (! valid) console.log (validate.errors);

Toate probele de cod sunt disponibile in GitHub Repository.

Ajv, validatorul folosit in exemplu, este cel mai rapid validator JSON-Schema pentru JavaScript. L-am creat, asa ca il voi folosi in acest tutorial. Vom analiza in cele din urma cum se compara cu alti validatori, astfel incat sa puteti alege unul potrivit pentru dvs.

Sarcini

Consultati partea 1 a tutorialului pentru instructiuni despre instalarea depozitului cu sarcinile si pentru a va testa raspunsurile.

Referinte intre scheme cu cuvantul cheie „$ ref”

Standardul JSON-Schema va permite sa reutilizati partile repetate ale schemelor folosind referinte cu cuvantul cheie „$ ref”. Dupa cum vedeti din exemplul de navigare, puteti face referire la schema localizata:

intr-un alt fisier: utilizati schema URI care este definita in proprietatea „id”
in orice parte a unui alt fisier: adaugati indicatorul JSON la referinta schemei
in orice parte a schemei curente: adaugati indicatorul JSON la „#”

Va puteti referi, de asemenea, la intreaga schema curenta folosind „$ ref” egal cu „#” – va permite sa creati scheme recursive care se refera la ei insisi.

Deci, in exemplul nostru, schema din navigare.json se refera la:

pagina schemei.json
definitii in schema defs.json
definitia positiveIntOrNull in aceeasi schema

Schema din pagina.json se refera la:

inapoi la schema de navigare.json
de asemenea, la definitiile din fisierul defs.json

Standardul necesita ca „$ ref” sa fie singura proprietate in obiect, asa ca daca doriti sa aplicati o schema de referinta pe langa o alta schema, trebuie sa utilizati cuvantul cheie „allOf”.

Sarcina 1

Refactorizeaza schema utilizatorului din partea 1 a tutorialului folosind referinte. Separati schema in doua fisiere: user.json si connection.json.

Puneti schemele in fisierele part2 / task1 / user.json si part2 / task1 / connection.json si executati nodul part2 / task1 / validate pentru a verifica daca schemele dvs. sunt corecte.

JSON-Pointer

JSON-pointer este un standard care defineste caile catre partile fisierelor JSON. Standardul este descris in RFC6901.

Aceasta cale este formata din segmente (care pot fi orice sir) conectate cu caracterul „/”. Daca segmentul contine caractere „~” sau „/”, acestea trebuie inlocuite cu „~ 0” si „~ 1”. Fiecare segment inseamna proprietatea sau indexul din datele JSON.

Daca va uitati la exemplul de navigare, „$ ref” care defineste proprietatea culorii este „defs.json # / definitions / color”, unde „defs.json #” este schema URI si „/ definitii / culoare” este Indicatorul JSON. Indica culoarea proprietatii din interiorul definitiilor proprietatii.

Conventia este de a pune toate partile din schema care sunt utilizate in ref-uri in interiorul proprietatii definitiilor schemei (asa cum puteti vedea in exemplu). Desi standardul JSON-schema isi rezerva rezervarile de cuvinte cheie pentru definitii in acest scop, nu este necesar sa va adaugati subschemele acolo. JSON-pointer va permite sa faceti referire la orice parte a fisierului JSON.

Cand indicatoarele JSON sunt utilizate in URI, toate caracterele nevalide in URI ar trebui sa fie evadate (in JavaScript se poate utiliza functia globala cododeURIComponent).

Indicatorii JSON pot fi folositi nu numai in schemele JSON. Acestea pot fi utilizate pentru a reprezenta calea din datele JSON catre orice proprietate sau obiect. Puteti utiliza json-pointer-ul bibliotecii pentru a accesa obiecte cu indicatorii JSON.

Sarcina 2

Fisierul JSON de mai jos descrie structurile si folderele (numele folderului incep cu „/”):

{“/”: {“/ documents”: {“my_story ~ .rtf”: {“type”: “document”, “application”: [“Word”, “TextEdit”], “size”: 30476} ,. ..}, “/ system”: {“/ applications”: {“Word”: {“type”: “executabil”, “size”: 1725058307}, …}}}}

Care sunt indicatoarele JSON care indica:

dimensiunea aplicatiei „Word”,
dimensiunea documentului „my_story ~ .rtf”,
numele celei de-a doua aplicatii care poate deschide documentul „my_story ~ .rtf”?

Puneti raspunsurile in part2 / task2 / json_pointers.json si executati nodul part2 / task2 / validate pentru a le verifica.

Coduri de schema

Schemele au de obicei o proprietate „id” de nivel superior care are schema URI. Atunci cand „$ ref” este utilizat intr-o schema, valoarea acesteia este tratata ca un URI care este rezolvat relativ la „id”.

Rezolutia functioneaza in acelasi mod in care browserul rezolva URI-uri care nu sunt absolute – sunt rezolvate relativ la URI-ul schemei care se afla in proprietatea sa „id”. Daca „$ ref” este un nume de fisier, acesta inlocuieste numele de fisier din „id”. In exemplul de navigare, id-ul schemelor de navigare este “http://mynet.com/schemas/navigation.json#”, astfel ca, atunci cand se rezolva referinta “page.json #”, URI-ul complet al schemei de pagini devine “http: //mynet.com/schemas/page.json# “(adica„ id-ul “schemei page.json).

Daca „$ ref” din schema paginii ar fi o cale, de exemplu „/page.json”, atunci ar fi fost rezolvata ca „http://mynet.com/page.json#”. Si „/folder/page.json” ar fi fost rezolvata ca „http://mynet.com/folder/page.json#”.

Daca „$ ref” porneste de la caracterul „#”, acesta este tratat ca un fragment de hash si este atasat la calea din „id” (inlocuind fragmentul de hash din el). In exemplul de navigare, referinta „defs.json # / definitii / culoare” este rezolvata ca „http://mynet.com/schemas/defs.json#/definitions/color” unde „http://mynet.com/ schemas / defs.json # “este ID-ul schemei de definitii si” / definitii / culoare “este tratat ca un indicator JSON in interiorul sau.

Daca „$ ref” ar fi un URI complet cu un nume de domeniu diferit, in acelasi mod functioneaza legaturile in browser, ar fi fost rezolvat ca acelasi URI complet.

Coduri interne ale schemei

Standardul JSON-schema va permite sa folositi „id” in interiorul schemei pentru a identifica aceste subcheme si, de asemenea, pentru a schimba URI de baza in raport cu care se vor rezolva referintele interioare – se numeste „modificarea domeniului de rezolvare”. Aceasta este probabil una dintre cele mai confuze parti ale standardului si de aceea nu este foarte frecvent utilizata.

Nu as recomanda utilizarea excesiva a ID-urilor interne, cu o exceptie mai jos, din doua motive:

Foarte putini validatori respecta in mod constant standardul si rezolva corect referintele atunci cand sunt utilizate ID-uri interne (Ajv urmeaza complet standardul aici).
Schemele devin mai greu de inteles.

Vom analiza in continuare modul in care functioneaza, deoarece este posibil sa intalniti scheme care utilizeaza ID-uri interne si exista cazuri cand le utilizati ajuta la structurarea schemelor.

In primul rand, sa ne uitam la exemplul nostru de navigatie. Majoritatea referintelor sunt in definitia obiect si asta face ca referintele sa fie destul de lungi. Exista o modalitate de a le scurta adaugand ID-uri la definitii. Aceasta este schema actualizata defs.json:

{“$ schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://mynet.com/schemas/defs.json#”, “title”: “Definitii”, “definitii”: {“positiveInteger”: {“id”: “#positiveInteger”, “type”: “integer”, “minimum”: 1}, “color”: {“id”: “#color “,” anyOf “: [{” enum “: [” rosu “,” verde “,” albastru “,” alb “]}, {” type “:” sir “,” model “:” ^ # (?: (?: [0-9a-fA-F] {1,2})) {3} $ “}]}}}}

Acum, in loc de referinte „defs.json # / definitions / positiveInteger” si „defs.json # / definitions / color” care sunt utilizate in schemele de navigare si pagina, puteti utiliza referinte mai scurte: „defs.json # positiveInteger” si „defs # .json de culoare“. Aceasta este o utilizare foarte frecventa a ID-urilor interne, deoarece va permite sa faceti referintele mai scurte si mai lizibile. Va rugam sa retineti ca, desi acest caz simplu va fi tratat corect de majoritatea validatorilor schemei JSON, este posibil ca unii dintre ei sa nu-l accepte.

Sa ne uitam la un exemplu mai complex cu ID-uri. Iata schema exemplului JSON:

{“id”: “http: //xyz/rootschema.json#”, “definitii”: {“bar”: {“id”: “#bar”, “type”: “string”}}, “subschema” : {“id”: “http: //somewhere.else/completely.json#”, “definitii”: {“bar”: {“id”: “#bar”, “type”: “integer”}}, “type”: “obiect”, “Properties”: {“foo”: {“$ ref”: “#bar”}}}, “type”: “obiect”, “Properties”: {“bar”: {” $ ref “:” # / subschema “},” baz “: {” $ ref “:” # / subschema / properties / foo “},” bax “: {” $ ref “:” http: //somewhere.else /completely.json#bar “}}}

In foarte putine randuri, a devenit foarte confuz. Aruncati o privire la exemplul si incercati sa aflati ce proprietate ar trebui sa fie un sir si care este un numar intreg.

Schema defineste un obiect cu bara de proprietati, baz si bax. Bara de proprietati ar trebui sa fie un obiect valabil in conformitate cu subschema, care necesita ca proprietatea sa foo sa fie valabila in functie de referinta „bara”. Deoarece subschema are propriul „id”, URI-ul complet pentru referinta va fi „http: //somewhere.else/completely.json#bar”, deci ar trebui sa fie un numar intreg.

Acum uitati-va la proprietatile baz si bax. Referintele pentru ele sunt scrise intr-un mod diferit, dar indica aceeasi referinta „http: //somewhere.else/completely.json#bar” si ambele ar trebui sa fie intregi. Desi bazul proprietatii indica direct schema {“$ ref”: “#bar”}, ar trebui totusi rezolvat in raport cu ID-ul subschemei, deoarece se afla in interiorul acesteia. Deci, obiectul de mai jos este valid conform acestei scheme:

{“bar”: {“foo”: 1}, “baz”: 2, “bax”: 3}

Multi validatori de schema JSON nu o vor gestiona corect, si de aceea ID-urile care modifica sfera de rezolutie trebuie utilizate cu precautie.

Sarcina 3

Rezolvarea acestui puzzle va va ajuta sa intelegeti mai bine cum functioneaza referintele si modificarea domeniului de aplicare a rezolutiei. Schema dvs. este:

{“id”: “http: //xyz/rootschema.json#”, “title”: “Sarcina 3”, “description”: “Schema cu referinte – creati date valide”, “definitii”: {“my_data” : {“id”: “#my_data”, “type”: “integer”}}, “schema1”: {“id”: “#foo”, “allOf”: [{“$ ref”: “#my_data” }]}, “schema2”: {“id”: “otherschema.json”, “definitii”: {“my_data”: {“id”: “#my_data”, “type”: “sir”}}, “cuibarit “: {” id “:” #bar “,” allOf “: [{” $ ref “:” #my_data “}]},” alsonested “: {” id “:” t / inside.json # baz “, „definitii“: {“my_data”: {“id”: “#my_data”, “type”: “boolean”}}, “allOf”: [{“$ ref”: “#my_data”}]}}, “schema3”: {“id”: “http: //somewhere.else/completely#”, “definitii”: {“my_data”: {“id”: “#my_data”, “type”: “null”}}, “allOf” : [{“$ ref”: “#my_data”}]}, “type”: “obiect”, “proprietati”: {“foo”: {“$ ref”: “#foo”}, “bar”: { “$ ref”: “otherschema.json # bar”}, “baz”: {“$ ref”: “t / inside.json # baz”}, “bax”: {“$ ref”: “http: // undeva.else / complet # “},” quux “: {” $ ref “:”# / schema3 / allOf / 0 “}},” obligatoriu “: [” foo “,” bar “,” baz “,” bax “,” quux “]}

Creati un obiect care este valabil in conformitate cu aceasta schema.

Puneti raspunsul in part2 / task3 / valid_data.json si executati nodul part2 / task3 / validat pentru a-l verifica.

Se incarca schemele referite

Pana acum ne uitam la scheme diferite care se refera intre ele, fara sa acordam atentie modului in care sunt incarcate la validator.

O abordare este de a avea toate schemele conectate preincarcate precum am avut in exemplul de navigare de mai sus. Exista insa situatii cand nu este practic sau imposibil – de exemplu, daca schema pe care trebuie sa o utilizati este furnizata de o alta aplicatie sau daca nu cunoasteti in avans toate schemele posibile care pot fi necesare.

In astfel de cazuri, validatorul ar putea incarca schemele de referinta la momentul validarii datelor. Dar asta ar face procesul de validare lent. Ajv va permite sa compilati o schema intr-o functie de validare incarcand in mod asincron schemele de referinta lipsa din proces. Validarea in sine ar fi in continuare sincrona si rapida.

De exemplu, daca schemele de navigatie erau disponibile pentru a fi descarcate de la URI-urile din ID-urile lor, codul pentru validarea datelor din schema de navigare ar putea fi acesta:

Codul defineste functia validateNavigation care incarca schema si compileaza functia de validare atunci cand este apelata prima data si intoarce intotdeauna rezultatul validarii prin callback. Exista mai multe modalitati de imbunatatire a acesteia, de la preincarcare si compilare a schemei separat, inainte de a fi utilizata prima data, pana la contabilizarea faptului ca functia poate fi apelata de mai multe ori inainte de a reusi sa puna in cache schema (ajv.compileAsync deja asigura ca schema este intotdeauna solicitata o singura data).

Acum vom analiza noile cuvinte cheie propuse pentru versiunea 5 a schemei JSON standard.

JSON-Schema Versiunea 5 Propuneri

Desi aceste propuneri nu au fost finalizate ca un proiect standard, ele pot fi folosite astazi – validatorul Ajv le pune in aplicare. Ele extind substantial ceea ce puteti valida folosind schema JSON, asa ca merita sa le utilizati.

Pentru a utiliza toate aceste cuvinte cheie cu Ajv, trebuie sa utilizati optiunea v5: true.

Cuvinte cheie „constant” si „contine”

Aceste cuvinte cheie sunt adaugate pentru comoditate.

Cuvantul cheie „constant” necesita ca datele sa fie egale cu valoarea cuvantului cheie. Fara acest cuvant cheie, s-ar fi putut realiza cu ajutorul cuvantului cheie „enum” cu un element din tabloul de elemente.

Aceasta schema necesita ca datele sa fie egale cu 1:

{“constant”: 1}

Cuvantul cheie „contine” necesita ca un element de matrice sa se potriveasca cu schema din acest cuvant cheie. Acest cuvant cheie se aplica numai matricelor; orice alt tip de date va fi valabil in conformitate cu acesta. Este putin mai dificil sa exprimati aceasta cerinta folosind doar cuvinte cheie din versiunea 4, dar este posibil.

Aceasta schema necesita ca daca datele sunt un tablou, cel putin unul dintre elementele sale este intreg:

{“contine”: {“type”: “numar intreg”}}

Este echivalent cu acesta:

{“not”: {“type”: “array”, “items”: {“not”: {“type”: “numar intreg”}}}}

Pentru ca aceasta schema sa fie valabila, fie datele nu ar trebui sa fie un tablou sau nu ar trebui sa aiba toate elementele sale non-intregi (adica un element ar trebui sa fie intreg).

Va rugam sa retineti ca atat cuvantul cheie „contine”, cat si schema echivalenta de mai sus ar esua daca datele ar fi un tablou gol.

Cuvant cheie „patternGroups”

Acest cuvant cheie este propus ca inlocuitor pentru „patternProperties”. Va permite sa limitati numarul de proprietati care sa corespunda modelului care ar trebui sa existe in obiect. Ajv accepta atat „patternGroups”, cat si „patternProperties” in modul v5, deoarece prima este mult mai verosioasa, iar daca nu doriti sa limitati numarul de proprietati, puteti prefera sa o utilizati pe cea de-a doua.

De exemplu schema:

{“patternGroups”: {“^ [az] + $”: {“schema”: {“type”: “string”}}, “^ [0-9] + $”: {“schema”: {“type “: “numar” } } } }

este echivalent cu aceasta schema:

{“patternProperties”: {“^ [az] + $”: {“type”: “string”}, “^ [0-9] + $”: {“type”: “numar”}}}

Amandoi necesita ca obiectul sa aiba numai proprietati cu taste constand doar din litere mici cu valori de sir de tip si cu taste constand doar din numere cu valori de numar. Nu necesita niciun numar de astfel de proprietati si nici nu limiteaza numarul maxim. Asta puteti face cu „patternGroups”:

{“patternGroups”: {“^ [az] + $”: {“minimum”: 1, “maximum”: 3, “schema”: {“type”: “string”}}, “^ [0-9] + $ “: {” minimum “: 1,” schema “: {” type “:” numar “}}}}

Schema de mai sus are cerinte suplimentare: ar trebui sa existe cel putin o proprietate care sa corespunda fiecarui model si nu mai mult de trei proprietati ale caror taste contin doar litere.

Nu puteti obtine acelasi lucru cu „patternProperties”.

Cuvinte cheie pentru limitarea valorilor formatate „formatMaximum” / „formatMaximum”

Aceste cuvinte cheie, impreuna cu „exclusiveFormatMaximum” / „exclusiveFormatMinimum” va permit sa setati limite pentru timp, data si potential alte valori de sir care au formatul necesar cu cuvantul cheie „format”.

Aceasta schema necesita ca datele sa fie o data si sa fie mai mari sau egale cu 1 ianuarie 2016:

{“format”: “data”, “formatMinimum”: “2016-01-01”}

Ajv accepta compararea datelor formatate pentru formatele „data”, „ora” si „data-ora” si puteti defini formate personalizate care sa sustina limitele cu cuvintele cheie „formatMaximum” / „formatMaximum”.

Cuvant cheie „switch”

Desi toate cuvintele cheie anterioare va permiteau sa va exprimati mai bine ceea ce era posibil fara ele sau extindand usor posibilitatile, acestea nu au modificat natura declarativa si statica a schemei. Acest cuvant cheie va permite sa faceti validarea dinamica si dependenta de date. Contine mai multe cazuri daca.

Este mai usor de explicat cu un exemplu:

{“switch”: [{“if”: {“minimum”: 50}, “apoi”: {“multipleOf”: 5}}, {“if”: {“minimum”: 10}, “apoi”: { “multipleOf”: 2}}, {“if”: {“maximum”: 4}, “apoi”: false}]}

Schema de mai sus valideaza secvential datele cu subschemele din cuvintele cheie „daca” pana cand una dintre ele trece validarea. Cand se intampla acest lucru, valideaza schema din cuvantul cheie „atunci” din acelasi obiect – care va fi rezultatul validarii intregii scheme. Daca valoarea „atunci” este falsa, validarea esueaza imediat.

In acest fel, schema de mai sus necesita ca valoarea sa fie:

fie mai mare sau egal cu 50 si este un multiplu de 5
sau intre 10 si 49 si un multiplu de 2
sau intre 5 si 9

Acest set particular de cerinte poate fi exprimat fara un cuvant cheie de comutare, dar exista cazuri mai complexe cand nu este posibil.

Sarcina 4

Creati schema echivalenta cu ultimul exemplu de mai sus fara a utiliza un cuvant cheie switch.

Puneti raspunsul in part2 / task4 / no_switch_schema.json si executati nodul part2 / task4 / validat pentru a-l verifica.

Cazurile de cuvinte cheie „switch” pot contine, de asemenea, cuvantul cheie „continue” cu o valoare booleana. Daca aceasta valoare este adevarata, validarea va continua dupa o schema „if” de succes cu o validare a schemei „atunci” de succes. Aceasta este similara cu cea a cazului urmator intr-o instructiune de comutare JavaScript, desi in JavaScript fall-through este un comportament implicit, iar cuvantul cheie „switch” necesita o instructiune explicita „continue”. Acesta este un alt exemplu simplu cu o instructiune „continua”:

“schema”: {“switch”: [{“if”: {“minimum”: 10}, “apoi”: {“multipleOf”: 2}, “continue”: true}, {“if”: {“minimum “: 20},” apoi “: {” multipleOf “: 5}}]}

Daca prima conditie „daca” este satisfacuta si cerinta „atunci” este indeplinita, validarea va continua sa verifice a doua conditie.

Referinta „$ date”

Cuvantul cheie „date $” extinde si mai mult ceea ce este posibil cu schema JSON si face validarea mai dinamica si dependenta de date. Va permite sa introduceti valori din anumite proprietati, elemente sau chei de date in anumite cuvinte cheie de schema.

De exemplu, aceasta schema defineste un obiect cu doua proprietati in care, daca ambele sunt definite, „mai mare” ar trebui sa fie mai mare sau egal cu „mai mic” – valoarea in „mai mic” este utilizata ca minim pentru „mai mare”:

“schema”: {“properties”: {“menor”: {}, “large”: {“minimum”: {“$ data”: “1 / mai mic”}}}}

Ajv implementeaza referinta „$ date” pentru majoritatea cuvintelor cheie ale caror valori nu sunt scheme. Esueaza validarea daca referinta „$ $” indica un tip incorect si reuseste daca indica valoarea nedefinita (sau daca calea nu exista in obiect).

Deci, care este valoarea sirului in referinta „$ date”? Arata similar cu indicatorul JSON, dar nu este tocmai asta. Este un indicator JSON-relativ care este definit de acest proiect standard.

Este format dintr-un numar intreg care defineste de cate ori cautarea ar trebui sa traverseze obiectul (1 in exemplul de mai sus inseamna un parinte direct), urmata de indicatorul „#” sau JSON.

Daca numarul este urmat de „#” atunci valoarea JSON-pointer se rezolva a fi numele proprietatii sau indexul elementului pe care il are obiectul. In acest fel, „0 #” in locul „1 / mai mic” s-ar rezolva la sirul „mai mare”, iar „1 #” ar fi invalid, deoarece datele intregi nu sunt membre ale niciunui obiect sau tablou. Aceasta schema:

{“type”: “obiect”, “patternProperties”: {“^ date $ | ^ ora $”: {“format”: {“$ data”: “0 #”}}}}

este echivalent cu acesta:

{“type”: “obiect”, “Properties”: {“date”: {“format”: “data”}, “ora”: {“format”: “ora”}}}

deoarece {„$ data”: „0 #”} este inlocuit cu numele proprietatii.

Daca numarul din pointer este urmat de pointerul JSON, atunci acest pointer JSON este rezolvat pornind de la obiectul parinte la care se refera numarul. Puteti vedea cum functioneaza in primul exemplu „mai mic” / „mai mare”.

Sa ne uitam din nou la exemplul nostru de navigatie. Una dintre cerintele pe care le puteti vedea in date este ca proprietatea page_id din obiectul pagina este intotdeauna egala cu proprietatea parent_id din obiectul de navigare continut. Putem exprima aceasta cerinta in schema page.json folosind referinta „$ date”:

{“$ schema”: “http://json-schema.org/draft-04/schema#”, “id”: “http://mynet.com/schemas/page.json#”, … ” switch “: [{” if “: {” obligatoriu “: [” navigare “]},” apoi “: {” Properties “: {” page_id “: {” constant “: {” $ data “:” 1 / navigare / parent_id “}}}}}]}

Cuvantul cheie „switch” adaugat la schema paginii necesita ca, daca obiectul pagina are proprietatea de navigare, atunci valoarea proprietatii page_id ar trebui sa fie aceeasi cu valoarea proprietatii parent_id din obiectul de navigare. Acelasi lucru poate fi obtinut fara cuvantul cheie „switch”, dar este mai putin expresiv si contine duplicare:

{… “anyOf”: [{“not”: {“obligatoriu”: [“navigare”]}}, {“obligatoriu”: [“navigare”], “proprietati”: {“page_id”: {“constant “: {” $ data “:” 1 / navigation / parent_id “}}}}]]}

Sarcina 5

Exemple de indicatoare relativ JSON pot fi de ajutor.

Folosind cuvinte cheie v5, definiti schema pentru obiect cu doua liste de proprietati si ordine necesare. Lista ar trebui sa fie un tablou care are pana la cinci numere. Toate articolele ar trebui sa fie numere si ar trebui sa fie ordonate in ordine crescatoare sau descendenta, asa cum este stabilit de ordinea proprietatii care poate fi „asc” sau „desc”.

De exemplu, acesta este un obiect valid:

{“list”: [1, 3, 3, 6, 9], “ordine”: “asc”}

iar acest lucru nu este valabil:

{“list”: [9, 7, 3, 6, 2], “ordine”: “desc”}

Puneti raspunsul in part2 / task5 / schema.json si executati nodul part2 / task5 / validat pentru a-l verifica.

Cum ati crea o schema cu aceleasi conditii, dar pentru o lista de dimensiuni nelimitate?

Definirea noilor cuvinte cheie de validare

Am analizat noile cuvinte cheie propuse pentru versiunea 5 a standardului JSON-schema. Le puteti folosi astazi, dar uneori este posibil sa doriti mai multe. Daca ati facut sarcina 5, probabil ca ati observat ca unele cerinte sunt dificil de exprimat cu schema JSON.

Unele validatoare, inclusiv Ajv, va permit sa definiti cuvinte cheie personalizate. Cuvinte cheie personalizate:

va permit sa creati scenarii de validare care nu pot fi exprimate cu JSON-Schema
simplificati-va schemele
va ajuta sa aduceti o parte mai mare a logicii de validare in schemele dvs.
faceti schemele mai expresive, mai putin verbose si mai apropiate de domeniul dvs. de aplicatie

Unul dintre dezvoltatorii care foloseste Ajv a scris pe GitHub:

„Ajv cu cuvinte cheie personalizate ne-a ajutat foarte mult la validarea logicii de afaceri in backend. Am consolidat o multime de validari la nivel de controler in JSON-Schema cu cuvinte cheie personalizate. Efectul net este mult mai bun decat scrierea codului individual de validare. “

Problemele de care trebuie sa fiti constienti atunci cand extindeti standardul JSON-schema cu cuvinte cheie personalizate sunt portabilitatea si intelegerea schemelor dvs. Va trebui sa sustineti aceste cuvinte cheie personalizate pe alte platforme si sa va documentati corect aceste cuvinte cheie, astfel incat toata lumea sa le poata intelege in schemele dvs.

Cea mai buna abordare aici este definirea unei noi meta-schema care va fi extensia meta-schemei 4 meta-scheme sau „propuneri v5” care va include atat validarea cuvintelor dvs. cheie suplimentare, cat si descrierea acestora. Apoi, schemele dvs. care utilizeaza aceste cuvinte cheie personalizate vor trebui sa stabileasca proprietatea $ schema la URI a noii meta-schema.

Acum, dupa ce ati fost avertizat, va vom arunca in cuptor si vom defini cateva cuvinte cheie personalizate folosind Ajv.

Ajv ofera patru modalitati de a defini cuvinte cheie personalizate pe care le puteti vedea in documentatie. Vom analiza doua dintre ele:

folosind o functie care compila schema dvs. la o functie de validare
folosind o macro-functie care preia schema si returneaza o alta schema (cu sau fara cuvinte cheie personalizate)

Sa incepem cu exemplul simplu al unui cuvant cheie de gama. Un interval este pur si simplu o combinatie de cuvinte cheie minime si maxime, dar daca trebuie sa definiti mai multe intervale din schema dvs., mai ales daca au granite exclusive, poate deveni usor plictisitor.

Asa ar trebui sa arate schema:

{“range”: [5, 10], “exclusiveRange”: true}

unde gama exclusiva este optionala, desigur. Codul pentru a defini acest cuvant cheie este mai jos:

ajv.addKeyword (‘range’, {type: ‘number’, compile: compileRange}); ajv.addKeyword ( ‘exclusiveRange’); // acest lucru este necesar pentru a rezerva functia de cuvinte cheie compileRange (schema, parentSchema) {var min = schema [0]; var max = schema [1]; returneaza parentSchema.exclusiveRange === true? function (data) {return date> date min && <max; }: function (date) {return date> = min && data <= max; }}

Si asta e! Dupa acest cod, puteti utiliza cuvantul cheie pentru interval in schemele dvs.:

var schema = {“range”: [5, 10], “exclusiveRange”: true}; var validate = ajv.compile (schema); console.log (validate (5)); // false console.log (validare (5.1)); // true console.log (validare (9.9)); // true console.log (validare (10)); // fals

Obiectul trecut la addKeyword este o definitie a cuvantului cheie. Optional contine tipul (sau tipurile ca matrice) la care se aplica cuvantul cheie Functia de compilare se numeste cu parametri schema si parentSchema si ar trebui sa returneze o alta functie care valideaza datele. Acest lucru il face aproape la fel de eficient ca cuvintele cheie native, deoarece schema este analizata in timpul compilarii sale, dar exista costul unui apel functional suplimentar in timpul validarii.

Ajv va permite sa evitati aceasta suprapunere cu ajutorul unor cuvinte cheie care returneaza codul (ca sir) care va face parte din functia de validare, dar este destul de complex, asa ca nu o vom privi aici. Cea mai simpla metoda este de a utiliza cuvinte cheie macro – va trebui sa definiti o functie care preia schema si returneaza o alta schema.

Mai jos este implementarea cuvantului cheie interval cu o functie macro:

ajv.addKeyword (‘range’, {type: ‘number’, macro: macroRange}); function macroRange (schema, parentSchema) {var resultSchema = {“minimum”: schema [0], “maximum”: schema [1]}; if (parentSchema.exclusiveRange === true) {resultSchema.exclusiveMimimum = rezultatSchema.exclusiveMaximum = true; } returnare rezultatSchema; }

Puteti vedea ca functia returneaza pur si simplu noua schema care este echivalenta cu intervalul de cuvinte cheie care foloseste cuvinte cheie maxim si minim.

Sa vedem, de asemenea, cum putem crea o meta-schema care va include cuvantul cheie interval. Vom folosi proiectul 4 meta-schema ca punct de plecare:

{“id”: “http://mynet.com/schemas/meta-schema-with.range.json#”, “$ schema”: “http://json-schema.org/draft-04/schema# “,” allOf “: [{” $ ref “:” http://json-schema.org/draft-04/schema# “}, {” Properties “: {” range “: {” description “:” Primul itemul este minim, al 2-lea este maxim “,” type “:” array “,” items “: [{” type “:” numar “}, {” type “:” numar “}],” ExtraItems “: false}, “exclusiveRange”: {“type”: “boolean”, “default”: false}}, “dependences”: {“exclusiveRange”: [“range”]}}]}

Daca doriti sa utilizati referinte „$ date” cu cuvantul cheie pentru interval, va trebui sa extindeti meta-schema „propuneri v5” care este inclusa in Ajv (vezi linkul de mai sus), astfel incat aceste referinte sa poata fi valorile intervalului si exclusivitate . Si in timp ce prima noastra implementare nu va suporta referintele „date $”, cea de-a doua cu o macro-functie le va sustine.

Acum ca aveti o meta-schema, trebuie sa o adaugati la Ajv si sa o utilizati in scheme folosind cuvantul cheie din interval:

ajv.addMetaSchema (necesita ( ‘./ meta-schema-cu-range.json’)); var schema = {“$ schema”: “http://mynet.com/schemas/meta-schema-with-range.json#”, “range”: [5, 10], “exclusiveRange”: true}; var validate = ajv.compile (schema);

Codul de mai sus ar fi aruncat o exceptie daca valorile invalide ar fi fost trecute in interval sau in gama exclusiva.

Sarcina 6

Presupunem ca ati definit cuvantul cheie jsonPointers care aplica schemele proprietatilor profunde definite de indicatoarele JSON care indica date pornind de la cea curenta. Acest cuvant cheie este util cu cuvantul cheie de comutare, deoarece va permite sa definiti cerintele pentru proprietati si elemente profunde. De exemplu, aceasta schema folosind cuvantul cheie jsonPointers:

{“jsonPointers”: {“0 / books / 2 / title”: {“pattern”: “json | Json | JSON”},}}

este echivalent cu:

{“Properties”: {“books”: {“items”: [{}, {}, {“Properties”: {“title”: {“pattern”: “json | Json | JSON”}}}}}} }

Presupunem ca ati definit, de asemenea, cuvantul cheie necesarJsonPointers care functioneaza similar cu cel necesar, dar cu indicatorii JSON in loc de proprietati.

Daca doriti, puteti defini aceste cuvinte cheie si dvs. sau puteti vedea cum sunt definite in fisierul part2 / task6 / json_pointers.js.

Sarcina dvs. este: folosind cuvinte cheie jsonPointers si obligatoriiJsonPointers, definiti selectarea cuvintelor cheie care este similara cu instructiunea de comutare JavaScript si are sintaxa de mai jos (altfel si ulterior sunt optionale):

{“select”: {“selector”: “<pointer relativ JSON care porneste de la ‘0 /’>”, “cases”: [{“case”: <value1>, “schema”: {<schema1>}, “fallthrough”: true}, {“case”: <value2>, “schema”: {<schema2>}}, …], “altfel”: {<defaultSchema>}}}

Aceasta sintaxa permite valori de orice tip. Va rugam sa retineti ca fallthrough difera de continuarea cuvantului cheie switch. Fallthrough aplica schema de la urmatorul caz la date fara a verifica daca selectorul este egal cu valoarea din urmatorul caz (intrucat cel mai probabil nu este egal).

Puneti raspunsurile in part2 / task6 / select_keyword.js si part2 / task6 / v5-meta-with-select.json si executati nodul part2 / task6 / validate pentru a le verifica.

Bonus 1: imbunatatiti-va implementarea pentru a sustine si aceasta sintaxa:

{“select”: {“selector”: “<indicatorul JSON relativ care porneste de la ‘0 /’>”, “cases”: {“<value1>”: {<schema1>}, “<value2>”: { <schema2>}, …}, “altfel”: {<defaultSchema>}}}

Poate fi utilizat daca toate valorile sunt siruri diferite si nu exista nicio cadere.

Bonus 2: extinde meta-schema „propuneri v5” pentru a include acest cuvant cheie.

Alte utilizari ale schemei JSON

Pe langa validarea datelor, schemele JSON pot fi folosite pentru:

genereaza UI
genera date
modifica datele

Puteti consulta bibliotecile care genereaza interfata de utilizator si date daca sunteti interesat. Nu o vom explora, deoarece este in afara acestui obiectiv.

Vom analiza folosirea schemei JSON pentru a modifica datele in timp ce acestea sunt validate.

Filtrarea datelor

Una dintre sarcinile obisnuite in timpul validarii datelor este eliminarea proprietatilor suplimentare din date. Acest lucru va permite sa igienizati datele inainte de a le trece in logica de procesare, fara a esua validarea schemei:

Fara optiunea removeAdditional, validarea ar fi esuat, deoarece exista o bara de proprietate suplimentara care nu este permisa de schema. Cu aceasta optiune, validarea trece si proprietatea este eliminata din obiect.

Cand valoarea optiunii removeAdditional este adevarata, proprietatile suplimentare sunt eliminate numai daca cuvantul cheie adicionalProperties este fals. Ajv va permite, de asemenea, sa eliminati toate proprietatile suplimentare, indiferent de cuvantul cheie adicionalProperties sau proprietati suplimentare care nu reusesc validarea (daca cuvantul cheie suplimentarProperties este schema). Va rugam sa consultati documentatia Ajv pentru mai multe informatii.

Alocarea implicita la proprietati si elemente

Standardul JSON-schema defineste cuvantul cheie „implicit” care contine o valoare pe care ar trebui sa o aiba datele daca nu sunt definite in datele validate. Ajv va permite sa atribuiti astfel de valori implicite in procesul de validare:

Fara optiunea useDefaults, validarea ar fi esuat, deoarece nu exista o bara de proprietate necesara in obiectul validat. Cu aceasta optiune, validarea trece si proprietatea cu valoarea implicita este adaugata la obiect.

Coactionarea tipurilor de date

„Tip” este unul dintre cele mai utilizate cuvinte cheie in schemele JSON. Cand validati intrarile utilizatorilor, toate proprietatile dvs. de date pe care le obtineti din formulare sunt de obicei siruri. Ajv va permite sa constrangeti datele la tipurile specificate in schema, atat pentru a trece validarea, cat si pentru a utiliza datele corect tastate dupa aceea:

Compararea JavaScript validatorilor schema JSON

Exista mai mult de zece validatori JavaScript sustinuti activ. Care ar trebui sa folosesti?

Puteti vedea reperele de performanta si modul in care diferiti validatori trec suita de teste din standardul JSON-schema din proiectul json-schema-benchmark.

Exista, de asemenea, caracteristici distinctive pe care unii validatori le pot face sa fie cele mai potrivite pentru proiectul dvs. Voi compara unele dintre ele mai jos.

este-my-json-valid si jsen

Aceste doua validatoare sunt foarte rapide si au interfete foarte simple. Ambele compileaza scheme la functiile JavaScript, asa cum face Ajv.

Dezavantajul lor este ca amandoi au un suport limitat de referinte la distanta.

schemasaurus

Aceasta este o biblioteca unica, in care validarea schemei JSON este aproape un efect secundar.

Este construit ca un procesor / iterator JSON-schema generic si usor extensibil, pe care il puteti utiliza pentru a construi tot felul de instrumente care utilizeaza schema JSON: generatoare UI, sabloane etc.

Acesta are deja validator schema JSON relativ rapid inclus.

Nu accepta deloc referinte la distanta.

Themis

Cel mai lent din grupul de validatori rapide, are un set complet de functii, cu un suport limitat de referinte la distanta.

Unde straluceste cu adevarat este implementarea sa a cuvantului cheie implicit. In timp ce majoritatea validatorilor au un suport limitat pentru acest cuvant cheie (Ajv nu este o exceptie), Themis are o logica foarte complexa de aplicare a valorilor implicite cu retrageri in interiorul cuvintelor cheie compuse, cum ar fi anyOf.

z schema

In ceea ce priveste performanta, acest validator foarte matur se afla la granita dintre validatoarele rapide si lente. Probabil a fost unul dintre cele mai rapide inainte de aparitia noii rase de validatori compilate (toate cele de mai sus si Ajv).

Trece aproape toate testele din suita de teste JSON-schema pentru validatori si are o implementare destul de completa a referintelor la distanta.

Are un set mare de optiuni care va permit sa reglati comportamentul implicit al multor cuvinte cheie cu schema JSON (de exemplu, sa nu acceptati tablele goale ca tablouri sau seturi goale de siruri) si sa impuneti cerinte suplimentare pe schemele JSON (de ex., Necesitati cuvantul cheie minLength pentru corzi).

Cred ca, in majoritatea cazurilor, atat modificarea comportamentului schemelor, cat si solicitarea catre alte servicii din schema JSON sunt lucruri gresite de facut. Exista insa cazuri in care capacitatea de a face acest lucru simplifica foarte mult.

TV4

Acesta este unul dintre cele mai vechi (si mai lente) validatoare care accepta versiunea 4 a standardului. Ca atare, deseori este o alegere implicita pentru multe proiecte.

Daca il utilizati, este foarte important sa intelegeti modul in care raporteaza erorile si referintele lipsa si sa il configurati corect, in caz contrar veti primi multe pozitive false (adica, validarea trece cu date nevalide sau referinte la distanta nesolutionate).

Formatele nu sunt incluse in mod implicit, dar sunt disponibile ca o biblioteca separata.

Ajv

Am scris Ajv pentru ca toate validatoarele existente erau fie rapide, fie conforme cu standardul (in special in ceea ce priveste sprijinirea referintelor la distanta), dar nu ambele. Ajv a umplut acest gol.

Momentan este singurul validator care:

trece toate testele si accepta pe deplin referinte la distanta
accepta cuvinte cheie de validare propuse pentru versiunea 5 a standardului si referintele de date $
accepta validarea asincrona a formatelor si a cuvintelor cheie personalizate

Are optiuni de modificare a procesului de validare si de modificare a datelor validate (filtrare, atribuire de valori implicite si tipuri de constrangere – vezi exemplele de mai sus).

Ce validator sa folosesti?

Cred ca cea mai buna abordare este sa incercati mai multe si sa o alegeti pe cea care va functioneaza cel mai bine.

Am scris json-schema-consolidate, care furnizeaza o colectie de adaptoare care unifica interfetele celor 12 validatori de scheme JSON. Folosind acest instrument puteti petrece mai putin timp schimband intre validatoare. Iti recomand sa il scoti odata ce ai decis ce validator sa folosesti, deoarece pastrarea acestuia ar afecta negativ performanta.

Asta este! Sper ca acest tutorial a fost util. Ati aflat despre:

structurarea schemelor
folosind referinte si ID-uri
folosind cuvinte cheie de validare si referinta date $ din propunerile versiunii 5
incarcarea schemelor la distanta in mod asincron
definirea cuvintelor cheie personalizate
modificarea datelor in procesul de validare
avantajele si dezavantajele diferitelor validatoare de schema JSON

Multumesc pentru citit!