Skip to content

Especificaciones legibles por máquina

Un JSON Schema para la configuración y un documento OpenAPI para la API, ambos generados desde el código y comprobados en CI, para que un agente de programación pueda configurar Potato sin inventarse opciones.

Potato publica dos contratos generados y verificables por máquina junto a la documentación en prosa. Ambos se producen desde el código en ejecución en lugar de mantenerse a mano, así que describen lo que Potato hace de verdad y no lo que alguien recordaba la última vez que editó una página.

Si vas a poner un agente de programación a trabajar con Potato, estos dos más llms.txt son lo más valioso que puedes darle.

ArtefactoQué describe
JSON Schema de configuraciónCada clave, tipo de anotación y tipo de visualización válidos en un config.yaml de tarea
Especificación OpenAPI 3.1Cada endpoint HTTP que registra el servidor

El esquema de configuración

La versión 2.8.0 cubre 159 claves de configuración de nivel superior, 61 tipos de anotación y 24 tipos de visualización, más condicionales por tipo, de modo que a un esquema constant_sum se le indica que necesita labels antes de que el servidor lo rechace.

Añade la modeline como primera línea de cualquier configuración y tu editor valida mientras escribes, en VS Code, JetBrains, Zed y Helix:

yaml
# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json

Todas las configuraciones que se distribuyen en el repositorio de Potato la llevan, y el playground la emite en cada descarga.

En CI:

bash
check-jsonschema --schemafile \
  https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json \
  path/to/config.yaml

O con el validador local, que además informa de claves desconocidas:

bash
python -m potato.validate_cli --strict config.yaml

La especificación de la API

419 rutas y 456 operaciones, recorridas desde el mapa de rutas Flask en vivo en lugar de escritas a mano. Los blueprints que dependen de la configuración se registran en aplicaciones desechables para que no se omitan en silencio, y la autenticación por endpoint se recupera mediante un análisis del AST.

Para dar escala: la referencia anterior, escrita a mano, cubría 84 endpoints frente a más de 400 rutas registradas.

La CI falla si divergen

Ambos artefactos se regeneran y se comparan en CI. Un esquema que puede divergir del código es peor que ningún esquema, porque acabará creyéndose.

Por qué importa ahora

El fallo más habitual cuando un LLM escribe una configuración de Potato es inventarse un annotation_type que no existe. Distribuir un JSON Schema que editores y agentes resuelven sin conexión lo corrige en el origen.

El constructor de configuraciones de este sitio se apoya en la misma idea: el playground lee los registros de Potato y solo puede emitir claves que aparezcan en ellos, con un banco de pruebas que pasa cada configuración generada por validate_cli --strict.

Relacionado