Passei uma tarde no ano passado depurando um arquivo de valores Helm que um colega jurou estar correto Cada chave parecia certa O serviço se recusou a começar O culpado acabou sendo quatro personagens: NO como um código de país, não citado, em uma lista de regiões O analisador YAML lê-lo como o booleano false, o modelo renderizado false em um cabeçalho, e o pedido foi rejeitado downstream com uma mensagem de erro que não mencionou nem YAML nem Noruega Esse bug é famoso o suficiente para ter um nome - o problema da Noruega - e é apenas um de uma família de surpresas esperando em um formato que a maioria de nós trata como & quot; JSON com espaços em branco mais agradáveis."
tl;dr: o Conversor YAML para JSON analisa um documento YAML e imprime o JSON equivalente, resolvendo âncoras, aliases, mesclar chaves e bloquear escalares ao longo do caminho, Ver sua configuração como JSON mostra exatamente o que o analisador decidiu que seus valores significam - quais tipos ele inferiu, quais referências ele expandiu - antes que essa interpretação chegue a um cluster Ele é executado inteiramente em seu navegador.
Converter YAML para JSON não é apenas uma mudança de formato. É a auditoria mais rápida disponível do que sua configuração realmente contém. JSON não tem comentários, nem âncoras, nem digitação implícita além do que a sintaxe afirma abertamente, então a visualização JSON de um manifesto é a versão resolvida e inequívoca dele. Este guia cobre como o YAML mapeia no JSON, o tipo e os comportamentos de referência que causam incidentes reais e como usar o conversor quando você está depurando uma configuração, fazendo script contra um manifesto ou escrevendo um dispositivo elétrico de teste.
O que a conversão de YAML para JSON realmente faz?
A relação é definida, não incidental: o Especificação YAML 1.2 afirma que YAML é um superconjunto de JSON, então todo documento JSON já é válido YAML. YAML e JSON descrevem as mesmas três coisas: mapeamentos de chaves para valores, sequências ordenadas e escalares A conversão caminha pelo documento YAML e emite cada construção em seu equivalente JSON Um mapeamento de bloco se torna um objeto Uma sequência de blocos se torna um array Um escalar se torna uma string, número, booleano ou nulo, dependendo de como o esquema central do YAML o resolve.
A parte estrutural é desinteressante porque é mecânica A parte interessante é tudo o que a YAML pode expressar que a JSON não pode, porque é aí que o conversor tem que tomar uma decisão em seu nome:
| Recurso YAML | O que JSON recebe | Por que é importante |
|---|---|---|
Comentários (# ...) |
Caiu | JSON não possui sintaxe de comentários; a documentação em sua configuração não sobreviveu |
Âncoras e pseudônimos (&base, *base) |
Cópias expandidas | JSON não possui sintaxe de referência, portanto os blocos compartilhados são duplicados |
Mesclar chaves (<<: *base) |
Achatado no objeto | As chaves explícitas substituem as mescladas, de acordo com a especificação da chave de mesclagem |
| Escalares de bloco (` | , >`) |
Uma única corda com fugas |
Vários documentos (---) |
Uma série de documentos | Um pacote Kubernetes torna-se um array JSON, um elemento por recurso |
| Digitação implícita | Tipos resolvidos | Não citado 8080 torna-se um número, true um booleano, null um nulo |
Essa última linha é aquela que vale a pena olhar para JSON força cada valor a declarar seu tipo através da sintaxe: aspas significam string, números médios de dígitos nus YAML infere o tipo a partir da forma do texto Converter para JSON torna visível a inferência Se você esperava uma string de versão e JSON mostra a você 1.1 onde o YAML disse 1.10, você encontrou um bug que de outra forma teria enviado.
Por que YAML's a digitação implícita causa interrupções reais
O esquema central YAML 1.2 resolve um escalar não citado por padrão Dígitos tornam-se inteiros Dígitos com um ponto decimal ou expoente tornam-se flutuadores. true e false tornar-se booleanos. null e ~ torne-se nulo Todo o resto é uma string.
Isso parece organizado até que você atenda aos valores que se parecem com um tipo e são concebidos como outro:
- Portas e IDs.
port: 08080não é o número 8080. um zero à esquerda torna-o um número inteiro inválido sob o esquema principal, de modo que a maioria dos analisadores devolvem a string, e alguns mais antigos interpretam-no como octal. códigos postais, números de telefone e IDs de contas com zeros à esquerda têm o mesmo problema. - Versões.
version: 1.10é o flutuador1.1. O zero à direita desapareceu e nenhum analisador avisa. Compare isso com uma tag de contêiner e a pesquisa falhará. - Códigos de país e idioma. Sob YAML 1.1 - que PyYAML ainda segue por padrão, juntamente com um monte de Ruby e ferramentas Java mais antigas -
y,n,yes,no,on, eoffsão booleanos.NO,ON, eNAsão códigos perfeitamente comuns de duas letras no mundo real. - Tempos e sexagesimais. YAML 1.1 também analisa
12:30como um número base 60, que é 750. strings semelhantes a Cron ou duração podem desaparecer em números inteiros.
Cada um deles é uma corrupção de dados silenciosa, não um erro de análise O documento é válido, o pipeline é verde e o valor está errado O conversor & #39; s Mantenha as cordas opção existe exatamente para esta classe de investigação: ligue-o e cada escalar simples volta como uma string, para que você possa comparar as duas conversões lado a lado e ver precisamente quais valores o analisador estava reinterpretando O que quer que o JSON mostre sem essa opção é o que seu analisador de produção está mais provavelmente fazendo hoje.
A correção em seu YAML de origem é sempre a mesma: cite qualquer coisa cujo significado seja textual. port: "8080", version: "1.10", region: "NO". As cotações não custam nada e removem toda a categoria de bug Se você gerar YAML a partir de JSON em vez de escrevê-lo, o Conversor JSON para YAML aplica essa citação automaticamente para valores ambíguos.
Como âncoras, pseudônimos e chaves de mesclagem convertem
As âncoras são YAML' s resposta à repetição Você marca um nó com &name, então faça referência a isso mais tarde com *name:
defaults: &defaults
restartPolicy: Always
terminationGracePeriodSeconds: 30
web:
<<: *defaults
replicas: 3
worker:
<<: *defaults
terminationGracePeriodSeconds: 120
JSON não tem como dizer & quot; o mesmo valor que sobre lá." Então o conversor expande cada referência em uma cópia completa A saída acima se torna três objetos, cada um carregando o seu próprio restartPolicy, e o JSON é mais longo do que o YAML que o produziu Isso não é uma falha na conversão - é o que o YAML significa, escrito.
A chave de mesclagem << merece sua própria nota porque sua regra de precedência é fácil de retroceder As chaves escritas explicitamente no mapeamento filho vencem as chaves puxadas pela mesclagem No exemplo, worker acaba com um período de carência de 120, não 30, independentemente de a linha de mesclagem aparecer acima ou abaixo da chave explícita O conversor implementa essa regra, então o JSON mostra a configuração efetiva, pós-mesclagem - que geralmente é a coisa que você realmente queria inspecionar.
Seguem-se dois usos práticos disto Primeiro, quando uma configuração usa ancoragem pesada, a conversão para JSON é a forma mais rápida de responder ao & quot; para que é que este ambiente resolve de facto?" sem executar a implementação Segundo, se um alias não tiver âncora correspondente - um resultado comum de dividir um ficheiro grande em vários - o conversor reporta - o como um erro com o número da linha, em vez de produzir silenciosamente um nulo.
Como os escalares de bloco convertem
YAML tem duas maneiras de incorporar texto multilinha e eles se comportam de maneira diferente:
- Literal (
|) mantém cada quebra de linha exatamente como escrita Use-a para scripts de shell, certificados PEM, SQL e qualquer coisa sensível a espaços em branco. - Dobrado (
>) une linhas consecutivas com um único espaço e trata uma linha em branco como uma quebra de parágrafo Use-a para prosa que você deseja embrulhada no arquivo de origem, mas unida no valor.
Ambos aceitam um indicador de pompa que controla as novas linhas à direita O padrão, chamado clipping, mantém exatamente uma nova linha à direita A menos (|-) retira todas as novas linhas. Um mais (|+) mantém cada um deles.
Em JSON, tudo isso desmorona em uma string com \n escapes. Essa é outra razão pela qual a visualização JSON é útil: é inequívoca. A | bloco cuja última linha foi recuada acidentalmente, ou a > bloquear que uniu duas linhas dobradas que você pretendia manter separadas é óbvio em JSON e quase invisível em YAML. O conversor também lida com o case que captura implementações ingênuas - a # o caractere dentro de um bloco literal é conteúdo, não um comentário, o que importa no momento em que você incorpora um script de shell começando com um shebang.
Como usar o YAML para JSON Converter
Passo 1: Cole o documento
Cole qualquer YAML no painel de entrada: um manifesto do Kubernetes, a docker-compose.yml, um fluxo de trabalho do GitHub Actions, um manual do Ansible, a .gitlab-ci.yml, ou uma configuração de aplicação. Arquivos multi-documentos com --- os separadores estão bem - cada documento é analisado de forma independente Clique em Carregar amostra para começar a partir de uma Implantação realista que exerce mapas aninhados, sequências, uma coleção vazia e um escalar de blocos literais.
A única coisa que não irá analisar é o recuo com caracteres de tabulação O YAML proíbe as tabulações de uma vez, e o conversor diz isso com o número da linha ofensiva em vez de adivinhar Os editores que inserem uma tabulação no Enter são a fonte habitual; a maioria tem um & quot; converter o recuo para o spaces" comando que corrige todo o arquivo de uma vez.
Passo 2: Escolha a forma de saída
Escolha 2 espaços, 4 espaços, ou Minificado. Minificado é o que você deseja quando está prestes a colar o resultado em um curl corpo ou uma variável de ambiente A saída recuada é o que você quer quando um ser humano tem que lê-la.
Classificar chaves reescreve as teclas de objeto em ordem alfabética em todos os níveis Isso é inestimável ao comparar duas versões de uma configuração: dois arquivos que diferem apenas na ordem das teclas produzem JSON classificado idêntico, portanto, um diff mostra apenas mudanças reais Alimente ambas as saídas no json diff ferramenta e você obtém uma comparação estrutural precisa em vez de uma linha por linha.
Mantenha as cordas desativa a coerção escalar, como descrito acima Use-a quando quiser ver o texto bruto de cada valor, ou quando um consumidor downstream tratar tudo como uma string de qualquer maneira.
Passo 3: Converta e leia os erros
clique converter. Se o documento estiver bem formado, o JSON aparecerá abaixo junto com a contagem de linhas, contagem de chaves, tamanho de bytes e - para fluxos de vários documentos - quantos documentos foram encontrados.
Se não estiver bem formado, o erro nomeia a linha As mensagens cobrem as falhas que realmente acontecem na prática: guias usadas para recuo, uma linha recuada inconsistentemente com seus irmãos, uma string citada não terminada, um alias sem âncora, uma chave de mesclagem apontando para algo que não é um mapeamento Um número de linha transforma uma caça de cinco minutos em uma correção de cinco segundos.
Etapa 4: copie, baixe ou continue
Copie o JSON para sua área de transferência ou baixe-o como um .json arquivo. A partir daí, as próximas etapas comuns são a impressão bonita e a validação com o formatador json, gerando tipos para um carregador de configuração com json para digitar, ou derivando um contrato para validação de IC com o Gerador de esquema JSON.
Fluxos de trabalho reais que isso se encaixa
Depurar um manifesto que o & quot; parece bem e quot;
Quando uma implantação se comporta inesperadamente e o YAML lê corretamente, converta-o Nove vezes em cada dez o JSON mostra o problema imediatamente: um valor que se tornou um booleano, uma chave aninhada um nível mais rasa do que o pretendido por causa de um espaço perdido, uma âncora que se expandiu para algo obsoleto A visualização JSON remove a ambiguidade do espaço em branco que tornou o bug invisível.
Script contra configuração
Os scripts Shell e Node lidam com JSON nativamente; YAML precisa de uma dependência Quando preciso extrair cada tag de imagem de um pacote de manifestos, convertendo-a primeiro em JSON e passando jq é mais rápido do que adicionar uma biblioteca YAML a um script descartável O suporte a vários documentos do conversor & #39; é importante aqui - um pacote Kubernetes de seis recursos se torna uma matriz JSON que você pode iterar.
Dispositivos de teste de construção
Os testes de integração geralmente precisam de um objeto de configuração em vez de um arquivo de configuração A conversão do manifesto real para JSON oferece um dispositivo elétrico que garante corresponder à forma de produção, que é um ponto de partida muito melhor do que um objeto que você digitou na memória. Emparelhe-o com json para digitar e seu dispositivo elétrico vem com tipos.
Revendo a configuração em uma solicitação pull
Diferenças de YAML fortemente ancoradas são difíceis de ler porque uma mudança de uma linha para uma âncora muda silenciosamente cada consumidor Convertendo ambas as versões com Classificar chaves habilitado e diffing o JSON mostra o raio de explosão verdadeiro: cada valor resolvido que mudou, não apenas a linha que foi editada.
Migrando entre ferramentas
Muitas plataformas aceitam JSON, mas não YAML, ou vice-versa A conversão geralmente é toda a migração. Quando você precisa voltar para o outro lado - JSON na mão, YAML necessário - o Conversor JSON para YAML fecha o loop e o Validador YAML confirma as análises de resultados antes de cometê-las.
YAML e JSON comparados
| Dimensão | yaml | JSON |
|---|---|---|
| comentários | sim | não |
| Edição humana | Baseado em indentação, fácil de desnatar | Pontuação pesada, prolixa |
| Analisando máquina | Analisadores mais lentos e maiores, mais casos de borda | Rápidos, pequenos analisadores por toda parte |
| Inferência de tipo | Implícito, dependente do esquema | Explícito da sintaxe |
| referências | Âncoras, pseudônimos, mesclar chaves | nenhum |
| Vários documentos por arquivo | Sim, via --- |
não |
| Casa típica | Configurar arquivos, pipelines CI, manifestos | APIs, intercâmbio de dados, armazenamento |
YAML 1.2 é formalmente um superconjunto de JSON, então todo documento JSON já é válido YAML O inverso não é verdadeiro, e é por isso que converter YAML para JSON é uma operação com perdas em exatamente uma direção: comentários e estrutura de referência são descartados, enquanto os dados são preservados Se o seu YAML tiver comentários que você se importa, mantenha o YAML como a fonte da verdade e trate o JSON como um artefato derivado.
Privacidade: por que isso é executado no seu navegador
Os arquivos Config estão entre os artefatos de texto simples mais sensíveis que uma equipe possui Eles carregam nomes de host internos, nomes de cluster, caminhos de registro, contas de serviço, identificadores de banco de dados e - apesar das melhores intenções de todos e #39; - a credencial ocasional que ainda não chegou a um gerenciador secreto.
O conversor é JavaScript do lado do cliente Seu documento é analisado na página, o JSON é produzido na página e nenhuma solicitação leva seus dados para qualquer lugar Carregue a ferramenta uma vez e ela continua trabalhando com a rede desligada, o que é um hábito razoável para qualquer coisa em que você cole um manifesto Este é o mesmo princípio por trás de cada ferramenta no site, e o raciocínio é explicitado no guia em Privacidade de dados em ferramentas online. Se você estiver montando um kit de ferramentas de navegador de uso geral, o Kit de ferramentas para desenvolvedores web guia cobre o que mais pertence a ele.
Limitações que vale a pena conhecer
Nenhum conversor que cabe em uma guia do navegador implementa todos os cantos da especificação YAML, e é mais útil ser específico sobre as bordas do que implicar que não há nenhuma.
Chaves de mapeamento complexas - o explícito ? key formulário onde a chave é em si uma sequência ou mapeamento - não são suportados, porque as teclas de objeto JSON devem ser strings Digite tags como !!binary ou personalizado !MyType as diretivas não são interpretadas; o valor aparece como texto. Os valores especiais do flutuador .inf, -.inf, e .nan são preservados como strings, já que JSON não tem literal para eles e se converte silenciosamente em null perderia mais informações do que economizaria Diretivas como %YAML 1.2 são ignorados em vez de postos em prática.
Nenhum destes aparece em arquivos comuns do Kubernetes, Compose, Actions ou Ansible Se você clicar em um, você está trabalhando com um documento escrito para uma linguagem específica' s biblioteca YAML, e essa biblioteca' s próprio dumper é a ferramenta certa.
FAQ
Como faço para converter YAML para JSON online?
Cole seu YAML no painel de entrada e clique em Converter. O analisador lê o documento, resolve âncoras e escalas de blocos e imprime JSON formatado que você pode copiar ou baixar. Tudo acontece no seu navegador, portanto, nenhum arquivo é carregado.
JSON é um subconjunto de YAML?
Sim. O YAML 1.2 foi redefinido como um superconjunto estrito de JSON, portanto, qualquer documento JSON válido também é válido YAML. O inverso não é verdadeiro: YAML adiciona comentários, âncoras, escalas de blocos, vários documentos por arquivo e chaves não string, nenhum dos quais JSON pode expressar diretamente.
Como as âncoras e aliases YAML são convertidos em JSON?
JSON não tem sintaxe de referência, então cada alias é expandido em uma cópia completa do valor que sua âncora define Uma configuração que reutiliza um bloco padrão três vezes produz três objetos JSON idênticos A saída é, portanto, maior que a fonte YAML, mas semanticamente idêntica.
O que acontece com as teclas de mesclagem, como o suporte de ângulo duplo?
O mapeamento referenciado é mesclado no objeto atual. Chaves escritas explicitamente no mapeamento filho de vitórias sobre chaves mescladas, que correspondem ao comportamento da especificação de chave de mesclagem YAML e do Kubernetes e das ferramentas ansible.
Por que meu YAML falhou com um erro nas guias?
YAML proíbe caracteres de tabulação para indentação - a especificação permite apenas espaços Os editores que inserem guias em Enter são a causa usual Converter as guias principais em espaços, o que a maioria dos editores pode fazer para um arquivo inteiro de uma só vez, e o documento irá analisar.
Posso converter um arquivo YAML multi-documento com separadores de documentos?
Sim. cada documento entre os marcadores separadores é analisado independentemente e o resultado é uma matriz JSON com um elemento por documento, na ordem de origem Um arquivo de documento único retorna o objeto em si, não uma matriz de um elemento.
Os números das portas e as strings de versão manterão seu tipo?
Os escalares simples são resolvidos pelo esquema central YAML, então um 8080 não citado se torna o número 8080 e um 1.10 não citado se torna 1.1. Cite o valor em seu YAML para mantê-lo como uma string ou ligue a opção Manter strings para desligar toda coerção escalar.
Como os escalares de blocos literais e dobrados se convertem?
Um bloco literal mantém cada nova linha, então ele se torna uma string JSON com quebras de linha escapadas Um bloco dobrado une linhas consecutivas com um espaço e trata linhas em branco como quebras de parágrafo Os indicadores de pompa são respeitados: um menos deixa cair a nova linha à direita e um mais mantém cada linha em branco à direita.
