YAML null

O que significa null em um arquivo YAML?

YAML é um formato de texto para organizar informações em pares de chave e valor, usando recuos em vez de chaves e colchetes. Ele é comum em arquivos de configuração de sistemas, em pipelines de implantação e em documentos que descrevem APIs.

Null é a forma de dizer que um campo existe, mas não tem valor. Não é zero, não é texto vazio e não é falso: é a indicação explícita de que ali não há informação. Por exemplo, um campo de complemento de endereço pode ficar null quando o cliente mora em uma casa sem número de apartamento.

Como escrever null em YAML?

Na especificação mais usada do YAML, são reconhecidas como null as palavras null, Null e NULL, o símbolo til (~) e também a chave sem nenhum valor depois dos dois-pontos. Assim, as linhas complemento: null, complemento: ~ e complemento: produzem o mesmo resultado ao serem lidas por um sistema.

Um cuidado importante: se a palavra estiver entre aspas, como complemento: "null", ela deixa de ser null e passa a ser um texto com as letras n, u, l, l. Esse detalhe causa muitos erros difíceis de perceber.

Qual a diferença entre null, texto vazio e campo ausente?

São três situações distintas. Com null, o campo aparece, mas sem valor. Com texto vazio (duas aspas sem nada dentro), o campo tem um valor, que é um texto de tamanho zero. Com o campo ausente, a chave simplesmente não está no arquivo.

Muitos sistemas tratam essas situações de forma diferente. Uma API pode aceitar o campo ausente, mas recusar o texto vazio, ou interpretar null como uma ordem para apagar um valor já salvo. Por isso, vale conferir na documentação qual comportamento é esperado em cada campo.

Por que o YAML null importa na integração com uma API fiscal?

APIs fiscais costumam receber dados em JSON, mas muitas equipes guardam configurações, modelos de requisição ou a própria descrição da API em YAML. Quando esse conteúdo é convertido, o null do YAML vira o null do JSON, e é isso que chega ao emissor.

Nos documentos fiscais eletrônicos, como NF-e, NFC-e e CT-e, o XML final segue um esquema rígido. Em geral, campos opcionais sem informação devem ser omitidos, e não enviados vazios, pois tags vazias costumam gerar falha de validação do esquema e rejeição. Entender como seu sistema trata o null ajuda a evitar que um campo sem valor vire uma tag vazia ou um texto "null" dentro da nota.

Quais erros mais comuns envolvem YAML null?

Os mais frequentes são: colocar null entre aspas e enviar a palavra como texto; esquecer o valor de uma chave e, sem querer, gerar null; e confundir null com zero em campos numéricos, como valor de desconto ou alíquota. No caso de valores tributários, zero e ausência de valor podem ter significados fiscais diferentes.

Uma boa prática é validar os dados com um esquema, como o JSON Schema, antes de enviá-los à API, definindo quais campos aceitam null e quais são obrigatórios.

Exemplos de YAML null

• Em um arquivo de configuração de um ERP, a linha certificado_senha_secundaria: ~ indica que não existe uma segunda senha cadastrada para aquela empresa emissora.
• Na descrição de uma API de emissão de NF-e escrita em YAML, um campo de complemento de endereço do destinatário é marcado como podendo ser null, sinalizando que ele é opcional.
• Um desenvolvedor escreve inscricao_municipal: "null" entre aspas em um modelo de NFS-e; o sistema envia a palavra null como texto e o emissor retorna erro de validação.
• Um modelo de requisição em YAML define valor_desconto: null; ao converter para JSON, o campo chega como null e o sistema emissor entende que não houve desconto informado, em vez de desconto igual a zero.