JSON Lines ou tableau JSON : comprendre la structure attendue par une API

JSON Lines et tableau JSON : deux structures distinctes

JSON est un format de données textuel qui permet de représenter des données structurées. La page de MDN Web Docs consacrée à JSON en donne une présentation générale. La référence fournie ici est en espagnol : [« Trabajar con JSON »](https://developer.mozilla.org/es/docs/Learn_web_development/Core/Scripting/JSON). Claris documente pour sa part l’export de données au format JSON Lines dans son aide FileMaker Pro. La référence fournie est également en espagnol : [« Guardar registros como JSONL »](https://help.claris.com/es/pro-help/content/save-records-as-jsonl.html).

JSON Lines, souvent abrégé en JSONL, présente des valeurs JSON séparées par des sauts de ligne. Dans un fichier utilisé pour représenter des enregistrements, chaque ligne peut ainsi contenir un enregistrement sous forme d’objet. Les lignes ne sont toutefois pas nécessairement des objets : une valeur JSON peut aussi être, par exemple, une chaîne ou un nombre. Un tableau JSON, lui, regroupe des valeurs à l’intérieur d’une structure de tableau. Ce sont donc des formes différentes, même si elles peuvent représenter des données similaires.

Les exemples ci-dessous sont schématiques et ne décrivent pas le contrat d’une API particulière. Ils servent uniquement à visualiser la différence de structure. Les noms, valeurs et champs sont fictifs.

• JSON Lines : plusieurs valeurs JSON présentées sur des lignes séparées.
• Tableau JSON : plusieurs valeurs regroupées dans une structure de tableau.
• La documentation du point de terminaison, et non le nom du fichier, indique la forme attendue.

Exemple illustratif : observer la forme à la racine

Supposons que l’on veuille représenter deux entrées fictives, chacune avec un identifiant et un nom. En JSON Lines, l’exemple peut s’écrire ainsi, avec une valeur JSON par ligne :

En tableau JSON, les deux mêmes objets peuvent être regroupés dans une seule structure :

Dans le premier extrait, il n’y a pas de crochets qui entourent l’ensemble des lignes. Dans le second, les crochets délimitent un tableau et les objets y sont séparés par des virgules. Cette comparaison montre pourquoi remplacer une structure par l’autre ne consiste pas simplement à changer l’extension du fichier. Elle ne prouve pas non plus que l’API cible accepte l’un ou l’autre format.

Une API peut attendre un tableau à la racine, un objet contenant une propriété dédiée, ou une autre structure décrite dans son contrat. Les exemples de requête fournis par l’équipe de l’API sont donc plus utiles qu’une supposition fondée sur le fait que le fichier contient plusieurs éléments.

• Exemple JSON Lines : {"id": 1, "nom": "A"} puis, sur la ligne suivante, {"id": 2, "nom": "B"}.
• Exemple de tableau JSON : [{"id": 1, "nom": "A"}, {"id": 2, "nom": "B"}].
• Ces extraits montrent deux formes possibles, pas une règle universelle d’envoi à une API.

Consultez le contrat de l’API avant de préparer les données

Commencez par identifier l’opération précise que vous souhaitez effectuer et le point de terminaison concerné. Consultez ensuite sa documentation et recherchez un exemple de requête, une description du corps transmis ou un schéma fourni par le service. La structure attendue peut changer d’une opération à l’autre, même au sein d’une même API.

Examinez d’abord la forme à la racine de l’exemple documenté : s’agit-il d’un tableau, d’un objet ou d’une autre valeur ? Si la documentation décrit des propriétés ou des champs, comparez-les avec ceux de vos données. Vérifiez aussi les types de valeurs et les champs requis lorsqu’ils sont précisés par le service. Ces contrôles rapprochent votre préparation du contrat documenté, sans présumer qu’un format donné convient partout.

Si la documentation montre uniquement un exemple pour un seul élément, ne déduisez pas automatiquement comment transmettre un lot. L’API peut documenter une opération distincte pour les lots ou ne pas les prendre en charge dans ce point de terminaison. Si le nombre d’éléments ou la structure du corps ne sont pas expliqués, demandez une clarification à l’équipe responsable.

• Repérez l’opération exacte et le point de terminaison visé.
• Comparez la structure à la racine avec l’exemple de requête documenté.
• Vérifiez les champs, les types et les contraintes explicitement indiqués.
• Demandez confirmation lorsque la documentation ne précise pas le traitement de plusieurs éléments.

Effectuez des vérifications concrètes sans supposer une validation universelle

Une vérification utile consiste à comparer une petite sélection de données avec l’exemple de l’API. Repérez si les valeurs sont présentées une par ligne ou regroupées dans un tableau. Comparez ensuite les champs visibles, leurs noms et leurs types avec les indications du contrat. Si le service documente des champs obligatoires, vérifiez qu’ils sont présents dans les éléments concernés.

Vérifiez également que la structure choisie est cohérente d’un bout à l’autre du contenu que vous préparez. Par exemple, ne mélangez pas dans un même fichier des lignes interprétées comme des enregistrements avec une ligne qui contient une structure enveloppante différente, sauf si le format et l’outil utilisés prévoient explicitement ce cas. La façon de détecter ou de traiter une telle différence dépend de l’outil : consultez sa documentation plutôt que de présumer de son comportement.

Une erreur de raisonnement fréquente est de penser qu’un fichier JSON Lines devient un tableau JSON dès qu’on ajoute des crochets autour du contenu. La structure finale doit respecter la syntaxe voulue et, surtout, le contrat de l’API. Les sources citées dans cet article présentent JSON de manière générale et documentent un export JSONL ; elles ne valident pas une procédure universelle de conversion, ni des règles détaillées de validation ligne par ligne.

• Comparez un échantillon représentatif à la requête de référence.
• Contrôlez la forme à la racine et les champs explicitement documentés.
• Ne supposez pas qu’un outil détecte ou corrige automatiquement toutes les différences.
• Faites vérifier le résultat si l’exemple de l’API ne permet pas de trancher.

Évaluez les compromis avant de choisir une structure

La présentation ligne par ligne peut être pratique lorsque les données sont organisées comme une suite de valeurs indépendantes. Elle rend visible la séparation entre ces valeurs, mais ne signifie pas que le destinataire peut les accepter telles quelles. La compatibilité dépend de ce que l’API et les outils concernés indiquent prendre en charge.

Un tableau JSON regroupe les valeurs dans une seule structure. Cette forme peut correspondre à l’exemple d’une API qui attend explicitement un tableau, mais elle n’est pas automatiquement préférable pour toute transmission de plusieurs éléments. Si l’API demande plutôt un objet avec des propriétés définies, un tableau seul ne répondra pas à cette description. Le bon choix n’est donc pas une question de préférence générale : il dépend de l’opération et du contrat.

Il faut aussi distinguer la forme des données de leur contenu. Un changement de structure peut nécessiter de réorganiser les valeurs, mais les informations fournies ici ne permettent pas de garantir qu’une méthode particulière préservera chaque donnée dans tous les cas. Avant de traiter un fichier complet, vérifiez les capacités de l’outil choisi et comparez le résultat à la structure attendue.

• JSON Lines rend visibles des valeurs séparées, mais son acceptation dépend du destinataire.
• Un tableau regroupe les valeurs, mais ne remplace pas un objet ou une autre forme exigée.
• La documentation de l’API prime sur la commodité apparente d’un format.
• Vérifiez la méthode et le résultat avant de traiter l’ensemble des données.

Conservez une référence au fichier d’origine

Avant toute modification, conservez séparément le fichier d’origine et identifiez clairement la copie de travail. Cette précaution permet de comparer les versions et de revenir aux données de départ si la structure préparée ne convient pas. Elle ne garantit pas la conformité du résultat, mais rend les changements plus faciles à examiner.

Notez la méthode ou l’outil utilisé et les points que vous avez vérifiés, par exemple la structure attendue dans la documentation de l’API. Si certains éléments restent ambigus, indiquez-les clairement au lieu de présenter le fichier comme prêt à l’envoi. Cette trace aide les personnes responsables de l’intégration à revoir le raisonnement et à demander une confirmation si nécessaire.

Si vous utilisez un convertisseur, vérifiez dans sa documentation les formats d’entrée et de sortie qu’il prend en charge. Ne supposez pas qu’un outil accepte JSON Lines parce qu’il traite des fichiers JSON en général. Les capacités d’un outil peuvent varier selon les formats et les opérations proposées.

• Gardez le fichier source séparé de la copie préparée.
• Identifiez clairement les versions et la méthode utilisée.
• Consignez les exigences confirmées et les points qui restent incertains.

Outils et vérifications avant utilisation

Apification permet d’intégrer Cloud et ses services au moyen de REST API, OpenAPI, webhooks, iframe et JavaScript. Son assistant guidé permet également de traiter des données et d’autres fichiers. Ces capacités générales ne confirment pas la prise en charge de JSON Lines ni une conversion précise entre JSON Lines et un tableau JSON.

Avant de vous appuyer sur un outil, consultez ses informations sur les formats pris en entrée et en sortie. Confirmez ensuite que le résultat correspond à la structure exigée par le point de terminaison. Les éléments de preuve disponibles pour cet article ne définissent pas de procédure universelle de conversion JSON Lines vers tableau JSON et ne permettent pas d’affirmer qu’Apification réalise cette conversion spécifique.

Les références citées peuvent aider à comprendre JSON et à reconnaître un exemple d’export JSONL. Elles ne remplacent pas la documentation du service que vous souhaitez appeler. La page MDN fournie et l’aide Claris fournie sont en espagnol ; leurs titres et liens sont indiqués tels quels afin de signaler explicitement leur langue.

• Vérifiez séparément les formats pris en charge par l’outil et ceux acceptés par l’API.
• Ne déduisez pas une conversion précise de capacités générales de traitement ou d’intégration.
• Consultez le contrat du point de terminaison avant de transmettre les données.

Questions fréquentes