Com diagnosticar errors JSON pas a pas

JSON sembla simple perquè té pocs tipus de dades i una puntuació coneguda. Justament per això un error mínim arriba sovint a l'eina com un missatge poc clar: una coma inesperada, una posició o un “token no vàlid”. L'objectiu no és provar canvis fins que el document deixi de fallar. Cal reduir el cas, localitzar la posició indicada, fer una correcció compatible amb la gramàtica i confirmar que les dades conserven el mateix significat.

RFC 8259 defineix JSON com un format d'intercanvi basat en objectes, arrays, nombres, cadenes, booleans i null. Els noms d'un objecte són cadenes entre cometes dobles. Una cadena no pot contenir un salt de línia literal. Les comes separen valors; no tanquen una llista amb un separador extra. Aquestes regles estrictes permeten que programes diferents interpretin el mateix document.

Un parser comprova sintaxi, no intenció. Pot indicar on ha deixat d'entendre el text, però no sap si dos camps amb noms diferents són el mateix import, si un identificador ha perdut zeros inicials o si una data té la zona horària correcta. Separa l'error que impedeix llegir JSON d'un problema semàntic que continuarà existint després de formatar-lo.

Un exemple reproduïble complet

Comença amb una còpia petita sense secrets reals. Aquesta càrrega combina quatre problemes habituals. L'ordre és important: el parser normalment informa del primer obstacle i amaga els altres fins que el primer es corregeix.

{
  "customer": "Ada",
  "items": ["notebook", "pen",],
  "note": "Deliver before
Friday",
  'orderId': "007",
  "total": 24.90,
  "amount": 24.90
}

La coma després de "pen" és final. El salt entre before i Friday és dins d'una cadena sense escapar. orderId usa cometes simples, acceptables en alguns contextos de JavaScript però no en JSON. Finalment, total i amount són sintàcticament vàlids, encara que podrien descriure la mateixa quantitat. Aquesta última pregunta requereix conèixer el contracte de l'API.

Llegir una posició del parser

Els errors de JSON.parse() poden mencionar una posició, una línia o una columna segons el motor i el navegador. Compta des de l'inici de l'entrada exacta, incloent espais i salts. No suposis que la posició és la causa: sovint assenyala el caràcter on la gramàtica ja no pot continuar. Una coma final pot aparèixer a ]; una cadena sense escapar pot aparèixer al salt de línia.

Utilitza un editor que mostri línies i columnes. Copia el text sense transformar cometes i evita aplicacions que hi afegeixin espais. Si una eina mostra una posició absoluta, observa vint caràcters abans i després. Si mostra una línia, revisa també l'anterior: un delimitador s'obre sovint abans que aparegui el símptoma.

El problema pràctic és diferenciar una càrrega il·legible d'una càrrega vàlida però incorrecta per al negoci. Un formatejador només actua quan la gramàtica és correcta. Si el document prové d'un log, una variable d'entorn o una resposta HTTP, conserva primer l'original i anota quin sistema l'ha produït. No substitueixis valors a cegues: eliminar un error pot alterar una signatura, una suma o un identificador. Redueix la mostra al bloc que reprodueix la fallada i elimina dades personals abans de compartir-la.

Diagnostica l'exemple en quatre passades. Primer, ves a items: la coma just abans de ] no separa cap valor i s'ha d'eliminar. Segon, localitza la línia de note; JSON representa el salt amb barra invertida i n, no amb un salt físic. Tercer, canvia les cometes simples de la clau per cometes dobles. Quart, pregunta al productor si total i amount són conceptes diferents. Si són el mateix import, conserva el nom establert i documenta la migració.

{
  "customer": "Ada",
  "items": ["notebook", "pen"],
  "note": "Deliver before\nFriday",
  "orderId": "007",
  "total": 24.90
}

El JSON corregit s'analitza, manté orderId com a cadena per preservar els zeros i codifica el salt de manera portable. No converteixis "007" en nombre només perquè ho sembla: els codis i les referències no són quantitats.

