Strumenti per sviluppatori · JSON formattatore e validatore
Valido JSON vs valido rispetto a uno schema: due significati di "valido"
· Sfondo
json standard convalida
Un validatore che dice che il tuo JSON è valido significa solo che lo analizza. Questo post spiega i livelli di validità (sintassi, struttura, semantica) e perché esiste JSON Schema per tutto ciò che va oltre la grammatica.
Valido e ancora rifiutato
Una richiesta può essere impeccabile JSON e tuttavia essere inaccettabile per un API. `{"username":"nori","plan":"gold"}` ha delimitatori bilanciati, nomi tra virgolette e valori legali, tuttavia un servizio potrebbe richiedere un'e-mail, rifiutare il nome del piano o vietare la creazione di un account nello stato corrente. Il parser e l'applicazione rispondono a domande diverse, quindi entrambi i risultati possono essere corretti.
ToolAcre risponde solo alla prima domanda: questo testo può essere analizzato come rigoroso JSON entro i suoi limiti di input? Non carica uno schema, non controlla le proprietà richieste, non verifica i formati, non contatta un database né valuta le regole aziendali. Quando lo strumento dice Valido, leggilo come "sintassi JSON ben formata", non come approvazione da parte del sistema che utilizzerà il valore.
Livello uno: sintassi ben formata
La convalida della sintassi controlla la grammatica JSON: un valore di primo livello, contenitori correttamente accoppiati, nomi di oggetti tra virgolette, virgole e due punti validi, stringhe legali, numeri legali e valori letterali esatti. Rifiuta `NaN` e `Infinity`, commenti, virgole finali e stringhe con virgolette singole. Accetta qualsiasi forma grammaticalmente valida, incluso un numero solitario o un oggetto con campi non familiari.
L'origine dal formato non valido presenta un punto di errore testuale, quindi ToolAcre può segnalare una riga e una colonna per il primo carattere impossibile. Una virgola mancante può far sì che venga riportata la citazione successiva; una virgola finale può far sì che venga riportato il delimitatore di chiusura. La correzione della sintassi crea un valore analizzabile ma non stabilisce che il valore abbia la forma o il significato previsto da un altro programma.
Livello due: la forma
La convalida della forma chiede se il valore analizzato corrisponde a un contratto dichiarato. Uno schema utente potrebbe richiedere `email`, vincolare `age` a un numero intero pari almeno a 18, limitare `tier` a `free` o `pro` e non consentire proprietà sconosciute. `{"email":false,"tier":"gold"}` è una sintassi JSON valida ma non rispetta tali regole strutturali perché i tipi di valore e le scelte consentite sono errate.
Lo schema JSON è un modo per esprimere tali vincoli, ma ToolAcre non lo esegue. Un validatore di schema solitamente riporta un percorso di istanza come `/tier`, una parola chiave come `enum` e un messaggio esplicativo anziché un accento parser. Mantieni la versione dello schema e il contratto API accanto al payload durante la diagnosi di questo livello; la modifica della punteggiatura non riparerà un valore analizzato correttamente della forma sbagliata.
Livello tre: significato
Il significato dipende da fatti e regole che vanno oltre la forma statica del documento. Un `accountId` può avere lo schema di stringa corretto senza nominare alcun account. Una data di inizio può corrispondere a un formato in stile ISO pur cadendo dopo la data di fine. Una quantità può essere positiva ma superare lo stock corrente. Questi errori richiedono il contesto dell'applicazione, lo stato memorizzato o le relazioni tra i campi.
Alcuni vincoli semantici possono essere approssimati in uno schema, ma molti appartengono alla logica del servizio in cui sono disponibili dati autorevoli e stato della transazione. Le risposte agli errori a questo livello dovrebbero identificare il campo o la regola pertinente senza fingere che il testo JSON fosse formato in modo errato. ToolAcre non può riprodurre tali decisioni perché non conosce il contratto né invia l'input all'applicazione proprietaria della regola aziendale.
Esempio realizzato: un carico utile attraverso tre controlli
Inizia con `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre lo accetta: tutti i nomi e i valori seguono la grammatica JSON. Uno schema può quindi richiedere un oggetto, una stringa non vuota SKU, una quantità intera positiva e uno dei codici di magazzino documentati. Supponiamo che anche questo carico utile superi questi vincoli. Nessuno dei due controlli ha confermato che SKU A-19 esista o che il nord contenga tre unità.
Il servizio di inventario esegue il terzo controllo rispetto ai record correnti e può rifiutare la richiesta in quanto non disponibile. La modifica del rientro non può alterare tale risultato. Se `quantity` fosse scritto come `03`, la sintassi fallirebbe prima; se fosse `"3"`, l'analisi passerebbe ma il controllo del tipo di schema fallirebbe; con il numerico `3`, rimane solo la regola del bestiame vivo. Lo stesso campo può quindi fallire a tre livelli distinti per tre ragioni distinte.
A cui appartiene ogni assegno
Esegui la convalida della sintassi il prima possibile durante la modifica, poiché i controlli successivi non possono funzionare in modo affidabile su testo che non viene analizzato. Applicare la forma dichiarata al limite di ogni applicazione non attendibile anziché dare per scontato che un client lo abbia già fatto. Valutare le invarianti aziendali nel componente che possiede lo stato richiesto, soprattutto quando la risposta può cambiare tra una richiesta e l'altra.
I controlli lato client migliorano il feedback ma non sostituiscono l'applicazione lato server. Al contrario, una risposta del server che dice "non valido JSON" dovrebbe essere riservata per l'analisi non riuscita anziché utilizzata per ogni richiesta rifiutata. Una chiara separazione produce utili diagnostici: riga e colonna per la sintassi, percorsi di istanza per vincoli strutturali e codici o messaggi specifici del dominio per conflitti semantici. ToolAcre fornisce solo la prima categoria.
Ciò che questo non copre
Questo formattatore non crea né valuta lo schema JSON, non seleziona una bozza di schema, non risolve i riferimenti allo schema, inserisce valori predefiniti o forza stringhe in numeri. Inoltre, non riconosce il documento OpenAPI di API o le convenzioni di convalida personalizzate. Fornire uno schema insieme all'input non modificherebbe il risultato di ToolAcre perché in questo strumento non è presente alcun passaggio di elaborazione dello schema.
Inoltre, la convalida della sintassi non rileva qui nomi di oggetti duplicati; `JSON.parse` mantiene l'ultima occorrenza prima della formattazione. Né garantisce precisione numerica, byte canonici, resa sicura o autorizzazione. Ognuna di queste preoccupazioni necessita di un proprio contratto e di una propria attuazione. Evita di comprimerli in un unico badge verde “valido”, perché così facendo si nasconde quali prove sono state raccolte e quali domande non sono mai state poste.
Conclusione: "valido" necessita di un qualificatore
Qualificare ogni richiesta di convalida. "Valido JSON" significa che il testo segue la grammatica. "Valido rispetto a questo schema" significa che il valore analizzato soddisfa un contratto strutturale denominato. “Accettato dal servizio” significa che le attuali regole applicative consentono l'operazione. Il passaggio di un livello è necessario per quello successivo in molti flussi di lavoro, ma non è mai una prova che tutti i livelli successivi siano passati.
Utilizza ToolAcre per formattare e controllare la sintassi rigorosa, incluso il rifiuto di valori letterali nonJSON come `NaN` e `Infinity`. Quindi utilizzare lo schema e l'applicazione che governano effettivamente il carico utile. Quando una richiesta continua a fallire, leggi l'errore al suo livello invece di riformattare ripetutamente il JSON corretto. Lo strumento non prevede controlli dello schema e quel confine esplicito è più utile di una promessa di validità troppo ampia.