ik bouw Toolz.dev, en daarvoor heb ik jaren besteed aan het verzenden van WordPress plugins en Laravel API's In al het, de enkele foutmelding die ik heb verspild de meeste uren op is een variatie van & quot; Onverwacht token in JSON op positie 428.& quot; Het vertelt je bijna niets Er is geen regel, geen kolom, en de positie die het noemt is vaak een paar tekens voorbij het ding dat verkeerd is Je uiteindelijk tellen tekens in een geminificeerde blob met de hand, of plakken van de hele payload in een editor en squinting Ik heb de JSON Validator dus dat hoef ik nooit meer te doen, en dit is de gids voor wat het doet en waarom het valideren van JSON lastiger is dan het lijkt.
tl;dr: Een JSON-validator controleert tekst aan de hand van de grammatica in RFC 8259 en vertelt u, wanneer de tekst is verbroken, de exacte regel, kolom en karakter van de eerste fout, geformuleerd in termen van wat hij verwachtte. Het vangt ook dingen op die een normale parser verbergt: dubbele sleutels, die stil worden ingeklapt tot de laatste waarde, en het rapporteert de structuur van een geldig document (object, array en sleuteltellingen, nestdiepte en bytegrootte). Het is geen opmaakster. Een opmaakster gaat ervan uit dat de invoer al geldig is; een validator is het ding waar u precies naar reikt als dat niet het geval is.
Wat betekent het voor JSON om geldig te zijn?
JSON is een klein formaat met een strikte grammatica De huidige standaard is RFC 8259, wat aansluit bij ECMA-404, en tussen hen definiëren ze precies wat een geldig document mag bevatten Een JSON tekst is een enkele waarde Die waarde is een object, een array, een string, een getal, true, false, of null. Objecten worden in beugels gewikkeld en met komma's gescheiden gehouden "key": value paren Arrays worden tussen haakjes gewikkeld en houden komma-gescheiden waarden vast Strings zijn verpakt in dubbele aanhalingstekens, nooit enkele aanhalingstekens Getallen volgen een specifieke vorm zonder voorloopnullen en zonder achterliggende decimalen Er zijn geen opmerkingen en er zijn geen achterliggende komma's.
Die laatste zin is waar de meeste real-world JSON fout gaat, omdat veel van de JSON mensen die met de hand schrijven niet echt JSON is Het is een config bestand met // opmerkingen, of een object gekopieerd uit de JavaScript-bron waar enkele aanhalingstekens en achterste komma's prima zijn, of een met de hand bewerkt armatuur waarbij iemand een veld heeft toegevoegd en een bungelende komma heeft achtergelaten. Deze worden allemaal afgewezen door een strikte parser, en een validator & # 39; Het is de taak om ze op een specifieke plek af te wijzen in plaats van met een schouderophaaldienst.
Eén punt dat de moeite waard is om op te helderen, omdat het mensen struikelt die JSON jaren geleden hebben geleerd: een naakte waarde is een compleet, geldig JSON-document. 42 op zichzelf is geldig JSON. Dat is zo "hello", en zo ook true. Het oude RFC 4627 vereiste dat het hoogste niveau een object of een array was, maar die beperking werd in 2014 geschrapt toen RFC 7159 (later 8259) het verving Als een tool het je vertelt 42 is geen geldige JSON, die tool volgt een specificatie die al meer dan tien jaar verouderd is.
Waarom is JSON.parse zo'n slechte foutreporter?
De reden dat een speciale validator zijn plaats verdient, is dat de parser die in uw taal is ingebouwd, is geoptimaliseerd voor het gelukkige pad, niet voor het uitleggen van het trieste pad. JSON.parse in een browser gooit een SyntaxError wiens bericht motorspecifiek is en je meestal een tekenoffset geeft zonder regel of kolom. V8 zegt "Onverwacht token } in JSON op positie 148." Firefox zegt "JSON.parse: onverwacht teken op regel 1 kolom 149." Safari zegt weer iets anders Geen van hen vertelt je wat ze hadden verwacht, en de positie wordt gemeten vanaf het begin van de string, wat nutteloos is op het moment dat je JSON meer dan een paar regels heeft.
De validator op Toolz.dev gebruikt niet JSON.parse. Het loopt de tekst zelf met een handgeschreven recursieve-afdaling parser, het volgen van de lijn en kolom zoals het gaat, dus wanneer het stopt kan het u alle drie coördinaten: de lijn, de kolom, en de absolute teken offset, nog belangrijker, het kent de grammaticaregel het was in het midden van, dus het bericht is specifiek In plaats van & quot;onverwacht token, & quot; u krijgt & quot; Het volgen van komma is niet toegestaan vóór de sluitbeugel, & quot; of & quot;Object sleutels moeten dubbel geciteerde strings, & quot; of & quot; Verwacht een jacht komma of een sluitseconde na een bestandquot het fixeren is vijf.
Het tekent ook een caret onder het exacte teken op de gewraakte regel, zoals een compiler dat doet Wanneer u naar regel 34 van een config-bestand kijkt, zal "column 12" prima zijn, maar een ^ direct onder de verdwaalde quote zitten gaat sneller.
Welke JSON fouten vangt de validator op naam?
Dit zijn de mislukkingen die ik het vaakst zie, zowel in mijn eigen werk als in de ondersteuningsthreads voor tools als deze. De validator noemt ze allemaal in plaats van een algemene tokenfout te rapporteren.
| Fout | Hoe het eruit ziet | Waarom het ongeldig is |
|---|---|---|
| Achterliggende komma | {"a": 1,} of [1, 2,] |
JSON heeft geen achterliggende komma's; de standaard & # 39; De grammatica staat er eenvoudigweg geen toe vóór een sluitbeugel of beugel |
| Enkele citaten | {'name': 'Liton'} |
Tekenreeksen en sleutels moeten dubbele aanhalingstekens gebruiken; enkele aanhalingstekens zijn een JavaScript-gewoonte, niet JSON |
| Ontbrekende komma | {"a": 1 "b": 2} |
Elk lid na de eerste moet worden voorafgegaan door een komma |
| nadere beschouwing | {"a": 1} // note |
JSON heeft geen commentaar syntaxis; de // en alles erna is onverwachte inhoud |
| Niet-geciteerde sleutel | {name: "Liton"} |
Sleutels zijn tekenreeksen en moeten worden geciteerd, in tegenstelling tot JavaScript-objectletterlijke waarden |
| Leading zero | {"n": 007} |
Een getal heeft mogelijk geen voorloopnul, dus 007 is ongeldig; schrijven 7 |
| Achterliggende decimaal | {"n": 5.} |
De breuk na een decimaal heeft minimaal één cijfer nodig |
| Ruw controlekarakter | een letterlijk tabblad of nieuwe regel in een tekenreeks | Bedieningstekens binnen tekenreeksen moeten worden ontsnapt als \t, \n, enzovoort |
| NaN of Infinity | {"n": NaN} |
Deze zijn geldig in JavaScript maar zijn geen JSON-waarden |
| Niet-beëindigde tekenreeks | {"a": "oops} |
Een string zonder slotcitaat loopt tot het einde van de invoer |
Elk van deze levert een bericht in platte taal en een positie op. Het geval dat voor nul staat, is een mooi voorbeeld van waarom een speciaal gebouwde parser helpt: een generieke parser leest 007 als het nummer 0 en dan struikelt over de 7 als "extra inhoud," u wijzend op de 7, wanneer het echte probleem de twee nullen ervoor zijn De validator controleert eerst op het leidende-nulpatroon en vertelt je dat direct.
Hoe zit het met dubbele sleutels?
Hier is degene die mij meer heeft gebeten in de productie dan welke syntaxisfout dan ook, omdat het helemaal geen syntaxisfout is Dit is geldig JSON:
{
"timeout": 30,
"retries": 3,
"timeout": 60
}
RFC 8259 zegt de namen binnen een object & quot; MOET uniek zijn, & quot; maar het verbiedt geen duplicaten, dus een parser moet dit accepteren. Wat vervolgens gebeurt, is waar het probleem begint: de standaard zegt dat het gedrag met dubbele namen onvoorspelbaar is, en in de praktijk behoudt bijna elke parser de laatste waarde en verwijdert in stilte de eerdere. Dus dit object parseert naar {"timeout": 60, "retries": 3}, en de "timeout": 30 u zorgvuldig ingesteld aan de bovenkant van het bestand is verdwenen zonder een waarschuwing Als twee mensen de configuratie hebben bewerkt, of een samenvoeging is misgegaan, of een sjabloonstap heeft dezelfde sleutel twee keer uitgezonden, hebt u een bug die geen enkele parser ooit voor u zal markeren.
De validator markeert het. Duplicate-key detectie is standaard aan, en omdat een duplicaat legaal is, wordt het gerapporteerd als een waarschuwing in plaats van als een fout: het document is nog steeds geldig, maar u krijgt te horen dat elke sleutel meer dan één keer in hetzelfde object verschijnt, met zijn lijn en een JSON-aanwijzer pad zodat je het in een geneste structuur kunt vinden. Als je echt duplicaten wilt, kun je de controle uitschakelen. Meestal is het zien van de waarschuwing het moment waarop je beseft wat er mis is gegaan.
Hoe verschilt een validator van een formatter?
Mensen gebruiken de woorden door elkaar, en de hulpmiddelen overlappen elkaar, maar ze beantwoorden verschillende vragen. A JSON-formatter neemt JSON die u al gelooft is geldig en herdrukt het opnieuw met consistente inspringing, zodat een mens het kan lezen Als u een formatter gebroken JSON overhandigt, het beste kan het weigeren Een validator' s hele doel is de gebroken geval: het vertelt u waar en waarom De Toolz.dev validator doet beide taken, want zodra het heeft bevestigd een document is geldig heeft het al geparseerd, dus het mooi-print het resultaat in dezelfde pas Maar de kopfunctie is de diagnose, niet de inspringing.
Dezelfde relatie geldt voor de aangrenzende tools. De JSON-minifier stript witruimte om een payload te verkleinen, wat alleen zinvol is bij geldige invoer De JSON-sorteerder herordent sleutels voor stabiele diffs, opnieuw op geldige invoer De JSON ontsnappen en ontsnappen tool gaat over het inbedden van JSON in een string. En de JSONPath-tester queries een document dat u al hebt bevestigd is goed gevormd Validatie is de stap die voor hen allemaal komt, daarom is het degene die ik als eerste uitvoeren wanneer een API-antwoord of een config-bestand zich vreemd gedraagt Er is een bredere tour van hoe deze in elkaar passen in de Ultieme gids voor JSON-tools.
Wat vertellen de structuurstatistieken je?
Wanneer een document valideert, rapporteert de tool zijn vorm: hoeveel objecten en arrays het bevat, hoeveel sleutels, hoeveel tekenreeksen, getallen, booleans en nulls, hoe diep het nestelt en de grootte ervan in zowel tekens als UTF-8-bytes. Dit is geen decoratie. Wanneer u een onbekend API-antwoord krijgt, vertelt het dieptenummer u in één oogopslag of u te maken heeft met een plat record of een diep geneste boom, en het aantal sleutels vertelt u ongeveer hoeveel werk het parseren ervan zal zijn.
Het bytecijfer doet er meer toe dan mensen verwachten. De limieten voor de aanvraaggrootte, de limieten voor de berichtwachtrij en de limieten voor de databasekolom worden bijna altijd gemeten in bytes, niet in tekens, en de twee verschillen op het moment dat uw JSON iets buiten ASCII bevat. Een emoji of een naam met accenten is één teken op het scherm, maar twee, drie of vier bytes op de draad. Als een payload tegen een limiet van 256 KB botst, zal het aantal tekens u misleiden en het aantal bytes niet. De validator berekent de werkelijke UTF-8-byte lengte, dus het getal dat u ziet is het getal dat de limiet telt.
Hoe ik het gebruik
Mijn workflow is saai en snel, dat is het punt Wanneer een integratie breekt, kopieer ik de onbewerkte responslichaam direct uit het netwerktabblad en plak het in de validator Als het geldig is, het groene resultaat en de statistieken vertellen me dat het probleem ergens anders is, in mijn code in plaats van hun gegevens, en ik heb een hele klasse oorzaken in twee seconden uitgesloten Als het ongeldig is, krijg ik de regel en kolom, repareer het en ga verder Als ik een config-bestand met de hand aan het bewerken ben, plak ik het in voordat ik me engageer, meestal om de achterliggende komma op te vangen, het lijkt altijd achter te laten en af en toe een dubbele sleutel uit een kopieerplak. Voor iedereen die zijn eigen kit in elkaar zet, zit de validator de andere Webontwikkelaar Toolkit.
De privacyhoek is ook geen bijzaak De JSON mensen die het meest moeten valideren is precies de JSON waar ze het meest voorzichtig mee moeten zijn: API-reacties die tokens dragen, configuratiebestanden met inloggegevens, payloads met klantgegevens Alles wat de validator doet gebeurt in uw browser, in JavaScript, op uw machine Niets wordt geüpload, gelogd of opgeslagen U kunt het bewijzen door het netwerktabblad te openen terwijl u valideert, of door de verbinding met internet te verbreken en te kijken hoe de tool blijft werken.
Veelgestelde vragen
Waarom zegt mijn JSON dat het ongeldig is als het er goed uitziet?
De meest voorkomende redenen zijn een achterliggende komma voor een afsluitende beugel of haakje, enkele aanhalingstekens waarbij JSON dubbele aanhalingstekens vereist, een ontbrekende komma tussen twee leden, of een opmerking, die JSON helemaal niet toestaat Alle vier zijn gemakkelijk met het oog te missen, vooral in een groot bestand De validator noemt welke het heeft gevonden en geeft je de exacte regel en kolom, dus in plaats van het hele document te scannen, spring je meteen naar het teken waarop het is gestopt.
Is een enkel getal of string op zichzelf geldig JSON?
Ja. onder RFC 8259 is elke JSON-waarde een volledige JSON-tekst, dus 42, "hello", true, en null valideren allemaal op zichzelf De regel dat het bovenste niveau een object of een array moest zijn kwam van de oudere RFC 4627 en werd in 2014 verwijderd Een tool die een kale waarde afwijst volgt een verouderde specificatie.
Verandert of uploadt de validator mijn gegevens?
Nee. Het parseert de tekst in uw browser en verzendt deze nooit ergens. Op een geldig document produceert het voor het gemak een mooi afgedrukte kopie, maar die kopie wordt lokaal gegenereerd en het origineel wordt nooit verzonden, geregistreerd of opgeslagen. Omdat er geen retourvlucht met de server is, werkt de tool ook met het netwerk dat is verbroken zodra de pagina is geladen.
Waarom zou ik me druk maken om dubbele sleutels als de JSON nog steeds geldig is?
Omdat een duplicaat bijna altijd dataverlies betekent dat je niet van plan was De standaard staat dubbele sleutels toe maar laat hun behandeling ongedefinieerd, en in de praktijk houden parsers alleen de laatste waarde en laten de rest vallen Dus een config waar timeout verschijnt twee keer stilletjes verliest de eerste instelling De validator waarschuwt u voor elke herhaalde sleutel met zijn positie, wat meestal het moment is waarop u een slechte samenvoeging of een copy-paste fout ziet.
Kan dit JSON valideren met opmerkingen, zoals een tsconfig- of VS Code-instellingenbestand?
Nee, en dat is bewust Die bestanden zijn JSON met Comments (JSONC) of JSON5, dat zijn aparte formaten die de regels versoepelen De validator richt zich op strikte RFC 8259, dus het zal een opmerking markeren als een fout Als u opmerkingen nodig hebt in een config-bestand, dat is een signaal het formaat moet iets gebouwd voor het, zoals YAML of TOML, in plaats van JSON uitgerekt voorbij wat de standaard toelaat.
Wat is het verschil tussen het valideren en formatteren van JSON?
Valideren controleert of de tekst voldoet aan de JSON grammatica en, als dat niet het geval is, vertelt u precies waar deze breekt Formatteren gaat ervan uit dat de tekst al geldig is en past alleen de witruimte aan voor leesbaarheid Je grijpt naar een validator als er iets mis is en je moet weten wat; je grijpt naar een formatter als alles in orde is en je wilt gewoon dat het leesbaar is Dit hulpmiddel doet beide, maar de bestaansreden is de diagnose.
Hoe groot kan ik een bestand valideren?
Comfortabel in de tientallen megabytes, alleen beperkt door uw browser' s geheugen, omdat het hele document in één keer op uw apparaat wordt geparseerd Er is geen uploadgroottelimiet omdat er geen upload is Voor een echt enorm bestand, in de gigabytes, is een streaming-opdrachtregelvalidator het betere instrument, aangezien de browser de volledige tekst in één keer in het geheugen bevat.
