03 - Formatos de datos y de configuración

Markdown, JSON, XML, YAML y TOML son formatos de texto plano con estructura definida. Cada uno ocupa un papel distinto: documentación, intercambio de datos con APIs, configuración de herramientas o configuración local con variables de entorno. La pregunta no es «cuál es mejor», sino qué se guarda en cada uno:

Markdown es un lenguaje de marcas ligero para escribir texto con formato desde un editor cualquiera; se convierte a HTML para presentarlo. Se usa en README.md, documentación técnica, PR de GitHub y ficheros como AGENTS.md:

# Título 1
## Título 2

Párrafo con **negrita**, *cursiva* y `código en línea`.

- Elemento de lista
1. Primer paso

[Enlace](https://example.com)
![Texto alternativo](captura.png)
> Cita destacada

| Comando | Acción |
|---------|--------|
| `git status` | Estado de los archivos |

```java
public class Main { }
```

• Las triples comillas delimitan bloques de código; indicar el lenguaje activa el resaltado de sintaxis.
• Los encabezados definen la jerarquía del documento: # para el título principal, ## debajo, ### más abajo.

JSON (*JavaScript Object Notation*) es el formato estándar para intercambiar información estructurada entre aplicaciones, sobre todo en las APIs REST: el cliente envía JSON y recibe JSON. También sirve como fichero de configuración del ecosistema JavaScript (package.json, tsconfig.json):

{
  "id": 42,
  "title": "Código limpio",
  "available": true,
  "authors": ["Robert C. Martin"],
  "price": null,
  "publisher": { "name": "Anaya" }
}

Los valores se anidan: un array de objetos, un objeto dentro de otro. Desde TypeScript, JSON.parse(texto) convierte texto JSON en objeto y JSON.stringify(objeto) al revés; response.json() ya lo aplica al cuerpo de una respuesta (tema 07). JSON no admite comentarios ni fechas como tipo nativo (se representan como texto ISO: “2026-10-12”).

XML (*eXtensible Markup Language*) describe documentos y ficheros de configuración con estructura jerárquica: pom.xml de Maven, web.xml de Tomcat o la configuración de frameworks:

<?xml version="1.0" encoding="UTF-8"?>
<library>
  <book id="42" available="true">
    <title>Código limpio</title>
    <tag>craft</tag>
  </book>
</library>

Los espacios de nombres (xmlns) agrupan vocabularios para que etiquetas del mismo nombre no colisionen, como se ve en web.xml.

Un documento bien formado cumple las reglas sintácticas: un único elemento raíz, etiquetas cerradas y correctamente anidadas. La validación comprueba además que el documento respeta una estructura acordada; se define con XSD (XML Schema), que aporta tipos de datos y obligatoriedad:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="book">
    <xs:complexType>
      <xs:attribute name="id" type="xs:int" use="required"/>
    </xs:complexType>
  </xs:element>
</xs:schema>

Con ese esquema, un <book> con id no numérico no es válido.

YAML es un formato de configuración sin etiquetas: la indentación define la estructura con pares clave: valor. Es el formato de Docker Compose, GitHub Actions y Kubernetes:

# compose.yaml
services:
  db:
    image: mariadb:11
    ports:
      - "3306:3306"
    environment:
      MARIADB_ROOT_PASSWORD: ${DB_PASSWORD}
  web:
    build: .
    depends_on:
      - db

La sustitución ${DB_PASSWORD} toma el valor de la variable de entorno definida en el .env (apartado 6).

TOML organiza la configuración en secciones con clave = valor; los tipos básicos (texto, número, booleano, array) son nativos. Es el formato de pyproject.toml de Python y Cargo.toml de Rust:

[project]
name = "biblioteca"
version = "1.0.0"
tags = ["novela", "ensayo"]

[build]
target = "dist"

• [sección] agrupa las claves hasta la siguiente sección.
• elementos repite una sección para representar listas de objetos.

La configuración que cambia por máquina (puertos, rutas de base de datos, claves de API) no se escribe en el código ni se sube al repositorio: se lee de las variables de entorno. Durante el desarrollo se declaran en un .env:

# .env
PORT=3000
DATABASE_URL=mariadb://app:contrasenya@localhost:3306/library

• Una línea por variable con el formato CLAVE=VALOR; los comentarios con #.
• Las herramientas cargan el .env al arrancar la aplicación: dotenv en Node; en Docker Compose el propio fichero alimenta las sustituciones ${VAR}, y en Spring las variables de entorno alimentan el application.properties.
• El código las consulta en ejecución: process.env.PORT en Node, System.getenv(“PORT”) en Java, os.environ en Python.

Al repositorio solo se sube un .env.example con los nombres de las variables y sin valores, para que cada máquina cree su .env propio.