1.3.1 .mini · Para aplicaciones que piden JSON a una IAFor apps that request JSON from AI
Tu IA puede
costar menos.Your AI can
cost less.
.mini es un formato compacto para los datos que genera tu IA: pedidos, productos, tickets o los objetos que necesita tu aplicación. JSON repite los nombres de los campos en cada objeto; .mini usa un contrato para evitar esa repetición y reducir el texto que se cobra..mini is a compact format for AI-generated data: orders, products, tickets or the objects your app needs. JSON repeats field names in every object; .mini uses a contract to avoid that repetition and reduce billable text.
Acuerdas los campos una vez en un contrato; la IA responde en .mini y el código lo comprueba y convierte a JSON para tu aplicación. Menos tokens —los fragmentos de texto que cobra la IA— puede reducir el coste de la respuesta. El total también depende de las instrucciones y los reintentos.You define the fields once in a contract; AI replies in .mini and the code checks it and converts it to JSON for your app. Fewer tokens—the pieces of text AI bills—can reduce response cost. Total cost also depends on instructions and retries.
Dónde se reduce el textoWhere text gets shorter
JSON repite los nombres.
.mini acuerda las reglas una vez.JSON repeats field names.
.mini agrees on the rules once.
- 01
JSON
Cada ticket vuelve a escribir "titulo", "categoria" y "prioridad", con comillas y signos. La IA también genera y cobra ese texto.Every ticket writes "title", "category" and "priority" again, with quotes and punctuation. AI also generates and bills that text.
- 02
TOON
También reduce repetición: en una tabla, declara los campos una vez. Es otra alternativa para responder con datos estructurados.It also reduces repetition: a table declares fields once. It is another alternative for structured data responses.
- 03
.mini
Adapta un contrato a tu dominio: soporte, pedidos o inventario. Cada línea usa el orden de campos acordado y el código conoce sus tipos. Tu aplicación recupera el JSON.Tailors a contract to your domain: support, orders or inventory. Each line uses the agreed field order and the code knows its types. Your app gets JSON back.
En los 20 tickets medidos, .mini usa 278 tokens frente a 304 de TOON y 443 de JSON. La ventaja depende de tus datos; compara también las instrucciones y las correcciones antes de calcular el ahorro total.For the 20 measured tickets, .mini uses 278 tokens versus TOON's 304 and JSON's 443. The benefit depends on your data; include instructions and corrections before calculating total savings.
Qué hace mini setupWhat mini setup does
Tu formato nace
de los datos que necesitas.Your format starts
with the data you need.
Es un asistente en tu terminal. Le das un JSON como el que necesita tu aplicación; prepara las reglas del formato y su conexión a tu llamada a IA.It is a terminal wizard. Give it JSON like the data your app needs; it prepares format rules and connects them to your AI call.
- 01
Describe tu JSONDescribe your JSON
Elige español o inglés y una muestra de datos. El contrato guarda sus campos, su orden y sus tipos: las reglas de tu .mini.Choose Spanish or English and a data sample. The contract stores its fields, order and types: the rules of your .mini.
- 02
Recibe el kit preparadoGet your toolkit
El prompt son las instrucciones para la IA. El workflow es el código que comprueba su respuesta, la repara cuando puede y devuelve JSON.The prompt contains AI instructions. The workflow is code that checks the response, repairs it when possible and returns JSON.
- 03
Elige el archivo de tu flujoChoose your workflow file
Indica dónde llamas a la IA para preparar la integración. Si todavía no tienes ese código, la guía guarda el comando para hacerlo después.Select the code that calls AI to prepare integration. If you do not have it yet, the guide saves the command for later.
Incluye un prompt para probar 20 objetos antes de conectar tu aplicación.Includes a prompt to test 20 objects before connecting your application.
Dentro de tu códigoInside your code
Comprueba primero.
Guarda después.Check first.
Save afterwards.
El workflow conecta tu llamada a IA con el validador y el parser. El validador comprueba las reglas; Repair corrige fallos de formato. El parser convierte una respuesta válida a objetos JSON para tu aplicación.The workflow connects your AI call to the validator and parser. The validator checks the rules; Repair fixes formatting problems. The parser converts a valid response to JSON objects for your app.
Si hay un tipo incorrecto o faltan datos, el workflow puede pedir una corrección a la IA y vuelve a comprobarla. La animación muestra una ejecución guardada con 20 tickets.If a type is wrong or data is missing, the workflow can request an AI correction and check again. The animation shows a recorded run with 20 tickets.
Empieza con una muestra JSON.Start with a JSON sample.
Descarga y extrae el paquete. Instala el archivo Python incluido y abre el asistente:Download and extract the package. Install the included Python file and open the wizard:
python -m pip install --no-index mini_format-1.3.1-py3-none-any.whlmini setupEl asistente pregunta el idioma, lee tu muestra JSON y prepara el kit. Después eliges el archivo que llama a la IA o «Todavía no tengo un flujo» para conectarlo más adelante.The wizard asks for your language, reads your JSON sample and prepares the toolkit. Then select your AI call file or “I do not have a workflow yet” to connect it later.
Python 3.9+ · MIT · Ejemplo de 20 tickets e historial incluidos.20-ticket example and history included.
Ver más mediciones y documentación técnicaMore measurements and technical documentation
DummyJSON products
194 registros · Datos públicos de prueba
Tokens de salida relativos a .mini · menos es mejor. o200k_base
DummyJSON users
208 registros · Datos públicos de prueba
Tokens de salida relativos a .mini · menos es mejor. o200k_base
JSONPlaceholder comments
500 registros · Datos públicos de prueba
Tokens de salida relativos a .mini · menos es mejor. o200k_base
USGS earthquake observations
1.000 registros · Observaciones reales
Tokens de salida relativos a .mini · menos es mejor. o200k_base
Cuantos más campos,
más gana.
JSON repite el nombre de cada campo en cada objeto. mini-format lo declara una vez en el contrato. El coste de los nombres crece como O(W·N) en JSON y como O(W) aquí.
registro estrecho
registro típico de negocio
registro ancho
Ahorro frente a JSON compacto · escala lineal, origen en 0 %, máximo del eje 50 % · 1000 registros · tokenizador o200k_base · mediana de 5 documentos por celda · datos sintéticos deterministas (semilla 20260915). La curva satura cerca de 32 campos. reproducir →
Mismos datos.
Menos tokens medidos.
1.902 registros de cuatro conjuntos públicos. 35,64 % menos tokens que JSON compacto y 9,65 % menos que TOON plano en el total medido.
| Conjunto | N | .mini | TOON flat | Ahorro vs TOON | Ahorro vs CSV | Prompt .mini |
|---|---|---|---|---|---|---|
| DummyJSON products | 194 | 64.090 | 68.260 | 6,11 % | 4,42 % | 1.206 |
| DummyJSON users | 208 | 43.268 | 60.926 | 28,98 % | 27,92 % | 1.796 |
| JSONPlaceholder comments | 500 | 30.268 | 31.022 | 2,43 % | -1,35 % | 477 |
| USGS earthquake observations | 1.000 | 164.137 | 173.803 | 5,56 % | 4,11 % | 1.336 |
USGS: 1.000 observaciones reales. DummyJSON y JSONPlaceholder: 902 registros de prueba sintéticos, sin duplicación para inflar el lote. Ida y vuelta JSON exacta en los ocho formatos. TOON oficial 4.1.1; se elige el menor de dos aplanados reversibles. Los porcentajes son de salida: el prompt de .mini se muestra aparte. CSV sigue siendo menor en comentarios. Es una medición de serialización, no de precisión de generación de un LLM. Método y reproducción → · JSON
El mismo documento
no cuesta lo mismo en cada modelo.
Los separadores no se segmentan igual en todos los vocabularios. Mismos 14 dominios, lote de 10, frente a JSON compacto.
vocabulario de 50k
IC95 [26,8 % · 31,5 %] · k=14
vocabulario de 100k
IC95 [29,1 % · 33,5 %] · k=14
vocabulario de 200k
IC95 [31,5 % · 35,5 %] · k=14
Escala lineal, origen en 0 %, máximo del eje 36 %: la diferencia es real pero pequeña — 3,9 puntos entre el vocabulario más antiguo y el más reciente. Los tres vocabularios pertenecen a la familia tiktoken. reproducir →
Interfaz
Todo sale
del contrato.
from minifmt import Contract, parse, dumps, spec_block, roundtrip_ok
c = Contract.load("contrato.json") # el contrato de tu aplicación
instruccion = spec_block(c, lang="es") # bloque para el prompt de sistema
doc = parse(respuesta, c, strict=False) # tolerante: no lanza, acumula
doc.records # registros válidos, ya tipados
for e in doc.errors: # MiniError: code, line, field, message
print(e)
texto = dumps(doc.to_canonical(), c) # canónico -> .mini
assert roundtrip_ok(doc.to_canonical(), c)import { normalizeContract, parse, dumps, specBlock } from '@mini-format/core';
const c = normalizeContract(miContrato); // contract.json de tu aplicación
const lenient = parse(texto, c, { strict: false });
lenient.records; // registros válidos
lenient.errors; // MiniError[] con code, line, field, message
lenient.invalidLines(); // líneas rechazadas: las que hay que regenerar
lenient.missingRecords; // n − líneas recibidas
lenient.diagnostics(); // mismas claves que la referencia Pythonimport { createReader } from '@mini-format/core';
const reader = createReader(c, { // strict: false por defecto
onRecord: ({ record, line, index }) => mostrar(record),
onError: (e) => console.warn(String(e)),
});
for await (const token of respuestaDelModelo) reader.push(token);
const res = reader.end();
res.missing; // registros que faltan respecto de n
res.truncated; // se cortó: incompleto o menos líneas que n
res.terminated; // el flujo terminó en salto de líneamini from-schema ticket.schema.json -p tk --out contrato.json
mini validate respuesta.mini --contract contrato.json
mini diagnose respuesta.mini --contract contrato.json
mini to-json respuesta.mini --contract contrato.json | jq .
mini from-json datos.json --contract contrato.json
mini prompt --contract contrato.json --lang es
mini tokens respuesta.mini --enc o200k_base # tokens y bytes, con el tokenizador declarado
$ python conformance/run_python.py
376 casos · 376 pasan · 0 fallan
$ cd ts && npm test
conformance.test.ts · 376/376
# las expectativas salen de la norma y de los fixtures publicados,
# nunca se calculan ejecutando la implementaciónComparativa
Qué hace cada formato
cuando el emisor es un modelo.
| Capacidad | mini-format | JSON | CSV | TOON |
|---|---|---|---|---|
| Menos tokens que JSON compacto | ✓ | — | ✓ | ✓ |
| Tipos declarados en el contrato | ✓ | parcial | ✗ | parcial |
| Error con código, línea y campo | ✓ | parcial | ✗ | ✗ |
| Códigos de error estables en la norma | 15 | ✗ | ✗ | ✗ |
| Recuperación ante truncamiento | ✓ | ✗ | ✓ | parcial |
| Reparación selectiva por línea | ✓ | ✗ | ✗ | ✗ |
| Lectura en streaming, registro a registro | ✓ | parcial | ✓ | ✗ |
| Suite de conformidad publicada | 376 | ✓ | ✗ | ✗ |
| Dos implementaciones independientes | ✓ | ✓ | ✓ | parcial |
| Listas con elemento marcado | ✓ | ✗ | ✗ | ✗ |
| Compatibilidad hacia adelante declarada | ✓ | ✗ | ✗ | ✗ |
| Anidamiento arbitrario | ✗ | ✓ | ✗ | ✓ |
| Lectura directa sin contrato | parcial | ✓ | ✓ | ✓ |
| Soporte nativo en APIs de proveedores | ✗ | ✓ | ✗ | ✗ |
La compatibilidad conserva los campos conocidos cuando el mismo prefijo declara una versión superior. El perfil base usa registros planos; el toolkit generado reconstruye la estructura JSON de tu dominio. El modelo necesita el prompt y el lector, el contrato.
376 casos independientes del lenguaje, con expectativas escritas desde la norma y nunca calculadas ejecutando el código. Python y TypeScript pasan 376/376.
Gramática EBNF, 15 códigos de error estables y protocolo de extensión.
EspecificaciónSpecification · ValidaciónValidation · Referencia de erroresError reference · Ejemplos opcionalesOptional examples