Aula de Laboratório — Formatos de Arquivo de Configuração

Ferramentas: VS Code · terminal (Python/Node para validar)

---

1. Objetivos de aprendizagem

Ao final desta aula, o aluno será capaz de:

• Identificar um formato pela extensão e pela aparência do conteúdo.
• Ler e editar arquivos INI, TOML, JSON, YAML, CONF, JS e front matter de Markdown.
• Reconhecer as armadilhas de sintaxe mais comuns de cada um.
• Validar cada formato com uma ferramenta simples.

Pontos de commit

Os cartões "Ponto de commit" marcam cada tarefa avaliada. Muitas pedem que você crie um arquivo de um formato — o commit registra a entrega.

---

2. Por que isso importa

Durante o semestre você vai encontrar (e editar!) muitos formatos:

Extensão	Formato	Onde aparece no curso	Pista visual
.ini	INI	platformio.ini	[secao] e chave = valor; comentário ;
.toml	TOML	wokwi.toml	[tabela], strings entre aspas; comentário #
.json	JSON	diagram.json, flows.json	chaves e colchetes, aspas duplas, sem comentário
.yml / .yaml	YAML	docker-compose.yml, workflows	indentação, chave: valor, listas com -
.conf	(varia)	mosquitto.conf	diretiva valor; comentário #
.js	JavaScript	settings.js, docusaurus.config.js	module.exports, //; é código
.md / .mdx	Markdown	as próprias aulas	texto + front matter YAML entre ---
.csv	CSV	notas.csv	valores separados por vírgula

Identifique pelo conteúdo, não só pela extensão

A extensão é uma dica, mas o conteúdo confirma: viu [algo] no topo? INI ou TOML. Só chaves { } e aspas duplas? JSON. Indentação com chave:? YAML. module.exports? JavaScript.

---

3. Os mesmos dados em 4 formatos

Repare como a mesma informação (um dispositivo com nome, porta e uma lista de tags) muda de cara em cada formato.

JSON

{
  "dispositivo": {
    "nome": "esp32",
    "porta": 1883,
    "tags": ["wifi", "mqtt"]
  }
}

YAML

dispositivo:
  nome: esp32
  porta: 1883
  tags:
    - wifi
    - mqtt

TOML

[dispositivo]
nome = "esp32"
porta = 1883
tags = ["wifi", "mqtt"]

INI

[dispositivo]
nome = esp32
porta = 1883
tags = wifi, mqtt

INI não tem tipos nem listas nativas: tudo é texto. A "lista" aqui é só uma string separada por vírgula que o programa interpreta.

---

Parte 1 — INI

Regras: seções entre colchetes [secao], pares chave = valor, comentários com ;. Valores são texto (sem tipos). No platformio.ini, listas ocupam várias linhas indentadas.

formatos/exemplo.ini

; comentario de linha
[env:esp32dev]
platform = espressif32
board = esp32dev
monitor_speed = 115200
build_flags =
    -DCORE_DEBUG_LEVEL=5
    -DEXEMPLO=1

Valide: python -c "import configparser; configparser.ConfigParser().read('formatos/exemplo.ini')" (sem erro = ok).

Ponto de commit · T1 (5 pts) #

cria e comenta um arquivo INI com secao e chaves

git add formatos/exemplo.ini && git commit -m "T1: cria e comenta um arquivo INI com secao e chaves" && git push

---

Parte 2 — TOML

Parecido com INI, mas com tipos e regras mais rígidas: strings entre aspas, números e booleanos sem aspas, tabelas [tabela], arrays [a, b], comentário #.

formatos/exemplo.toml

# wokwi.toml e um TOML
[wokwi]
version = 1
firmware = '.pio/build/esp32dev/firmware.bin'
elf = '.pio/build/esp32dev/firmware.elf'

Erro clássico de TOML

nome = esp32 é inválido — string precisa de aspas: nome = "esp32". Booleanos são true/false (minúsculas, sem aspas).

Valide: python -c "import tomllib; tomllib.load(open('formatos/exemplo.toml','rb'))".

Ponto de commit · T2 (5 pts) #

cria um arquivo TOML com tabela, string e numero

git add formatos/exemplo.toml && git commit -m "T2: cria um arquivo TOML com tabela, string e numero" && git push

