YAML

Deux formats, des rôles qui se chevauchent

JSON (JavaScript Object Notation) et YAML (YAML Ain’t Markup Language) représentent tous deux des données structurées : objets imbriqués, listes, chaînes, nombres et booléens. On les trouve dans les APIs, les fichiers de configuration, les pipelines CI, les manifests Kubernetes et les exemples de documentation. Choisir entre eux n’est pas tant une question de « meilleur » format que de savoir qui édite le fichier, quels outils le consomment et à quel point le parsing doit être strict.

Si vous avez déjà du JSON et voulez l’inspecter sous forme d’indentation YAML, convertissez avec JSON vers YAML.

JSON en bref

JSON est né de la syntaxe des littéraux d’objets JavaScript et est devenu un format d’échange indépendant du langage. Un document JSON se construit à partir de :

• Objets : { "key": "value" }
• Tableaux : [1, 2, 3]
• Chaînes entre guillemets doubles
• Nombres
• true, false et null

Contraintes notables : pas de commentaires, pas de virgules finales en JSON standard, les clés doivent être des chaînes, et les chaînes utilisent une syntaxe d’échappement limitée. Ces contraintes rendent les parseurs simples et stricts—précieux pour les machines qui échangent des données.

Le JSON mis en forme est lisible pour de petits documents. Les grandes configs à imbrication profonde deviennent bruyantes à cause des accolades, crochets et clés quotées à chaque ligne.

YAML en bref

YAML privilégie l’édition humaine. La structure est surtout portée par l’indentation plutôt que par les accolades. Parmi les fonctionnalités :

• Commentaires commençant par #
• Chaînes non quotées dans de nombreux cas
• Anchors et alias pour la réutilisation
• Flux multi-documents séparés par ---
• Tags de type explicites en usage avancé

Un petit mapping ressemble à :

service:
  name: api
  replicas: 3
  ports:
    - 8080
    - 8443

La même structure en JSON répète la ponctuation et les guillemets. Pour les opérateurs qui éditent des manifests au quotidien, la concision de YAML est attrayante.

Chevauchement du modèle de données

Au cœur, les deux formats peuvent exprimer des arbres de maps et de séquences avec des feuilles scalaires. Le round-trip est souvent possible pour le sous-ensemble commun : objets, tableaux, chaînes, nombres, booléens et null.

Les différences apparaissent aux marges :

• YAML peut produire des clés non-chaînes ; JSON ne le peut pas.
• YAML offre plus de façons d’écrire les chaînes (blocs littéraux, blocs folded).
• Le « Norway problem » de YAML et d’autres bizarreries de typage implicite peuvent transformer NO, on ou des jetons version-like non quotés en booléens ou nombres selon la version YAML et le parseur.
• Les nombres JSON sont directs ; YAML peut parser spécialement de grands entiers ou des timestamps dans certains loaders.

Quand l’interopérabilité compte, préférez quoter en YAML les chaînes qui ressemblent à des booléens, des nombres ou des dates, ou générez le YAML depuis une structure typée plutôt que d’éditer à la main des scalaires ambigus.

Commentaires et documentation

JSON n’a pas de commentaires standard. Les équipes abusent parfois de champs "_comment", qui polluent les schemas. Les commentaires # de YAML documentent l’intention à côté des données—pourquoi le nombre de réplicas est 3, quelle équipe possède un label—sans changer le modèle d’information.

Si votre audience principale est des machines (APIs, corps fetch du navigateur), l’absence de commentaires de JSON est rarement un problème. Si des humains maintiennent le fichier pendant des mois, les commentaires YAML réduisent la perte de savoir tribal.

Outillage et écosystème

Forces de JSON

• Parseurs omniprésents dans presque tous les langages mainstream
• Support navigateur de premier plan (JSON.parse / JSON.stringify)
• Écosystèmes de schema (JSON Schema) largement adoptés
• Diffs orientés lignes familiers, même s’ils sont riches en accolades
• Parseurs en streaming pour les gros payloads

Forces de YAML

