O que é YAML? Sintaxe, Tipos de Dados, Usos e Armadilhas

A API de Scraping Sem Raspagem retorna dados da web estruturados em JSON ou CSV, que um pipeline controlado pode transformar em YAML quando um limite de configuração editado por humanos precisar.

O que significa YAML?

YAML significa “YAML Não É Uma Linguagem de Marcação.” É uma linguagem de serialização de dados baseada em Unicode projetada para mapear de forma limpa para estruturas de programação comuns. Um documento YAML é construído a partir de três principais tipos de nó: mapeamentos para associações de chave-valor, sequências para coleções ordenadas e escalares para valores individuais.

O especificação YAML 1.2.2 descreve o modelo de representação, árvore de serialização, fluxo de apresentação, sintaxe, tags e esquemas. A camada de apresentação do YAML oferece várias maneiras de escrever dados equivalentes, o que ajuda os autores humanos, mas dá aos implementadores mais opções do que a gramática menor do JSON.

YAML é dados, não uma linguagem de instruções por definição. Aplicações usam frequentemente para configurar implantações, sistemas de construção, jobs de automação, metadados de sites estáticos e ferramentas de desenvolvedor locais. A aplicação decide quais chaves são válidas e o que essas chaves fazem.

Sintaxe Básica de YAML

Uma configuração YAML pode combinar mapeamentos, sequências, números, booleanos e valores aninhados:

service:
  name: catalog-worker
  enabled: true
  workers: 4
  regions:
    - us-east
    - eu-west
  output:
    format: json
    include_metadata: true

O dois-pontos separa uma chave de mapeamento de seu valor. Um hífen introduz um item de sequência no estilo de bloco. A indentação coloca name, enabled, e as configurações restantes sob service. O documento não precisa de chaves ou vírgulas neste estilo.

Mapeamentos

Um mapeamento associa chaves com valores. Chaves são comumente strings simples, embora o modelo de linguagem permita chaves mais complexas. Autores de configuração devem preferir chaves de string simples e únicas, pois bibliotecas de aplicação e ferramentas de validação lidam com elas de maneira previsível.

Chaves duplicadas em mapeamentos são um problema de portabilidade. Bibliotecas podem rejeitá-las, manter um valor ou expor comportamento controlado por uma opção. Um carregador de configuração de produção deve rejeitar duplicatas para que um revisor e a aplicação em execução vejam a mesma configuração efetiva.

Sequências

Uma sequência é ordenada. O estilo de bloco usa um hífen por item, enquanto o estilo de fluxo usa colchetes:

regions: [us-east, eu-west]

checks:
  - name: schema
    required: true
  - name: links
    required: true

Cada item pode ser um escalar, mapeamento ou outra sequência. A ordem deve ser usada apenas quando o contrato da aplicação atribuir significado a ela.

Escalares e Citação

Escalares incluem strings, números, booleanos, nulos, timestamps sob alguns esquemas e valores com tags explícitas. Escalares simples omitidos, mas pontuação e certas palavras podem ser interpretadas de maneiras inesperadas entre versões YAML ou esquemas de parser. Cite valores quando sua forma textual deve permanecer exata, incluindo números de versão, identificadores com zeros à frente e strings que se assemelham a booleanos ou nulos.

Strings com aspas simples tratam a maioria dos caracteres literalmente. Strings com aspas duplas suportam sequências de escape. Escalares em bloco usam | para preservar quebras de linha ou > para dobrar linhas em espaços, com indicadores adicionais controlando a indentação e quebras de linha finais.

Comentários, Âncoras, Aliases e Tags

Um caractere hash começa um comentário fora de um escalar entre aspas. Comentários tornam o YAML atraente para configuração, pois os mantenedores podem explicar por que uma configuração existe. Comentários são parte da apresentação e não do núcleo do modelo de dados, então muitos parsers os descartam ao carregar e escrever um documento.

Uma âncora rotula um nó, e um alias refere-se a esse nó em outro lugar. Isso pode reduzir configurações repetidas:

defaults: &defaults
  timeout_seconds: 30
  output: json

jobs:
  catalog:
    <<: *defaults
    region: us-east

A chave de mesclagem mostrada aqui é amplamente utilizada, mas o comportamento de mesclagem não é uma característica universal simples de todos os caminhos de processamento YAML. Confirme o que a biblioteca e a aplicação escolhidas suportam. Gráficos de âncoras excessivos também dificultam a revisão da configuração, pois o valor efetivo não é mais visível em um só lugar.

