1.3.3 .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.3-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 records · Public test data
Output tokens relative to .mini · lower is better. o200k_base
DummyJSON users
208 records · Public test data
Output tokens relative to .mini · lower is better. o200k_base
JSONPlaceholder comments
500 records · Public test data
Output tokens relative to .mini · lower is better. o200k_base
USGS earthquake observations
1,000 records · Real observations
Output tokens relative to .mini · lower is better. o200k_base
More fields,
greater savings.
JSON repeats every field name in every object. mini-format declares it once in the contract. Field-name cost grows as O(W·N) in JSON and O(W) here.
narrow record
typical business record
wide record
Savings versus compact JSON · linear scale from 0%, maximum 50% · 1,000 records · o200k_base · median of 5 documents per cell · deterministic synthetic data (seed 20260915). The curve levels off near 32 fields. reproduce →
Same data.
Measured token savings.
1,902 records from four public datasets. 35.64% fewer tokens than compact JSON and 9.65% fewer than flat TOON across the measured total.
| Dataset | N | .mini | TOON flat | Saved vs TOON | Saved vs CSV | .mini prompt |
|---|---|---|---|---|---|---|
| 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 real observations. DummyJSON and JSONPlaceholder: 902 synthetic test records, never duplicated to inflate the batch. Exact JSON round-trips for all eight formats. Official TOON 4.1.1; the smaller of two reversible flattening variants is selected. Savings describe output tokens; the .mini prompt is shown separately. CSV remains smaller for comments. This measures serialization, not LLM generation accuracy. Method and reproduction → · JSON
The same document
has a different cost in each model.
Separators tokenize differently across vocabularies. Same 14 domains, batches of 10, versus compact JSON.
50k vocabulary
95% CI [26.8 % · 31.5 %] · k=14
100k vocabulary
95% CI [29.1 % · 33.5 %] · k=14
200k vocabulary
95% CI [31.5 % · 35.5 %] · k=14
Linear scale from 0%, maximum 36%: a 3.9-point difference between the oldest and newest vocabulary. All three are tiktoken vocabularies. reproduce →
Interface
Everything comes
from the contract.
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ónComparison
What each format does
when a model writes the output.
| Capability | mini-format | JSON | CSV | TOON |
|---|---|---|---|---|
| Fewer tokens than compact JSON | ✓ | — | ✓ | ✓ |
| Contract-declared types | ✓ | partial | ✗ | partial |
| Errors with code, line and field | ✓ | partial | ✗ | ✗ |
| Stable specification error codes | 15 | ✗ | ✗ | ✗ |
| Truncation recovery | ✓ | ✗ | ✓ | partial |
| Selective per-line repair | ✓ | ✗ | ✗ | ✗ |
| Record-by-record streaming | ✓ | partial | ✓ | ✗ |
| Published conformance suite | 376 | ✓ | ✗ | ✗ |
| Two independent implementations | ✓ | ✓ | ✓ | partial |
| Lists with a selected item | ✓ | ✗ | ✗ | ✗ |
| Declared forward compatibility | ✓ | ✗ | ✗ | ✗ |
| Arbitrary nesting | ✗ | ✓ | ✗ | ✓ |
| Reading without a contract | partial | ✓ | ✓ | ✓ |
| Native provider API support | ✗ | ✓ | ✗ | ✗ |
Forward compatibility preserves known fields when the same prefix declares a higher version. The base profile uses flat records; the generated toolkit reconstructs your domain's JSON structure. The model needs the prompt; the reader needs the contract.
376 language-independent cases, with expectations derived from the specification rather than calculated by the code. Python and TypeScript pass 376/376.
Gramática EBNF, 15 códigos de error estables y protocolo de extensión.
SpecificationSpecification · ValidaciónValidation · Referencia de erroresError reference · Ejemplos opcionalesOptional examples