# Manual de json.wordkers.com

json.wordkers.com comprueba, ordena y enseña JSON y YAML, y pasa del uno al otro. Todo ocurre en tu navegador. Está escrito para personas y para IAs que ayudan a una persona a usarlo.

## Qué es y para quién

json.wordkers.com es un banco de trabajo para **JSON** (el formato de datos de las API y de muchos ficheros de configuración) y para **YAML** (el de Docker Compose, GitHub Actions, Kubernetes, Ansible y otros ficheros de configuración).

Sirve a quien tiene que:

- ver si un JSON o un YAML está bien escrito y, si no, saber **en qué línea y columna** falla;
- leerlo ordenado, con colores, o como **árbol** plegable;
- **pasar un YAML a JSON** o **un JSON a YAML**;
- enterarse de las **trampas de YAML**: cosas que se leen distinto de como se escriben (`yes` que en unas herramientas es verdadero y en otras texto, `1.10` que se queda en `1.1`, `010` que pierde el cero…);
- minificar, ordenar las claves para comparar dos ficheros, o validar ficheros JSON Lines (`.jsonl`).

No hace falta cuenta ni instalar nada.

## Cómo se entra

1. Abre https://json.wordkers.com en Chrome, Edge, Safari o Firefox.
2. Pega el texto en el panel de la izquierda, pulsa «⬆ Abrir» para elegir un fichero, o arrástralo encima del panel. Si instalas la página como aplicación («Instalar app», abajo a la derecha), un doble clic en un `.json`, `.yaml` o `.yml` lo abre con ella.
3. Si solo quieres probar, pulsa «Ejemplo» (un JSON) o «Ejemplo YAML» (un YAML con algunas trampas a propósito).
4. Ayuda dentro de la página: botón «Ayuda». Este manual está en https://json.wordkers.com/manual y, en texto plano, en https://json.wordkers.com/manual.md. El índice para IAs está en https://json.wordkers.com/llms.txt.

## Qué hay en pantalla

- **Barra de arriba**: «Formatear», «Minificar», «Ordenar claves», la sangría («2 espacios», «4 espacios», «Tabulador»), la casilla «JSONL», el selector de entrada («Entrada: auto», «Entrada: JSON», «Entrada: YAML»), los botones «YAML → JSON» y «JSON → YAML», «⬆ Abrir», «⬇ Guardar», «Ejemplo», «Ejemplo YAML», «Limpiar», «Texto», «Árbol», «Ayuda» y «Tema».
- **Panel «Entrada»** (izquierda): el texto que escribes, pegas o abres.
- **Panel «Salida»** (derecha): el resultado. En su cabecera, «JSON» y «YAML» eligen en qué formato sale; «Copiar» y «⬇» se lo llevan.
- **Avisos** (encima de la salida, en una franja de color, solo si los hay): las trampas de YAML encontradas, cada una con su línea. Un clic en un aviso lleva el cursor a esa línea de la entrada.
- **Barra de abajo**: si el texto es válido («✓ JSON válido», «✓ YAML válido») o no («✗ … no válido»), el error con su **línea y columna** (un clic lleva el cursor allí), y el recuento de nodos, claves, profundidad, caracteres, documentos y avisos. Con «Entrada: auto» dice «(detectado)»: la página ha decidido sola si es JSON o YAML.

## Paso a paso

### Validar y formatear un JSON

1. Pega el JSON en «Entrada».
2. Mira la barra de abajo. Si dice «✓ JSON válido», a la derecha lo tienes indentado y con colores.
3. Si dice «✗ JSON no válido», lee el error y la «línea, columna»; haz clic en ella y el cursor va al sitio. Suele ser una coma que sobra o falta, o unas comillas.
4. Elige la sangría (2 o 4 espacios, o tabulador) y pulsa «Formatear» para que la entrada quede así, o «Minificar» para dejarla en una línea.

### Pasar un YAML a JSON

