Le bug qui m'a fait construire cet outil était d'une taille exaspérante Je bourrais un modèle de courriel HTML - quelques centaines de lignes avec des citations, des sauts de ligne et un étrange backslash - dans un champ JSON pour envoyer à une API, et la requête revenait sans cesse sous la forme d'un 400. Le modèle allait bien Le JSON allait bien tout seul Mais au moment où les deux se sont rencontrés, un double guillemet non échappé de trois cents caractères fermait silencieusement la chaîne tôt, et tout après qu'elle se soit transformée en poubelle l'analyseur ne pouvait pas donner de sens J'avais collé du texte valide dans un conteneur valide et produit un document invalide.
C'est tout le problème que JSON échappe résout, et cela vaut la peine de comprendre plutôt que de travailler. Ce guide couvre ce que fait réellement l'évasion, quels personnages doivent être échappés et pourquoi, comment le désencombrement l'inverse et comment utiliser le gratuit Escape JSON / Déscape outil pour déplacer du texte arbitraire dans et hors des chaînes JSON sans un seul échec silencieux Il se trouve aux côtés des autres utilitaires de données sur lesquels j'ai écrit dans le Guide ultime des outils JSON.
tl;dr : Une chaîne JSON ne peut pas contenir de guillemet double brut, de barre oblique inverse brute ou de caractères de contrôle bruts comme les lignes neuves et les onglets L'échappement remplace chacun par une séquence barre oblique inverse -
"se transforme\", une nouvelle ligne devient\n, un onglet devient\tet tout ce qui se trouve en dessous de U+0020 devient\uXXXX. Une échappée transforme ces séquences en personnages originaux. Le Escape JSON / Déscape tool fait les deux dans votre navigateur, avec des options pour envelopper le résultat dans des devis, échapper à non-ASCII comme\uXXXX(ou échapper à la barre oblique avant).
Qu'est-ce que cela signifie pour échapper à une chaîne pour JSON ?
JSON a une grammaire précise et publiée - elle est définie par RFC 8259 et par la norme ECMA-404 - et les règles pour ce qui peut apparaître à l'intérieur d'une chaîne sont strictes Une chaîne JSON est une série de caractères enveloppés dans des guillemets doubles Parce que la guillemets doubles marque le début et la fin de la chaîne, une guillemets doubles à l'intérieur le texte y mettrait fin prématurément Parce que la barre oblique inverse commence une séquence d'échappement, une barre oblique inverse brute serait mal lue comme début d'une. Et comme les chaînes JSON sont censées être une seule ligne logique de texte, les caractères de contrôle littéraux - nouvelles lignes, onglets, retours de chariot - ne sont pas autorisés à s'asseoir à l'intérieur d'elles sans échappement.
L'évasion est le processus de remplacement de chacun de ces caractères gênants par une séquence de barre oblique inverse à deux caractères que JSON comprend Une double citation devient \". Une barre oblique inverse devient \\. Une nouvelle ligne devient \n. Le résultat est un texte qui apparence un peu plus laid mais il est maintenant sécuritaire de laisser tomber entre deux guillemets sans casser le document environnant La signification est identique - une lecture d'analyseur JSON \n produit à nouveau une véritable nouvelle ligne - mais la représentation est désormais légale.
Ceci est fondamentalement différent du formatage d'un document JSON Un formateur arrange la structure d'un objet entier : indentation, ordre des touches, espace entre les éléments L'évasion fonctionne d'un niveau vers le bas, sur le contenu d'une seule valeur de chaîne. Vous atteignez le Formateur JSON lorsque vous avez un document entier à imprimer ou à valider, et pour le Escape JSON / Déscape outil lorsque vous avez un morceau de texte brut, vous devez tenir dans un seul champ.
Quels personnages doivent réellement s'échapper ?
La spécification JSON est ici d'une spécificité rafraîchissante À l'intérieur d'une chaîne, exactement deux caractères moût soyez toujours échappé, plus toute la gamme des caractères de contrôle.
Les deux échappements obligatoires à un seul caractère sont le guillemet double (\") et la barre oblique inverse (\\). Au-delà de ceux-ci, JSON définit les échappements courts pour cinq caractères de contrôle courants : backspace (espace arrière)\b), former un aliment (\f), nouvelle ligne (\n), retour chariot (\r), et languette horizontale (\t). N'importe lequel autre le caractère de contrôle - tout ce qui a un point de code inférieur à U+0020 qui n'a pas de forme courte - doit être écrit comme un \u échappez-vous suivi de quatre chiffres hexadécimaux, donc un octet nul devient \u0000 et le " ; unit separator" ; devient \u001F.
Deux autres personnages sont facultatif pour s'échapper, et c'est là que la confusion s'insinue La barre oblique peut s'écrire ainsi \/mais il n’est pas nécessaire que ce soit une simple / est parfaitement valide JSON. Et tout caractère au-dessus de la gamme ASCII, comme un accent é ou un emoji, peut être écrit littéralement dans un document UTF-8 ou s'échapper comme \uXXXX; les deux sont légaux. Le Escape JSON / Déscape tool gère toujours les échappements obligatoires et vous donne des basculements pour les deux optionnels afin que vous puissiez correspondre à ce que votre système cible attend.
Dois-je échapper aux caractères slash et non-ASCII avant ?
Ces deux échappements optionnels existent pour de vraies raisons, même si vous en avez rarement besoin.
L'échappement avant-slash compte exactement dans une situation courante : lorsque JSON est intégré dans un HTML <script> balise. L'analyseur HTML browser' ;s recherche la séquence littérale </ pour trouver la fin d'un bloc de script, donc une chaîne contenant </script> dans votre JSON peut fermer prématurément la balise et casser la page Écriture de la barre oblique comme <\/script> - toujours valide JSON, toujours la même chaîne une fois analysée - évite cela En dehors des scripts en ligne, vous pouvez laisser les barres obliques seules, c'est pourquoi l'outil laisse la barre oblique non échappée par défaut.
Échapper aux caractères non ASCII en tant que \uXXXX il s'agit de portabilité plutôt que d'exactitude Si votre JSON peut passer par un système qui mutile les octets UTF-8 - un ancien pipeline de journalisation, un proxy mal configuré, un canal qui suppose ASCII - transformant chaque caractère au-dessus de la plage ASCII en un pur-ASCII \u escape garantit qu'il survit intact La sortie est plus volumineuse et moins lisible par l'homme, elle est donc désactivée par défaut, mais le " ; Escape Unicode" ; toggle est là pour le moment où vous avez besoin d'un transport pare-balles Un point de code comme é se transforme \u00e9« , et un analyseur JSON reconstruit le personnage original à la sortie ».
Comment fonctionne le désencaissement, et quand en ai-je besoin ?
Le désencaissement est l'inverse exact : il traverse une chaîne échappée et transforme chaque séquence de barre oblique inverse en caractère brut qu'elle représente. \n devient une vraie nouvelle ligne, \t devient un onglet, \" devient une double citation, et \uXXXX devient le caractère à ce point de code Vous en avez besoin chaque fois que vous êtes sur le côté de réception - vous avez copié une valeur de chaîne directement à partir d'un fichier JSON, d'une ligne de journal ou d'une réponse API, et vous voulez lire le texte original sans un écran plein de barres obliques inverses sur le chemin.
Un bon inescapier fait deux choses qu'un naïf de recherche et de remplacement ne fait pas. Premièrement, il supprime une seule paire de guillemets doubles environnants si la valeur entière est cotée, afin que vous puissiez coller "line one\nline two" directement à partir d'un document JSON et récupérer du texte propre Deuxièmement, il valide au fur et à mesure : une séquence d'échappement invalide comme \x(ou une barre oblique inverse perdue à la toute fin de la chaîne) est une véritable erreur, et le Escape JSON / Déscape tool rapporte sa position plutôt que de deviner et de produire une sortie silencieusement erronée Obtenir un " ; évasion invalide à la position 14" ; bat obtenir un texte qui semble presque correct mais qui est subtilement corrompu.
La propriété clé à laquelle il faut faire confiance est que s'échapper et se déséchapper sont des inverses exacts Échapper à tout texte et ensuite déséchapper au résultat et vous récupérez précisément ce que vous avez commencé, caractère pour personnage Cette garantie aller-retour est ce qui rend sûr d'utiliser l'outil comme une étape de routine dans un pipeline plutôt qu'une transformation risquée que vous devez vérifier à la main.
Échap versus opérations de chaîne associées
JSON qui s'échappe fait partie d'une famille de " ; rendre ce texte sûr pour ce contexte" ; se transforme, et cela aide à les garder droits. Voici comment cela se compare aux voisins avec lesquels les développeurs le confondent le plus souvent.
| Opération | Protège contre | exemple | outil |
|---|---|---|---|
| JSON s'échappe | Briser une chaîne JSON avec des guillemets, des barres obliques inverses ou des caractères de contrôle | he said "hi" → he said \"hi\" |
Escape JSON / Déscape |
| Encodage d'entité HTML | Briser HTML ou activer XSS avec <, >, & |
<b> → <b> |
Entités HTML |
| Pourcentage-encodage URL | Briser une URL avec des espaces ou des caractères réservés | a b → a%20b |
- |
| Format/valider JSON | Erreurs structurelles sur l'ensemble d'un document | minified → joli-imprimé | Formateur JSON |
| JSON → YAML | Déplacement d'une configuration entre les formats de sérialisation | {"a":1} → a: 1 |
JSON vers Yaml |
Le modèle à remarquer est que chaque évasion cible a différent conteneur. Les entités HTML empêchent le texte de casser HTML ; le codage en pourcentage l'empêche de casser une URL ; L'échappement JSON l'empêche de casser une chaîne JSON. L'utilisation de la mauvaise - encodage HTML de quelque chose qui nécessite l'échappement de JSON - laisse le vrai problème non résolu et ajoute une nouvelle couche de bruit. Parce que tout cela fonctionne sur du texte, vous ne voudrez peut-être pas le remettre à un serveur tiers, je garde chacun de ces outils côté client, ce qui est l'argument que j'ai fait en entier dans le guide de confidentialité des données pour les outils en ligne.
Quelles sont les erreurs courantes lors de l’intégration de texte dans JSON ?
L'erreur la plus courante est celle qui m'a coûté un après-midi : coller du texte multi-lignes avec des guillemets non échappés directement dans un champ JSON et supposer que parce que les deux parties sont valides, le tout ne l'est pas - le conteneur a des règles auxquelles le contenu doit obéir.
Une seconde proche est double évasion. Si une chaîne a déjà été échappée une fois et que vous y échappez à nouveau, chaque \n se transforme \\n et vos nouvelles lignes se transforment en un backslash-n littéral qu'aucun analyseur ne reconvertira Cela se produit généralement lorsqu'une valeur passe par deux systèmes qui chacun y échappe utilement Si votre sortie a des exécutions suspectes de \\ là où vous vous attendiez à des barres obliques inverses simples, vous avez probablement double échappée, et une fois en désévasion la réparera Le troisième piège est d'oublier qu'un chemin Windows comme C:\Users\me est plein de barres obliques inverses, dont chacune doit devenir \\ - un chemin non échappé dans JSON est une source classique de " ; pourquoi mon JSON est-il invalide" ; confusion.
Le correctif pour les trois est le même : laissez l'outil faire l'échappement exactement une fois, à la limite où le texte brut rencontre JSON, et lisez le résumé du nombre de caractères qu'il montre pour vérifier la santé mentale que quelque chose a changé. Lorsque vous devez vérifier manuellement, échappez-vous avec " ; enveloppez-le dans guillemets" ; activé et collez le résultat dans le Formateur JSON - s'il s'analyse comme une chaîne valide, votre évasion est correcte.
Un exemple concret : intégrer un extrait HTML dans JSON
Laissez-moi parcourir la situation exacte qui a déclenché cela, car voir la transformation une fois fait adhérer la règle Disons que vous voulez envoyer ce fragment comme le body champ d'une requête API :
<p>Hi "there",</p>
<p>Visit https://example.com/path</p>
Trois choses dans ce texte se battront avec JSON. Les deux doubles citations autour there essaiera chacun de terminer la chaîne La nouvelle ligne entre les paragraphes est un caractère de contrôle littéral que JSON interdit à l'intérieur d'une chaîne Et le </p> les séquences sont inoffensives dans un fichier JSON simple mais dangereuses si ce JSON est imprimé un jour dans un HTML <script> étiquette. Collez le fragment dans le Escape JSON / Déscape outil, activez " ; enveloppez-le dans des guillemets, " ; et vous obtenez une seule chaîne JSON valide : les guillemets deviennent \", la nouvelle ligne devient \net avec " ; échapper à la barre oblique et au quota ; activé, les balises de fermeture deviennent <\/p>. Déposez toute cette valeur citée directement dans votre body field et la demande passe par.
Le voyage inverse est tout aussi routinier Lorsqu'un coéquipier vous envoie une ligne de journal avec un JSON-escaped message champ plein de \n et \"« Coller dans l'outil, passer à Unescape, et lire le texte original multi-lignes avec les barres obliques inverses parties Parce que les deux opérations sont des inverses exacts, vous pouvez déplacer une charge utile pour la modifier et revenir sans crainte de corruption - le résumé du nombre de caractères confirme la transformation exécutée, et toute évasion mal formée est signalée avec sa position au lieu de mutiler silencieusement le texte Cette sécurité aller-retour est ce qui se transforme en échappant d'une étape manuelle nerveuse en quelque chose que vous pouvez connecter à un flux de travail et oublier. ».
Questions fréquentes
Qu'est-ce que cela signifie pour échapper à une chaîne pour JSON ? Les valeurs de chaîne JSON ne peuvent pas contenir de guillemet double brut, de barre oblique inverse brute ou de caractères de contrôle bruts comme les lignes neuves et les onglets L'échappement remplace chacun de ceux-ci par une séquence de barre oblique inverse - " ; devient " ;, une nouvelle ligne devient \n, un onglet devient \t - ainsi le texte peut être placé à l'intérieur d'une chaîne JSON sans casser la structure environnante.
En quoi est-ce différent d'un formateur JSON ? Un formateur JSON joli-imprime ou minimise un document JSON entier et valide sa structure. Cet outil travaille d'un niveau vers le bas, sur le contenu d'une seule chaîne : il permet à un texte arbitraire d'intégrer une valeur JSON ou de décoder une valeur échappée en texte brut. Utilisez le formateur pour les documents et cet outil pour les chaînes individuelles.
Quels personnages s'échappent ? La citation double (" ;), la barre oblique inverse (\), le retour arrière (\b), le flux de forme (\f), la nouvelle ligne (\n), le retour chariot (\r) et l'onglet (\t) sont toujours échappés, ainsi que tout autre caractère de contrôle inférieur à U+0020 comme \uXXXX. Facultativement, la barre oblique devient / et chaque caractère non ASCII devient \uXXXX.
Dois-je échapper à la barre oblique ? Il est facultatif La spécification JSON autorise à la fois / et /, donc simple / est valide Le seul endroit / compte est dans un HTML
