JSON vs YAML vs XML: sintaxe, usos e como converter entre eles

JSON, YAML e XML são formatos de texto simples para dados estruturados. Com a mesma informação, os três a descrevem fielmente, mas na prática cada um conquistou o seu próprio território: JSON nas APIs, YAML nos arquivos de configuração e XML em documentos e sistemas corporativos. Entender o porquê ajuda a escolher o formato certo e a evitar surpresas na hora de converter.

Os mesmos dados em três formatos

Aqui está a definição de um pequeno serviço escrita de três formas. Primeiro, em JSON:

{
  "service": "web",
  "port": 8080,
  "debug": false,
  "tags": ["api", "public"]
}

O mesmo em YAML:

# web service
service: web
port: 8080
debug: false
tags:
  - api
  - public

E em XML:

<?xml version="1.0" encoding="UTF-8"?>
<service name="web">
  <port>8080</port>
  <debug>false</debug>
  <tags>
    <tag>api</tag>
    <tag>public</tag>
  </tags>
</service>

Algumas diferenças saltam à vista:

• JSON usa chaves, colchetes e aspas. É rigoroso: sem comentários, sem vírgulas finais, chaves sempre entre aspas duplas.
• YAML se apoia na indentação em vez de colchetes e permite comentários com #. É o mais compacto e o mais fácil de ler de relance.
• XML envolve cada valor em tags de abertura e fechamento e pode associar atributos aos elementos (name="web"). É o mais verboso, mas também o mais expressivo.

JSON: a língua das APIs

O JSON corresponde diretamente aos objetos e arrays de quase todas as linguagens de programação, e por isso se tornou o formato padrão das APIs web. Os analisadores são rápidos, vêm integrados nos navegadores e nas bibliotecas padrão, e a gramática é tão pequena que há pouquíssimas formas de interpretar mal um documento.

Esse rigor é uma vantagem para as máquinas e um pequeno incômodo para as pessoas. Não dá para deixar um comentário explicando uma configuração, e uma única vírgula em falta quebra o arquivo inteiro. Por isso o JSON funciona melhor quando um programa o escreve e outro o lê: respostas de API, logs, exportações de dados, package.json.

YAML: configuração escrita por pessoas

O YAML foi pensado para ser escrito e revisado por pessoas. É por isso que tantas ferramentas de DevOps o adotaram: os manifestos do Kubernetes, os workflows do GitHub Actions e os arquivos do Docker Compose são YAML. Comentários, strings de várias linhas e a ausência de pontuação tornam agradável a manutenção de arquivos de configuração longos.

O preço são as sutilezas. A indentação tem significado, então um espaço fora do lugar altera a estrutura. E o YAML deduz os tipos dos valores sem aspas, o que leva às suas armadilhas mais famosas:

country: NO      # YAML 1.1: false
version: 1.10    # 1.1 (number)
zip: 01234       # 1234 or octal

Pelas regras do YAML 1.1, ainda usadas por muitos analisadores, NO, yes, on e off viram booleanos. Os números perdem os zeros finais e zeros à esquerda podem ser lidos como octal. A solução é simples: coloque entre aspas tudo o que precisa continuar sendo texto.

country: "NO"
version: "1.10"
zip: "01234"

XML: documentos, esquemas e feeds corporativos

O XML é mais antigo que os outros dois e traz recursos que eles não têm: namespaces para misturar vocabulários, esquemas (XSD) para validar a estrutura com rigor, atributos e conteúdo misto em que texto e tags se intercalam. Isso o torna ideal para documentos e para sistemas em que um contrato formal importa: feeds RSS e Atom, serviços SOAP, padrões de faturação e bancários, imagens SVG, o pom.xml do Maven e os arquivos que existem dentro de um DOCX ou XLSX.

Se você está começando algo novo e só precisa trocar dados, o XML raramente é a primeira escolha. Mas você vai continuar a recebê-lo de parceiros, sistemas legados e fontes de dados públicas, por isso saber transformá-lo em JSON é uma habilidade muito prática.

Comparação rápida

• Legibilidade: YAML > JSON > XML.
• Rigor e previsibilidade: JSON e XML não são ambíguos; o YAML depende da indentação e da dedução de tipos.
• Comentários: YAML e XML sim, JSON não.
• Validação: o XML tem as ferramentas de esquema mais maduras; o JSON Schema é amplamente usado; o YAML também costuma ser validado com JSON Schema.
• Hábitat típico: JSON para APIs e dados, YAML para configuração, XML para documentos e integração corporativa.

Converter entre eles: o que observar

Como os três descrevem árvores de dados, a conversão costuma ser simples. Ainda assim, vale conhecer alguns detalhes:

• De YAML para JSON, os comentários se perdem. O JSON não tem onde guardá-los. Âncoras e aliases (& e *) são expandidos em cópias comuns.
• De JSON para YAML, nada se perde. Todo JSON válido pode ser expresso em YAML; no YAML 1.2, o JSON é quase um subconjunto do YAML.
• Os atributos XML exigem uma convenção. O JSON não tem atributos, por isso os conversores os guardam como chaves comuns, muitas vezes com um prefixo como @. Confira o resultado antes de entregá-lo a outro programa.
• Elemento único ou lista. No XML, uma <tag> e três <tag> se escrevem da mesma forma. No JSON, uma pode virar objeto e as outras um array, então o código que consome o resultado deve lidar com os dois casos.
• No XML, tudo é texto. 8080 e false são só caracteres entre tags; ao passar de XML para JSON, talvez seja preciso convertê-los de volta em número ou booleano.
• De JSON para XML é preciso uma raiz única e chaves que sejam nomes de elemento válidos (sem espaços e sem começar por um dígito).

Converta no seu navegador

Os conversores de dados do Azpy funcionam inteiramente no seu navegador: cole o texto ou solte um arquivo e o resultado aparece na hora, sem nada ser enviado. Assim você pode usá-los com tranquilidade em arquivos de configuração com nomes de servidores internos ou respostas de API com dados de clientes. JSON para YAML, YAML para JSON, XML para JSON e JSON para XML estão entre as ferramentas.

Uma regra rápida

Máquinas conversando com máquinas → JSON. Pessoas editando configuração → YAML, com aspas em tudo o que for ambíguo. Documentos, esquemas rigorosos ou um contrato corporativo existente → XML. E quando o formato que você tem não é o que precisa, converta-o e confira os casos-limite acima.