Tags identificam o tipo ou interpretação de um nó. Tags padrão cobrem strings, inteiros, mapeamentos, sequências e outros valores essenciais. Algumas bibliotecas suportam tags específicas da aplicação que constroem objetos de linguagem. Carregar tags não confiáveis em construtores de objetos pode ser perigoso; use um carregador seguro que limite a construção a tipos de dados esperados.

Esquemas YAML e Diferenças de Versão

Um esquema YAML determina como o texto escalar se resolve para tags. Diferenças de versão e esquemas explicam muitos exemplos surpreendentes encontrados em repositórios de configuração. Uma palavra interpretada como booleano por um modo de processamento pode permanecer uma string em outro. A sintaxe numérica e o tratamento de timestamps também podem variar.

O YAML 1.2 alinhou seu esquema JSON para que documentos JSON sejam YAML válidos no modelo de compatibilidade pretendido. Isso não significa que todo arquivo YAML é um JSON válido: comentários, chaves não citadas, coleções em bloco, âncoras, aliases e tags são características do YAML fora da sintaxe JSON.

O especificação do tipo de mídia YAML registra application/yaml e o +yaml sufixo de sintaxe estruturada. Uma extensão de arquivo sozinha não indica o esquema do parser ou o contrato da aplicação. Os projetos devem fixar a biblioteca do parser, documentar a versão ou subconjunto do YAML suportado e validar os dados carregados contra um esquema de aplicação.

YAML vs JSON

Casos de uso comuns do YAML

Segurança e Confiabilidade do YAML

YAML não confiável deve ser tratado como entrada estruturada não confiável. Use um modo seguro de carregamento que construa apenas valores de dados comuns, não objetos específicos de linguagem ou classes de aplicação. O risco geral pertence à categoria mais ampla descrita por CWE-502: Desserialização de Dados Não Confiáveis.

Defina limites para o tamanho da entrada, profundidade de aninhamento, aliases e expansão agregada. Um pequeno documento pode referenciar valores ancorados muitas vezes, fazendo com que um carregador crie uma estrutura em memória muito maior. Bibliotecas expõem diferentes controles, então os testes devem exercer o parser implantado com limites representativos.

Valide os dados carregados após a análise. Rejeite chaves de nível superior desconhecidas quando erros de configuração seriam perigosos. Verifique campos obrigatórios, valores enum permitidos, intervalos numéricos, restrições de caminho e relacionamentos entre configurações. Não registre segredos ou a configuração completa em um erro de validação.

Erros Comuns do YAML

• Usar tabs para indentação. Prefira espaços e aplique uma largura de indentação por meio das configurações do editor e de um formatador.
• Deixar escalares ambíguos sem aspas. Coloque entre aspas identificadores e textos que se assemelham a booleanos, nulos, números ou timestamps.
• Permitindo chaves duplicadas. Configure o carregador ou linter para rejeitá-las.
• Assumindo que os comentários sobrevivem nas transições. Muitos carregadores baseados em objeto descartam comentários e formatação original.
• Excesso de âncoras e fusões. A reutilização pode reduzir a repetição, mas valores eficazes ocultos dificultam revisões e substituições.
• Pulando a validação de esquema. Um documento bem formado ainda pode conter chaves com erros de ortografia ou valores inseguros.

Como Usar YAML Corretamente

1. Defina um pequeno subconjunto suportado. Decida se o projeto permite âncoras, chaves de fusão, tags personalizadas, fluxos de múltiplos documentos e estilo de fluxo.
2. Prenda o analisador e o comportamento. Registre a biblioteca, versão YAML suportada, política de chaves duplicadas e modo de carregamento seguro.
3. Adicione linting e verificações de esquema. Execute-os antes da implantação para que erros de indentação e chaves desconhecidas falhem cedo.
4. Mantenha segredos fora do YAML comprometido. Referencie valores fornecidos pelo ambiente ou gerenciador de segredos de acordo com o mecanismo documentado da aplicação.
5. Revise a configuração eficaz. Quando a herança ou fusão existir, forneça um comando que renderize as configurações finais sem expor valores secretos.
6. Use outro formato quando a fronteira mudar. Prefira JSON para APIs públicas e formatos analíticos tipados para grandes conjuntos de dados.

Conclusão

YAML é uma linguagem de serialização flexível cujo estilo de bloco legível a torna especialmente útil para configuração. Sua conveniência vem com uma superfície de interpretação maior: indentação, esquemas, tags, âncoras, aliás, chaves duplicadas e opções de analisador podem afetar os valores carregados. Um fluxo de trabalho YAML confiável restringe o conjunto de recursos suportados, usa carregamento seguro, valida os dados resultantes e mantém a configuração amigável ao humano separada da troca de alta volume por máquina.