---

Parte 3 — JSON

O formato de troca de dados mais comum. Objetos { }, arrays [ ], strings em aspas duplas, números, true/false/null.

formatos/exemplo.json

{
  "nome": "esp32",
  "porta": 1883,
  "ativo": true,
  "tags": ["wifi", "mqtt"]
}

As 3 armadilhas do JSON

1. Sem comentários (nada de // ou #).
2. Sem vírgula sobrando depois do último item.
3. Só aspas duplas — 'aspas simples' não valem.

Valide: python -m json.tool formatos/exemplo.json (ou jq . formatos/exemplo.json). No VS Code, erros de JSON aparecem sublinhados na hora.

Ponto de commit · T3 (5 pts) #

cria um JSON valido com objeto e array

git add formatos/exemplo.json && git commit -m "T3: cria um JSON valido com objeto e array" && git push

---

Parte 4 — YAML

Usado nos docker-compose.yml e nos workflows. A indentação define a estrutura: mapas por chave: valor e listas por - item. É um superconjunto do JSON (todo JSON é YAML válido).

formatos/exemplo.yml

servico:
  nome: esp32
  porta: 1883
  tags:
    - wifi
    - mqtt

As armadilhas do YAML

1. Nunca use TAB para indentar — só espaços.
2. Precisa de espaço depois do : (porta: 1883, não porta:1883).
3. Indentação consistente (o mesmo nível com o mesmo número de espaços).
4. Alguns valores viram booleano sem querer: por isso docker-compose escreve as portas entre aspas ("1883:1883"), para o YAML não interpretar como número.

Valide: python -c "import yaml; yaml.safe_load(open('formatos/exemplo.yml'))". Para compose: docker compose config também valida.

Ponto de commit · T4 (5 pts) #

cria um YAML valido com mapa e lista

git add formatos/exemplo.yml && git commit -m "T4: cria um YAML valido com mapa e lista" && git push

---

Parte 5 — CONF

.conf não é um formato único — cada programa define a própria sintaxe. O Mosquitto usa uma diretiva por linha (diretiva valor, separado por espaço), com comentários #.

formatos/exemplo.conf

# estilo Mosquitto: diretiva valor
listener 1883 0.0.0.0
allow_anonymous true
persistence true

Leia a doc do programa

Um .conf do nginx usa blocos com chaves; um do Mosquitto usa diretiva valor; outro pode usar chave = valor. Quando encontrar um .conf, confirme a sintaxe na documentação daquele programa.

Ponto de commit · T5 (5 pts) #

cria um arquivo conf de diretivas

git add formatos/exemplo.conf && git commit -m "T5: cria um arquivo conf de diretivas" && git push

---

Parte 6 — JavaScript (.js)

Diferente dos anteriores, um .js é código — pode calcular valores. Usado quando a configuração precisa de lógica (settings.js do Node-RED, docusaurus.config.js).

formatos/exemplo.js

// isto e codigo: comentarios com //, chaves sem aspas, virgula final permitida
const porta = process.env.PORT || 1880;

module.exports = {
  nome: "esp32",
  porta: porta,
  tags: ["wifi", "mqtt"], // virgula final aqui e ok (ao contrario do JSON)
};

:::warning .js não é JSON Chaves sem aspas, comentários e vírgula final são permitidos — e o arquivo executa. Um erro de sintaxe quebra o programa que o carrega. :::

Valide a sintaxe: node -c formatos/exemplo.js (ou node -e "require('./formatos/exemplo.js')").

Ponto de commit · T6 (5 pts) #

cria um modulo de configuracao em JS

git add formatos/exemplo.js && git commit -m "T6: cria um modulo de configuracao em JS" && git push

---

Parte 7 — Markdown e front matter

As aulas são Markdown/MDX. O bloco de metadados no topo, entre ---, é YAML (chamado front matter).

formatos/exemplo.md

---
title: Minha aula
sidebar_position: 3
tags:
  - exemplo
---

# Conteúdo em Markdown

Texto normal, **negrito**, listas, código...

:::tip O front matter segue as regras do YAML Como é YAML, valem as mesmas armadilhas: espaços (não TAB), espaço depois do :, indentação consistente. :::

Ponto de commit · T7 (5 pts) #

escreve front matter YAML em um Markdown

git add formatos/exemplo.md && git commit -m "T7: escreve front matter YAML em um Markdown" && git push

---

8. Projeto integrador — Conserte os arquivos quebrados

Na pasta quebrados/ há três arquivos, cada um com um erro de sintaxe. Encontre e corrija os três, depois valide.

quebrados/dados.json

{
  // configuracao do dispositivo
  "nome": "esp32",
  "porta": 1883,
  "tags": ["wifi", "mqtt"]
}

quebrados/config.yml

servico:
	nome: esp32
porta:1883
tags:
  - wifi
  - mqtt

(A segunda linha usa uma tabulação.)

quebrados/projeto.toml

[projeto]
nome = esp32
porta = 1883
tags = ["wifi", "mqtt"]

Valide os três (nenhum deve imprimir erro):

python -m json.tool quebrados/dados.json
python -c "import yaml; yaml.safe_load(open('quebrados/config.yml'))"
python -c "import tomllib; tomllib.load(open('quebrados/projeto.toml','rb'))"

Ponto de commit · T8 (25 pts) #

projeto: conserta os arquivos quebrados

git add quebrados/dados.json quebrados/config.yml quebrados/projeto.toml && git commit -m "T8: projeto: conserta os arquivos quebrados" && git push

---

9. Desafios

Tente resolver sem olhar o gabarito. Faça o commit de cada desafio conforme concluir.

D1. Converta o formatos/exemplo.json da Parte 3 para YAML equivalente, salvando em desafios/d1.yml.

Ponto de commit · T9 (10 pts) #

desafio D1: converte JSON para YAML

git add desafios/d1.yml && git commit -m "T9: desafio D1: converte JSON para YAML" && git push

D2. Pegue o quebrados/config.yml, explique por escrito (num comentário no arquivo) por que a tabulação e o porta:1883 quebram, e deixe a versão corrigida em desafios/d2.yml.

Ponto de commit · T10 (10 pts) #

desafio D2: corrige o YAML com tabulacao e dois-pontos

git add desafios/d2.yml && git commit -m "T10: desafio D2: corrige o YAML com tabulacao e dois-pontos" && git push

D3. Em desafios/d3.md, explique por que no docker-compose.yml a porta é escrita como "1883:1883" (entre aspas) e o que aconteceria sem as aspas.

Ponto de commit · T11 (10 pts) #

desafio D3: explica por que a porta fica entre aspas no YAML

git add desafios/d3.md && git commit -m "T11: desafio D3: explica por que a porta fica entre aspas no YAML" && git push

D4. Escreva em desafios/d4.md o comando de validação de cada formato desta aula (INI, TOML, JSON, YAML, JS) e o que significa "validou".

Ponto de commit · T12 (10 pts) #

desafio D4: valida os arquivos com ferramentas

git add desafios/d4.md && git commit -m "T12: desafio D4: valida os arquivos com ferramentas" && git push

---

10. Gabarito

:::danger Spoiler Só abra depois de tentar por conta própria. :::

Ver soluções do projeto

dados.json — sem comentário e sem vírgulas sobrando:

{
  "nome": "esp32",
  "porta": 1883,
  "tags": ["wifi", "mqtt"]
}

config.yml — espaços no lugar da TAB e espaço depois do ::

servico:
  nome: esp32
porta: 1883
tags:
  - wifi
  - mqtt

projeto.toml — string entre aspas:

[projeto]
nome = "esp32"
porta = 1883
tags = ["wifi", "mqtt"]

D3 (resumo). Em YAML 1.1, 1883:1883 sem aspas poderia ser lido como um número no formato sexagesimal (base 60), não como o texto de mapeamento de porta. As aspas forçam o valor a ser uma string.

---

11. Checklist de encerramento

• Sei identificar INI, TOML, JSON, YAML, CONF e JS pela aparência.
• Criei um arquivo válido de cada formato (Partes 1 a 7).
• Sei as armadilhas do JSON (comentário, vírgula, aspas) e do YAML (TAB, espaço no :).
• Consertei e validei os três arquivos quebrados.
• Sei validar cada formato com uma ferramenta.
• Fiz o commit de cada ponto marcado (T1 a T12).

---

Fim da aula.