Executa primer el parser en l'entorn que ha fallat, quan sigui possible. Anota el missatge i la posició abans de reescriure text. Valida una còpia amb un formatejador; si el missatge canvia, comprova si l'entrada s'ha normalitzat. Corregeix un sol error sintàctic, torna a analitzar i repeteix. Quan el resultat sigui vàlid, compara claus, tipus, longituds i valors significatius amb una mostra coneguda. Per a una API, compara també amb l'esquema o contracte. Un esquema pot exigir camps, però no decideix sol quin import és correcte.

En automatitzacions, captura el missatge i el context proper, no tota una càrrega sensible. En JavaScript, envolta JSON.parse() amb tractament d'excepcions i retorna un diagnòstic sense tokens. En una integració, conserva l'identificador de sol·licitud, la versió del contracte i una mostra anonimitzada. Això fa el problema reproduïble sense convertir logs de depuració en una divulgació.

Cometes dobles, barres invertides i comes són sintaxi, no estil opcional. Dins d'una cadena, \n representa un salt, \" una cometa i \\ una barra. Una cadena oberta pot fer que el parser culpi un caràcter posterior. Igualment, una clau o un claudàtor absent pot informar-se al final, quan ja és segur que no ha arribat el tancament.

Les claus duplicades exactes són especialment arriscades: molts parsers conserven l'última, mentre RFC 8259 adverteix que el comportament amb noms no únics és imprevisible entre implementacions. Els duplicats semàntics com total i amount són més difícils: tots dos poden sobreviure i crear dues interpretacions. Defineix un nom canònic, rebutja la combinació ambigua al productor i afegeix una prova de migració.

Evita eines de “reparació” que converteixin text semblant a JavaScript en JSON sense explicar canvis. Afegir cometes, eliminar comes o convertir valors pot ocultar una incompatibilitat del productor. Tampoc facis servir expressions regulars per validar JSON complet: les cadenes escapades i l'anidament fan aquest mètode fràgil. El parser és l'autoritat de sintaxi; les proves de contracte i l'esquema cobreixen la resta.

Un altre error és confondre JSON vàlid amb una resposta correcta. {"enabled":"false"} és vàlid, però el tipus pot haver de ser booleà. 9007199254740993 pot perdre precisió en convertir-se en número JavaScript. 03/04/2026 no explica el seu ordre. Comprova tipus, unitat, zona horària, rang i regles de negoci abans de lliurar el valor a una altra capa.

Usa dades sintètiques per aprendre el flux i confirma on processa el contingut l'eina abans d'enganxar informació interna. Per a una càrrega gran, divideix la investigació: valida capçalera, un element de l'array i l'estructura final. No tallis enmig d'una cadena o d'una seqüència UTF-8. Conserva UTF-8 i evita processadors de text que substitueixin cometes rectes per tipogràfiques.

Els missatges canvien entre navegadors i versions. Una posició només és reproduïble amb l'entrada idèntica. Inclou versió del client, missatge literal, fragment sanejat i passos de reproducció en un informe. No publiquis una càrrega completa com a exemple si conté correus, rutes internes, sessions o comptes.

Aquesta guia no certifica que una càrrega sigui segura, autoritzada o apta per a una decisió professional. JSON no xifra, no signa ni valida permisos. Un document ben format pot incloure instruccions malicioses, dades antigues o xifres manipulades. La validació sintàctica no substitueix autenticació, autorització, límits de mida, logs segurs ni revisió humana quan el context ho requereix.

Les eines de navegador poden ajudar a inspeccionar text, però no han de ser l'únic control d'una integració crítica. Per a pagaments, salut, seguretat, deures legals o dades regulades, segueix el contracte, els procediments i els entorns aprovats per l'organització responsable. Si no saps què significa un camp duplicat, atura la importació i consulta el propietari de les dades.

Abans de considerar resolt un error JSON, guarda una còpia protegida i crea un exemple mínim sense secrets. Llegeix el primer missatge del parser i situa la posició en l'entrada exacta. Repara una regla cada vegada: comes, cometes, escapaments i tancaments. Analitza de nou després de cada canvi. Quan passi, compara claus, tipus, identificadors, nombres, dates i camps equivalents amb el contracte. Confirma que no hi ha noms duplicats ni significats solapats. Finalment, prova el consumidor real amb dades controlades, registra la causa i corregeix el productor perquè no emeti mai més el mateix document.