1. Pega el YAML en «Entrada» (o pulsa «Ejemplo YAML» para ver uno).
2. Pulsa «YAML → JSON». La entrada se lee como YAML y la salida sale en JSON.
3. Si la barra de abajo dice «✗ YAML no válido», lee el error (en castellano) y haz clic en «línea, columna» para ir al sitio. Los fallos típicos: sangría que no cuadra, un tabulador en la sangría, falta «:» o un espacio detrás de él, una clave repetida.
4. Si hay avisos encima de la salida, léelos: son cosas que esta página entiende de una forma y otras herramientas de otra (mira «Entender los avisos de YAML»).
5. Pulsa «Copiar» o «⬇» (baja `datos.json`). Si quieres que la entrada pase a ser el JSON, pulsa «Formatear».

### Pasar un JSON a YAML

1. Pega el JSON en «Entrada».
2. Pulsa «JSON → YAML». La salida sale en YAML.
3. Elige 2 o 4 espacios de sangría (YAML no admite tabuladores: con «Tabulador» se usan 2 espacios).
4. Pulsa «Copiar» o «⬇» (baja `datos.yaml`). Si quieres que la entrada pase a ser el YAML, pulsa «Formatear».

### Entender los avisos de YAML

1. Los avisos salen encima de la salida, cada uno con su línea; no son errores: el texto se ha leído, pero algo puede leerse distinto en otro programa.
2. «yes», «no», «on», «off», «y», «n» (y en mayúsculas) sin comillas: aquí son texto, como manda YAML 1.2; en YAML 1.1 (PyYAML, Ruby, muchas herramientas antiguas) son verdadero o falso. Si es texto, ponle comillas; si es verdadero o falso, escribe `true` o `false`. Pasa también con claves: la clave `on:` de GitHub Actions.
3. Números con cero delante (`010`) o con forma de versión (`1.10`, `2.0`): se leen como números y pierden su forma. Si es un código o una versión, ponle comillas.
4. Fechas sin comillas (`2024-01-01`): aquí quedan como texto; otras herramientas las convierten en fecha.
5. `.inf` y `.nan`: JSON no los tiene; en JSON quedan como `null`.
6. Tabuladores en la sangría: YAML solo admite espacios. Sangría mezclada (unos niveles entran 2 espacios y otros 4): es válida, pero confunde.
7. Varios documentos separados por `---`: mira «Trabajar con varios documentos YAML».
8. Anclas `&nombre` y alias `*nombre`: en JSON no existen, así que el contenido se copia en cada sitio donde se usa.
9. Haz clic en un aviso para ir a su línea y corrígelo si hace falta.

### Trabajar con varios documentos YAML

1. Un fichero YAML puede llevar varios documentos separados por líneas `---`.
2. La página los lee todos y lo avisa. En JSON salen como una lista: `[documento 1, documento 2, …]`.
3. Con la salida en «YAML», se escriben otra vez separados por `---`. No se pierde ninguno.

### Ordenar las claves o ver el árbol

1. Pulsa «Ordenar claves»: los campos de cada objeto salen en orden alfabético, en todos los niveles. Sirve para comparar dos ficheros con las mismas claves en distinto orden. Vuelve a pulsarlo para quitarlo.
2. Pulsa «Árbol» para ver la estructura plegable (un clic en «▸» pliega o despliega). «Texto» vuelve al texto con colores.
3. Las dos cosas valen igual para JSON y para YAML.

### Validar un fichero JSON Lines (.jsonl)

1. Marca la casilla «JSONL». Cada línea tiene que ser un JSON entero.
2. Si una línea falla, la barra de abajo dice cuál (línea del fichero y número de registro).
3. A la derecha ves cada registro formateado con su número de línea. «Minificar» deja cada registro en su línea; «Formatear» se desactiva, porque partiría los registros. Con la salida en «YAML», cada registro sale como un documento YAML.

### Abrir, guardar y descargar

