draft-07 o 2020-12
En resumen: 2020-12 es la versión actual y añade $defs, prefixItems y unevaluatedProperties, pero muchas herramientas solo hablan draft-07. Elige según lo que admita toda tu cadena de herramientas.
En resumen: usa 2020-12 para proyectos nuevos, vuelve a draft-07 en el momento en que cualquier validador, generador de código o herramienta OpenAPI solo lo admita, y fija siempre el borrador con $schema.
Respuesta corta: 2020-12 para trabajo nuevo, draft-07 cuando un componente antiguo lo obligue.
Cronología
| Borrador | Año | Destacado |
|---|---|---|
| draft-04 | 2013 | id en lugar de $id; aún común en API más antiguas |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; mejor compatibilidad |
| 2019-09 | 2019 | $defs sustituye a definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; recomendación actual |
Qué mejora 2020-12
Las tuplas de array dejan de ser un caso especial. draft-07 expresa «el primer elemento es A, el segundo es B» con items: [{...}, {...}] más additionalItems. 2020-12 usa prefixItems para esquemas por posición y items para el resto.
$defs es el nombre estándar. Las herramientas escritas después de 2019 lo buscan ahí de forma predeterminada.
unevaluatedProperties funciona con composición. Con allOf, additionalProperties: false rechaza campos definidos por ramas hermanas. unevaluatedProperties: false solo considera las propiedades evaluadas realmente por todo el esquema, que es lo que necesita la composición.
Cuándo draft-07 es la respuesta correcta
| Situación | Motivo |
|---|---|
| OpenAPI 3.0 | Su objeto schema es un subconjunto de draft-04/07 |
| Validadores antiguos (ajv 6, algunas bibliotecas Java) | No conocen prefixItems ni $dynamicRef |
| La plataforma impone una versión | Algunas plataformas low-code y gateways la fijan |
| Generadores de código que se detienen en 07 | Las palabras clave desconocidas se ignoran en silencio |
Prueba el último caso directamente: pasa un esquema con prefixItems a tu validador. Si lo acepta sin quejarse en lugar de informar de una palabra clave desconocida, está ignorando la restricción, el resultado más peligroso de todos.
Mezclar versiones
Declara siempre $schema. Los valores predeterminados difieren: ajv asume draft-07, varias bibliotecas de Python asumen 2020-12. El mismo archivo entonces valida de forma distinta en dos lugares.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
No uses $ref entre borradores. El comportamiento no está definido.
Actualiza por lotes. Dos borradores en un mismo repositorio convierten «qué reglas se aplican aquí» en conocimiento tribal.
FAQ
¿Cómo compruebo si mi validador admite 2020-12?
Pasa al validador un esquema que use prefixItems. Un error de palabra clave desconocida significa que no admite el borrador; que pase en silencio significa que está ignorando la restricción, lo que es peor.
¿Por qué debería un proyecto usar un único borrador?
Dos borradores en un mismo repositorio convierten «qué reglas se aplican aquí» en conocimiento tribal. Actualiza por lotes para que todos los archivos compartan la misma interpretación.
¿Debería declarar siempre $schema?
Sí. Los valores predeterminados difieren: ajv asume draft-07 mientras que varias bibliotecas de Python asumen 2020-12, así que el mismo archivo puede validar de forma distinta en dos lugares.