• Dominant en DevOps (Kubernetes, Ansible, de nombreux systèmes CI)
• Merges et anchors (puissants, parfois surutilisés)
• Fichiers multi-documents pour regrouper des ressources liées
• Plus agréable pour une configuration peu imbriquée

Risques de YAML

• Complexité de la spécification (différences YAML 1.1 vs 1.2)
• Erreurs d’indentation difficiles à voir
• Fonctionnalités (custom tags, merge keys) qui réduisent la portabilité
• Exécution accidentelle de code dans des loaders non sécurisés historiquement—utilisez toujours des APIs de chargement sûr

Performance et taille

Pour les protocoles filaires, JSON est en général moins coûteux à parser dans des bibliothèques natives optimisées et évite le surcoût d’indentation. JSON et YAML compressés convergent en taille. Pour une configuration lue occasionnellement et éditée souvent, la vitesse de parsing est rarement le goulot ; le taux d’erreur humaine l’est.

Les cousins binaires (MessagePack, CBOR, Protobuf) surpassent les deux quand le débit domine. Ce ne sont pas des formats humains de remplacement immédiat.

Stratégies de conversion

Convertir JSON → YAML est typiquement sans perte pour le sous-ensemble commun et utile pour les revues de lisibilité. Convertir YAML → JSON peut perdre commentaires, anchors et types non JSON. Traitez la conversion comme une projection, pas comme une archive parfaite de l’intention d’auteur.

Conseils de workflow :

1. Gardez une seule source de vérité (souvent JSON Schema ou un modèle typé du langage).
2. Générez le format dont chaque consommateur a besoin.
3. Si des humains doivent éditer le YAML, validez contre un schema à chaque changement.
4. Évitez de maintenir à la main deux copies du même document.

Le convertisseur from-json de Tool Plaza vous aide à prévisualiser un payload JSON avec une syntaxe basée sur l’indentation.

Quand choisir JSON

• APIs HTTP publiques et corps de webhooks
• Clients navigateur et mobiles
• Échange machine strict avec une ambiguïté minimale
• Journalisation d’événements structurés vers des agrégateurs qui attendent des JSON lines
• Intégration dans des langages où les littéraux JSON se mappent proprement aux types natifs

Quand choisir YAML

• Manifests de déploiement et d’infrastructure édités par des personnes
• Fichiers de config qui bénéficient des commentaires
• Écosystèmes déjà standardisés sur YAML
• Documents où la clarté d’indentation bat l’appariement d’accolades pour votre équipe

Approches hybrides

Certains projets stockent du JSON canonique en contrôle de version et génèrent du YAML pour un outil précis. D’autres acceptent une entrée YAML, normalisent vers un AST interne et émettent du JSON pour les APIs. Les deux fonctionnent si le pipeline est automatisé et testé.

Soyez prudents avec les extensions « JSON5 » ou « JSONC » (JSON avec commentaires) : elles améliorent l’ergonomie mais ne sont pas universelles. Documentez le dialecte si vous en adoptez un.

Hygiène d’édition et de revue

• Utilisez des éditeurs qui mettent en évidence l’indentation et les espaces en fin de ligne pour YAML.
• Faites échouer la CI sur une syntaxe invalide avant le merge.
• Préférez une indentation de 2 espaces de façon cohérente dans les équipes YAML.
• Gardez des lignes raisonnablement courtes ; les énormes chaînes inline appartiennent aux blocs littéraux ou aux fichiers externes.
• Ne collez pas de secrets dans l’un ou l’autre format dans des dépôts publics—utilisez des gestionnaires de secrets et des références.

Résumé

JSON est le format d’échange strict et omniprésent ; YAML est le dialecte de configuration accueillant aux commentaires, à la syntaxe plus riche—et plus risquée. Ils partagent un modèle de données imbriqué pour les maps et listes du quotidien. Choisissez JSON pour les APIs et les machines, YAML pour les fichiers d’infra opérés par des humains, et convertissez délibérément quand vous avez besoin des deux vues de la même structure.