1. «⬆ Abrir» trae un fichero del ordenador (`.json`, `.jsonl`, `.ndjson`, `.yaml`, `.yml` o de texto). También puedes arrastrarlo encima del panel «Entrada».
2. «⬇ Guardar» baja lo que hay en «Entrada», tal cual, con el nombre del fichero abierto (o `json.json`, `json.jsonl` o `json.yaml` si no abriste ninguno).
3. «⬇» (en la cabecera de «Salida») baja el resultado: `datos.json`, `datos.jsonl` o `datos.yaml`, según el formato de salida. «Copiar» lo copia al portapapeles.

## Qué ficheros admite y cómo tienen que venir

- **JSON**: un único valor JSON (objeto, lista, texto, número…), según el estándar: comillas dobles, sin comas finales, sin comentarios.
- **JSON Lines** (`.jsonl`, `.ndjson`): un JSON por línea, con la casilla «JSONL» marcada.
- **YAML** (`.yaml`, `.yml`): YAML 1.2 con el esquema básico («core»): textos, números, `true`/`false`, `null`, listas, objetos, anclas y alias, claves de fusión `<<`, bloques `|` y `>`, y varios documentos con `---`. Sangría solo con espacios.
- **Cómo decide «Entrada: auto»**: si el texto es JSON válido, es JSON. Si no, y empieza por `{` o `[`, se trata como JSON con un error (para que veas el error de JSON). En cualquier otro caso, es YAML. Para leer como YAML un texto que empieza por `{` o `[`, elige «Entrada: YAML».
- Texto en UTF-8.

## Límites

- No conserva los **comentarios** ni la forma exacta del YAML al convertirlo: al pasar a JSON se pierden (JSON no tiene comentarios), y el YAML que se escribe es nuevo, ordenado a su manera.
- Las **fechas** de YAML quedan como texto; las etiquetas raras (`!!binary`, `!!set`, `!!timestamp`, las propias de una herramienta como `!Ref` de CloudFormation) no se admiten: dan error.
- Al escribir YAML, los textos que se podrían confundir (`'yes'`, `'010'`, `'1.10'`, `'2024-01-01'`) salen con comillas, para que cualquier herramienta los lea igual.
- Unos alias que se despliegan en más de un millón de nodos (alias de alias en cadena) no se convierten: dan error en vez de colgar la página.
- YAML no admite tabuladores: con sangría «Tabulador» la salida YAML usa 2 espacios.
- En JSON, el error de algunos navegadores no dice la posición: entonces la barra de abajo da el mensaje sin línea ni columna.
- Todo se hace en el navegador: un fichero de muchos megas puede ir lento.

## Si algo sale mal

- Si la barra de abajo dice «no válido», haz clic en «línea, columna» para ir al sitio del error.
- Si un YAML sale como «JSON no válido», es que empieza por `{` o `[`: elige «Entrada: YAML».
- Si un JSON sale como YAML, es que no es JSON válido: elige «Entrada: JSON» para ver su error.
- Si un YAML da «hay un tabulador en la sangría», cambia los tabuladores del principio de línea por espacios.
- Si da «clave repetida», el mensaje dice qué clave y en qué línea estaba antes: quita o renombra una de las dos.
- Si no ves la salida en el formato que querías, pulsa «JSON» o «YAML» en la cabecera de «Salida».
- Si nada de esto sirve, escribe a admin@wordkers.com contando qué hiciste y qué viste.

## Privacidad

- Tu texto **no se sube a ningún servidor**: se lee, se comprueba y se convierte en tu navegador.
- Hay un contador de uso anónimo (juntos.wordkers.com): al empezar a escribir se envía solo el nombre de la herramienta («json»). Nunca tu texto.
- La página carga de cdn.wordkers.com el menú, el pie y el contador de visitas de la casa; el lector de YAML (js-yaml) va dentro de la propia página.
- Para que no pierdas el trabajo, el navegador guarda en tu propio equipo (localStorage) el texto que editas y tus preferencias (sangría, entrada, salida, vista). Se queda en ese navegador; para borrarlo, pulsa «Limpiar» o borra los datos del sitio.
- Una IA que te ayude solo ve lo que tú le cuentes o le pegues; esta página no le envía nada.

---
Karb and Sil · CC BY 4.0