A primeira vez que o YAML me queimou corretamente, era um código de país. Eu estava movendo uma configuração de localidade de arquivos JSON do projeto Laravel para um formato YAML compatível com a implantação, convertendo manualmente à medida que eu fui porque "está apenas mudando o aparelho para recuo." Uma das entradas foi a Noruega: "country": "NO". No YAML, sem citação, isso' não é uma string - sob as regras do YAML 1.1, PyYAML e muitos outros analisadores ainda se aplicam NO é o booleano false. O script de implantação, escrito em Python, avaliava alegremente os usuários noruegueses como country: false e os encaminhou para o local de fallback Este bug tem um nome - a comunidade o chama de problema da Noruega - e descobri isso de maneira artesanal, um ticket de suporte confuso de cada vez.
A conversão manual de JSON para YAML parece trivial e na verdade é um campo minado, porque os dois formatos têm ideias muito diferentes sobre o que significa uma palavra nua. Em JSON, tudo é explícito: strings têm aspas, números não, true/false/null são palavras-chave, fim da história. No YAML, um escalar não aspas recebe interpretado: no torna-se falso, 3000 torna-se um número inteiro, 1.10 torna-se o flutuador 1.1 (Adeus, string de versão), 08 engasga alguns analisadores como um octal inválido, e um valor com um espaço de dois pontos perdido torna-se um mapa aninhado quando você menos espera. Cada um deles é uma corrupção silenciosa de dados - o arquivo analisa tudo bem, os tipos estão simplesmente errados.
um Conversor JSON para YAML isso entende essas regras dá a você a legibilidade para a qual o YAML foi inventado sem a roleta de tipos Aquele que construí para o Toolz.dev detecta todos os escalares ambíguos - sósias booleanas, sósias numéricas, valores legados do YAML 1.1, strings com caracteres especiais - e cita exatamente esses, então o que era uma string no seu JSON ainda é uma string depois que a próxima ferramenta analisa o YAML. Isso " exatamente aqueles e quot; importa: citar tudo Seria seguro também, mas a saída para de parecer idiomática YAML e o idiomático é o ponto principal.
Este guia aborda como a conversão lida com as arestas afiadas do YAML, por que JSON já é tecnicamente YAML (e por que esse fato não ajuda você), e os fluxos de trabalho Kubernetes, Ci e Docker compõem onde essa conversão acontece semanalmente.
tl;dr: Cole JSON no Conversor Toolz.dev JSON para YAML, escolha o recuo de 2 ou 4 espaços e obtenha o YAML estilo bloco limpo com citações seguras para o tipo -
"3000"Fica uma corda,"no"Fica uma corda,"1.10"Fica uma versão. A ordem das chaves é preservada, as coleções vazias são reveladas como[]e{}, e tudo roda no cliente para que as configurações com segredos nunca saem do seu navegador. Volta de ida e volta com o Validador YAMLe formatar a fonte primeiro com o formatador json.
JSON já não é válido YAML?
Sim - e it' s o mais inútil & quot;yes" na gestão de configuração YAML 1.2 foi explicitamente concebido como um superconjunto de JSON: cada documento JSON válido analisa como YAML válido Você poderia colar JSON bruto em um manifesto Kubernetes e kubectl aceitaria.
Ninguém faz isso, porque a razão pela qual o YAML existe é ergonomia humana. Manifestos do Kubernetes, fluxos de trabalho do GitHub Actions, arquivos Docker Compose, playbooks Ansible, configurações do Home Assistant - estes são YAML porque as pessoas os lêem e editam à mão constantemente e replicas: 3 em um bloco recuado, escaneia melhor do que {"replicas":3} Aninhado em chaves. Quando alguém diz "converter JSON em YAML" significa que eles significam estilo bloqueado YAML: recuo em vez de chaves, - Traços em vez de matrizes entre colchetes, sem aspas onde nenhuma é necessária.
Essa última cláusula é onde vive a dificuldade. Ir de tudo - sintaxe explícito para JSON significar sintaxe mínima de YAML Decidir, para cada string, se pode perder suas cotações com segurança- e essa decisão requer conhecer as regras de resolução escalar do YAML' s melhor do que a maioria dos humanos faz de forma confiável às 17h de uma sexta-feira. Esse e no 39; é o trabalho real de um conversor; a parte entre colchetes e indicação é trivial.
O que se quebra silenciosamente quando você converte manualmente?
Os casos de falha se enquadram em quatro famílias e eu atingi cada uma delas em configurações reais:
Sequinhos booleanos. YAML 1.1 resolve yes, no, on, off, y, n (em vários invólucros) como booleanos e YAML 1.2 mantém true/false. PyYAML - ainda a biblioteca YAML padrão na maioria das bases de código Python - implementa 1.1. Então "debug": "no" convertido manualmente para debug: no torna-se debug: false Em suas ferramentas de implantação do Python. O problema da Noruega (NO → false) e seu primo o problema de Ontário (ON → true) são os maiores sucessos desta família.
Número parecido com o mesmo. "port": "3000" convertido em port: 3000 agora é um número inteiro. Kubernetes não importa & #39; importa-se em alguns campos e falha difícil em outros - valores env var, por exemplo, devem ser strings, e kubectl apply rejeitará um número inteiro com um erro que nomeie o campo, mas não o por que. As strings de versão são piores porque nada falha: version: 1.10 Analisa como o flutuador 1.1e seu script de implantação relata alegremente a versão errada para sempre Zeros principais - códigos postais, números de telefone, IDs com aparência octal como 0755- complete a família.
Personagens especiais. Um dois pontos seguido por um espaço dentro de um valor não aspas inicia um mapeamento (message: error: not found É um erro de análise ou um mapa aninhado, dependendo do analisador). um # Inicia um comentário de valor médio. direção *, &, ! Colide com a âncora, alias e sintaxe de tags de Yaml. Strings com novas linhas precisam de escalonamento ou escalas de bloco.
A string vazia. O vazio não citado em YAML é null, não "". Qualquer campo JSON que contém uma string vazia deve sair cotado ou muda de tipo.
o conversor verifica cada string em relação a todas as quatro famílias e cita aquelas que precisam dela - e apenas aquelas. production sai nua porque é inequívoco; "3000", "no", "1.10", e "" Saia citado porque eles não são. Também há uma opção "Cite todas as strings" para quando você está alimentando um analisador em que você não confia e deseja que a resolução escalar zero aconteça.
Como você converte JSON em YAML com a ferramenta?
Etapa 1: cole seu JSON
Quaisquer trabalhos JSON válidos - objetos, matrizes, aninhamento profundo, unicodeO botão Carregar amostra oferece uma configuração de serviço realista que exerce os casos interessantes: uma porta de string numérica, um booleano, um array vazio, mapas aninhados. Se sua entrada tiver problemas de sintaxe, o conversor relata o erro exato do analisador & #39; em vez de converter um documento truncado; para caçar onde O erro está em um grande blob, o formatador json é o melhor microscópio.
Passo 2: Escolha o recuo
Dois espaços ou quatro. dois é a convenção esmagadora - Kubernetes docs, exemplos de ações do GitHub, referências de composição do Docker e o yamllint todos os padrões o usam - mas algumas equipes padronizam quatro quanto à legibilidade no aninhamento profundo. Seja qual for a sua escolha, o conversor é consistente sobre isso, incluindo o caso sutil de itens de lista sob uma chave, onde o recuo manual inconsistente é uma fonte clássica de & quot; valores de mapeamento não são permitidos aqui e quot; erros.
Etapa 3: converter e revisar
A saída aparece com contagens de linha e bytes. Deslize-o uma vez - não para correção (isso & #39; s o trabalho conversor & #39; s), mas para verificar a sanidade das decisões de cotação em relação às suas expectativas Vendo PORT: "3000" citado enquanto NODE_ENV: production Não é a ferramenta que informa quais valores eram perigosos.
Etapa 4: Copie ou faça o download
Copie para a área de transferência para colar em um manifesto existente ou faça o download como um .yaml arquivo. A saída usa apenas espaços - YAML proíbe guias para recuo, o que vale a pena saber quando você editar o arquivo posteriormente em um editor configurado para recuo de guias.
JSON vs YAML: Quando cada formato vence?
| JSON | yaml | |
|---|---|---|
| Ler/Editado por | Máquinas, APIs | Humanos, equipes de operações |
| comentários | não está na especificação | # comentários - o recurso matador para configurações |
| digite explicitidade | Total - as cotações decidem tudo | Resolução escalar - contexto decide |
| cordas multilinhas | \n apenas escapa |
Escalares de bloco (` |
| Analisar velocidade e onipresença | Mais rápido, em todos os lugares | Parsers mais lentos e mais pesados |
| armas de fogo | Trasting Victions, isso é sobre isso | Problema da Noruega, guias, desvio de recuo, truncamento de versão |
| habitat natural | cargas úteis de API, package.json, intercâmbio de dados |
Kubernetes, CI Pipelines, Compor, Ansible |
O padrão atrás da mesa: JSON vence onde quer que uma máquina escreva e uma máquina leia; YAML vence onde quer que uma máquina leia, mas um ser humano escreve. A configuração fica diretamente na segunda categoria, e é por isso que a direção JSON-para-YAML é a comum - os dados começam a vida em uma API ou uma exportação de banco de dados e precisam se tornar algo que uma equipe de operações pode manter A viagem inversa, YAML de volta ao JSON legível por máquina, é o que o Validador YAML alças - colar YAML, obter validação mais o equivalente JSON.
Quais são os fluxos de trabalho diários para esta conversão?
Manifestações do Kubernetes da saída da API
kubectl get deployment my-app -o json dá-lhe JSON; o manifesto que você verifica no Git é YAML. Converter respostas da API em YAML limpo é a maneira mais rápida de inicializar um manifesto a partir de um recurso ao vivo - converter, retirar o servidor preenchido status e metadata.managedFields blocos e você tem um ponto de partida declarativo. A cotação de tipo seguro ganha seu suporte aqui: valores env no Kubernetes ser necessário Be Strings e a insistência do conversor em citar "3000" é a diferença entre kubectl apply Sucesso e falha.
Configuração do pipeline de
As Acções do GitHub e o CI do GitLab são apenas do YAML Quando as etapas do fluxo de trabalho do I & #39; m geram programaticamente - uma matriz de versões do PHP e do Nó para testar o WP Adminify contra, digamos - o gerador produz naturalmente o JSON, e o último passo é a conversão As cadeias de versões nas matrizes de teste são exatamente os valores que são mutilados pela conversão ingênua: uma matriz de ["1.9", "1.10", "1.11"] Testes convertidos manualmente sem aspas em relação ao PHP 1.1 duas vezes. o Coleção de ferramentas de codificação Abrange mais esse padrão de geração e conversão.
docker compõe da saída de inspeção
docker inspect emite JSON; docker-compose.yml quer YAML. Reverse-engineering um arquivo Compose de um contêiner em execução - portas, volumes, env - é um trabalho de conversão e poda Matrizes vazias e objetos se convertem em [] e {} Sintaxe do fluxo, que componha aceita e que mantém o estágio de poda legível.
Tornando a configuração revisável
Este é subestimado: as configurações JSON com dezenas de chaves aninhadas são miseráveis na revisão de código, em parte porque não podem carregar comentários. Converter para YAML permite anotar por que rateLimit é 250 ao lado do valor. Para a revisão em si, emparelhar a conversão com um diferencial estrutural O de antes/depois de JSON mantém a pergunta "O que realmente mudou" é honesta, enquanto a versão YAML lida com o "Por quê."
Documentos do OpenAPI e do esquema
As especificações OpenAPI são comumente de autoria em YAML, mas geradas e servidas como JSON. Converter uma especificação gerada em YAML para edição humana - validando então a viagem de ida e volta - é um fluxo de trabalho padrão da equipe da API, e as garantias de fidelidade (ordem da chave preservada, tipos citados) significam que a versão YAML permanece difável em relação ao seu ancestral JSON.
Por que a preservação das ordem-chaves é importante?
De acordo com a especificação JSON, a ordem das chaves do objeto não tem significado - {"a":1,"b":2} e {"b":2,"a":1} são o mesmo objeto. Portanto, um conversor pode classificar as teclas em ordem alfabética e estar tecnicamente correta. Também seria praticamente hostil, porque os arquivos de configuração são compreender Em ordem: uma implantação do Kubernetes é natural apiVersion, kind, metadata, spec- classificá-los em ordem alfabética produz um manifesto que analisa de forma idêntica e parece uma nota de resgate.
O conversor emite chaves na ordem de origem. Seu modelo mental do documento sobrevive à conversão, o YAML se diferencia de forma limpa em relação às conversões anteriores da mesma fonte e ordenações convencionais (nome antes do valor, apiVersion Primeiro) mantenha-se convencional. Se você carência ordenação canônica para fins de comparação, que & #39; é uma preocupação de ferramenta diferente - o verificador de diff json Compara por chave independentemente da ordem, que é a camada certa para esse problema.
É seguro converter configurações contendo segredos?
A configuração é o texto mais secreto e denso que um desenvolvedor lida - URLs de banco de dados com senhas incorporadas, tokens de API em blocos env, nomes de host internos que mapeiam sua infraestrutura It' s também exatamente o que as pessoas colam em conversores online, geralmente no meio da implantação, geralmente com pressa.
o Conversor Toolz.dev é executado inteiramente em seu navegador: análise, análise escalar, serialização - tudo isso é JavaScript do lado do cliente, nenhuma solicitação de rede carrega seus dados e a ferramenta continua trabalhando com seu corte de conexão Isso e #39; é um fato da arquitetura, não uma promessa de política de privacidade. A filosofia de design que prioriza o navegador por trás de toda a caixa de ferramentas está definida no Guia do kit de ferramentas para desenvolvedores web; Esta ferramenta é aquela que a filosofia se aplicou ao tipo de documento mais sensível em seu fluxo de trabalho.
A ressalva óbvia: a conversão do lado do cliente protege o conversão. Onde você cola a saída depois é sua própria decisão de segurança.
FAQ
Como faço para converter JSON para YAML online?
Cole seu JSON no Conversor JSON para YAML, escolha indentação de 2 ou 4 espaços e clique em Converter Você obtém YAML estilo bloco com cotação segura para o tipo, pronto para copiar ou baixar como um arquivo.yaml A conversão é executada inteiramente em seu navegador - nada é carregado.
JSON já é válido YAML?
Tecnicamente sim - YAML 1.2 é um superconjunto de JSON, portanto, qualquer documento JSON válido é analisado como YAML. Mas a sintaxe JSON derrota o propósito de legibilidade do YAML' A conversão produz YAML estilo bloco com recuo em vez de chaves, que é o que o Kubernetes manifesta, os fluxos de trabalho CI e os arquivos Compose esperam que os humanos leiam e editem.
Qual é o problema da Noruega no YAML?
Sob as regras escalares YAML 1.1, que analisadores como PyYAML ainda se aplicam, os valores não citados não, sim, na e fora da análise como booleanos - então o código do país NO silenciosamente se torna falso O conversor evita isso citando automaticamente qualquer string que um analisador YAML possa interpretar como booleana, numérica ou nula.
As strings numéricas como "3000" ficarão strings após a conversão?
Sim. O conversor detecta strings que se parecem com números e as cita na saída, então "3000" permanece uma string em vez de se tornar o inteiro 3000. Isso é importante para portas, números de versão como "1.10" (que, de outra forma, truncariam para o float 1.1), códigos postais e IDs com zeros à esquerda.
O conversor preserva a ordem das minhas chaves JSON?
Sim. As chaves são emitidas na ordem em que aparecem no JSON de origem As chaves de classificação seriam tecnicamente válidas - a ordem do objeto JSON não carrega significado por RFC 8259- mas a ordem da fonte mantém as configurações legíveis em sua estrutura convencional e mantém o YAML difável em relação à sua fonte JSON.
Posso usar a saída diretamente no Kubernetes ou no Docker Compose?
Sim. A saída é YAML estilo bloco padrão recuado com espaços (nunca tabs), que kubectl, Docker Compose, GitHub Actions, e GitLab CI todos aceitam Valores que devem ser strings - como valores de var de Kubernetes env - sair citado, evitando os erros de tipo kubectl levanta em números não cotados.
Como faço para converter o YAML de volta para JSON?
use o Validador YAML no Toolz.dev - ele analisa seu YAML, relata quaisquer erros de sintaxe e gera o JSON equivalente. Juntamente com o conversor JSON para YAML, ele oferece uma viagem completa de ida e volta entre os dois formatos.
É seguro converter arquivos de configuração que contêm segredos?
Sim. a conversão é executada inteiramente em JavaScript no seu navegador - nenhuma solicitação de rede transporta seus dados, nada é armazenado ou registrado e a ferramenta funciona offline Configurações com credenciais de banco de dados, tokens de API ou nomes de host internos nunca saem da sua máquina.
YAML' s legibilidade é real, e assim são suas arestas vivas - o formato resolve tipos de contexto, e contexto é exatamente o que mão-conversão fica errado Um conversor que conhece as regras escalares dá-lhe a configuração legível sem o tipo silencioso corrupção: Converta seu JSON, dê uma olhada na citação que escolheu e envie um manifesto onde a Noruega ainda é um país.
