Convertir TSV en JSON

Les outils qui produisent du TSV choisissent la tabulation parce que leurs données sont pleines de virgules et qu’aucun délimiteur ne doit être cité. Les clients de base de données impriment leurs résultats en colonnes tabulées. Les fichiers d’annotation de génomes, les tableaux d’expression, les exports d’analytics et de nombreuses consoles d’administration sortent ainsi par convention. Un point-virgule, un accent ou un titre de campagne n’a aucune chance de couper une ligne de travers.

Ce choix achète la fiabilité face aux virgules et sacrifie presque tout le reste. Le fichier n’a pas de types, pas d’imbrication, pas de marqueur d’identifiant, aucune défense contre une tabulation apparue dans une valeur. C’est un bon format de transport et une mauvaise matière à calculer, et c’est pour cela que la première chose que la plupart des gens en font est de la convertir.

La ligne d’en-tête fournit les clés et chaque ligne suivante devient un objet. Le résultat est un tableau JSON — la forme qu’un script, un carnet, un fetch JavaScript et presque toutes les bibliothèques attendent quand elles disent « les données ».

Rien n’est enveloppé autour, rien n’est indexé par une colonne identifiant, parce que faire l’un ou l’autre suppose de savoir quelle colonne joue ce rôle et que ce n’est pas une décision qu’un convertisseur peut prendre à votre place. Un tableau suppose le moins possible, et le transformer en dictionnaire indexé par n’importe quel champ tient en une ligne dans le langage que vous êtes en train d’écrire.

Un TSV n’a pas de mécanisme d’échappement pour une tabulation dans un champ, et un saut de ligne à l’intérieur est pire : la ligne se termine là où la valeur devait continuer. Les deux se produisent en pratique, d’ordinaire dans une colonne de notes, de description ou d’annotation où quelqu’un a collé depuis autre chose.

En JSON ce sont des caractères ordinaires. Une tabulation s’écrit \t dans la chaîne, un saut de ligne devient \n, et aucun ne peut affecter la structure du document, parce que la structure s’exprime par des accolades et des crochets plutôt que par les caractères dans les données. C’est la raison la plus forte de convertir un TSV mal tenu plutôt que de continuer à le traiter comme du texte, et cela vaut la peine de le faire avant que le fichier ne soit passé à quoi que ce soit d’autre.

Un en-tête « Symbole de gène » devient la clé « Symbole de gène », espaces compris, et « Coût (USD) » garde ses parenthèses. Rien n’est renommé, mis en minuscules ou transformé en snake_case, parce qu’un convertisseur qui réécrirait silencieusement vos noms de colonnes rendrait la sortie impossible à réconcilier avec la source.

Cela a des conséquences à l’usage. `row["Symbole de gène"]` est la forme qu’il faudra écrire dans la plupart des langages. Si le JSON part dans du code qui sera maintenu, renommer les clés une seule fois — dans l’en-tête avant la conversion, ou en une passe après — vaut la peine d’être fait délibérément. Deux colonnes partageant un même en-tête est le piège à surveiller : les clés d’objet sont uniques, donc la seconde gagne et la première est perdue sans avertissement.

JSON distingue 7 de « 7 » et un TSV ne le fait pas, donc l’analyseur infère. Les nombres deviennent des nombres, `true` et `false` deviennent des booléens, et tout le reste reste une chaîne. Pour des quantités, des comptes, des scores et des prix c’est exactement ce qu’il faut et cela épargne une passe de conversion à l’autre bout.

Pour les identifiants c’est de la destruction. Une valeur 00123 devient 123, un numéro d’accession écrit en notation scientifique devient le nombre qu’il ressemble à être, et une fois que le JSON contient un nombre il n’y a plus rien à récupérer comme texte d’origine. La règle est de se demander si additionner deux valeurs de la colonne aurait un sens : si non, la colonne est un identifiant et elle voulait rester une chaîne. Vérifiez ces colonnes dans la sortie avant de construire quoi que ce soit par-dessus.

La conversion est souvent la première étape pour lire un fichier que personne n’a documenté, et le JSON rend cela rapide. `jq "length"` donne le nombre de lignes sans que l’en-tête s’y mêle. `jq ".[0] | keys"` liste les colonnes telles que l’analyseur les a vues. `jq "[.[].status] | unique"` montre les valeurs distinctes d’une colonne, ce qui est aussi comment on trouve la sentinelle qui ruinait silencieusement un champ numérique.

Cette dernière commande vaut la peine sur n’importe quelle colonne que vous attendiez numérique et qui revient en chaînes. La raison est presque toujours quelques lignes portant `NA`, `-`, `n/a` ou une note de bas de page, et savoir quel marqueur la source a utilisé est plus utile que tout effort à deviner le schéma. C’est aussi considérablement plus rapide qu’ouvrir un gros TSV dans un tableur, qui est l’alternative et qui applique ses propres conversions à l’ouverture.

Un vide entre deux tabulations est écrit `null`. C’est une décision qui mérite d’être dite, parce que tout ce qui consommera le JSON traitera null et "" différemment : un schéma déclarant un type chaîne rejettera null, et un test de vérité en JavaScript traite les deux comme faux mais un test de type ne le fait pas.

La source ne peut pas dire lequel était voulu. Un fichier délimité a une seule manière d’écrire « rien ici » et l’utilise pour une valeur vide et pour un champ qui ne s’applique pas. Si cette distinction compte, elle doit exister dans le fichier avant la conversion — comme sentinelle, ou comme seconde colonne — et aucun convertisseur ne peut l’inventer après coup.

Les clés viennent de l’en-tête et chaque ligne ultérieure est appariée contre lui, donc une table où une colonne supplémentaire commence à apparaître après dix mille lignes ne gagne pas une nouvelle clé. Les valeurs en surplus atterriront ensemble sous une clé `__parsed_extra`, sous forme de tableau, sur les seuls enregistrements qui les portent. Les lignes auxquelles il manque un champ n’auront pas cette clé du tout.

C’est plus courant qu’il ne devrait dans des exports assemblés à partir de plusieurs exécutions, et c’est l’échec qu’une lecture positionnelle gère le plus mal — un découpeur naïf décale chaque valeur après la colonne manquante et produit des lignes qui ont l’air correctes et ne le sont pas. Avoir le fichier sous forme d’objets rend l’incohérence visible : un appel à `keys` sur quelques enregistrements montre immédiatement que la forme n’est pas uniforme.

Attendez-vous à ce que le fichier grossisse. Chaque enregistrement répète chaque clé, chaque chaîne est entre guillemets, et la ponctuation d’un objet entoure les valeurs. Sur une table large avec de longs en-têtes et des valeurs courtes, le JSON peut être plusieurs fois la taille de la source tabulée.

C’est un prix correct pour un fichier que vous allez traiter et un mauvais pour un fichier que vous voulez seulement stocker. La sortie est aussi joliment indentée à deux espaces, ce qui la rend lisible dans un éditeur et ajoute encore des octets. Si la destination est le stockage ou un flux plutôt qu’un script, NDJSON ou Parquet est une meilleure cible et la même table se convertit vers l’un ou l’autre.

L’analyse et la sérialisation sont du JavaScript ordinaire chargé par cette page, donc rien n’est téléversé, il n’y a pas de file et il n’y a pas de compte. Ce qui compte pour ce type de fichier : une table de référence sous embargo, un extrait client, un jeu de résultats non publié.

Le tableau est construit en entier avant d’être écrit, donc la mémoire est le plafond. Quelques dizaines de mégaoctets est routinier, quelques centaines est le point où un onglet de navigateur commence à peiner. Au-delà, un lecteur en flux dans un script est le bon instrument, et le dire est plus utile que de laisser une très grande conversion échouer aux deux tiers.