¿Cómo se alinea OpenAPI 3.1 con JSON Schema?

¿Cómo se alinea OpenAPI 3.1 con JSON Schema? #

Uno de los cambios más importantes introducidos en OpenAPI 3.1 es su plena alineación con la especificación JSON Schema. En las versiones anteriores de OpenAPI, el objeto Schema se describía como un subconjunto ampliado de JSON Schema con modificaciones propias, lo que generaba fricciones a los desarrolladores que querían compartir esquemas entre distintas herramientas. OpenAPI 3.1 lo resuelve al adoptar JSON Schema Draft 2020-12 como vocabulario de esquemas sin modificaciones. Comprender esta alineación es esencial para cualquier equipo que trabaje con OpenAPI 3.1 y con herramientas de esquemas modernas.

Breve historia de la divergencia #

La especificación OpenAPI 2.0 (Swagger) se basaba en un subconjunto de JSON Schema Draft 4, publicado en 2013. Cuando se lanzó OpenAPI 3.0 en 2017, siguió usando un “subconjunto ampliado” de JSON Schema Draft 4, pero con modificaciones importantes que lo hacían incompatible con JSON Schema estándar:

  • nullable se introdujo como alternativa propia al enfoque de JSON Schema, que consiste en usar arreglos (arrays) de tipos.
  • exclusiveMinimum y exclusiveMaximum se definieron como booleanos, lo que contradecía la definición de JSON Schema Draft 6+, donde son valores numéricos.
  • $ref no admitía palabras clave hermanas, al contrario que el comportamiento de JSON Schema.

Esto significaba que los esquemas de OpenAPI 3.0 no podían validarse con validadores de JSON Schema estándar, y que las herramientas de JSON Schema no podían consumir esquemas de OpenAPI sin una capa de traducción. OpenAPI 3.1 elimina todas estas incompatibilidades.

¿Qué es JSON Schema Draft 2020-12? #

JSON Schema Draft 2020-12 es la versión estable más reciente de la especificación JSON Schema (también conocida como el borrador “2020-12”). Define un vocabulario para anotar y validar documentos JSON y es compatible con validadores como:

Al alinearse con Draft 2020-12, los esquemas de OpenAPI 3.1 pueden validarse con cualquiera de estas herramientas de forma inmediata, sin traducciones, sin forks y sin extensiones personalizadas.

Palabras clave de JSON Schema ahora admitidas en OpenAPI 3.1 #

type como arreglo #

En JSON Schema, type puede ser un arreglo (array) de nombres de tipo, lo que permite que un campo acepte varios tipos:

schema:
  type: [string, "null"]

Esto sustituye la palabra clave propia nullable: true de OpenAPI 3.0, que se ha eliminado en la versión 3.1.

$schema #

Los objetos de esquema de OpenAPI 3.1 pueden incluir $schema para declarar de forma explícita qué dialecto de JSON Schema utilizan. Esto resulta especialmente útil en documentos que contienen esquemas dirigidos a distintos dialectos:

schema:
  $schema: "https://json-schema.org/draft/2020-12/schema"
  type: object

El propio objeto raíz openapi tiene un nuevo campo jsonSchemaDialect que establece el valor predeterminado de $schema para todos los esquemas del documento.

$id #

JSON Schema permite que los esquemas declaren un URI canónico mediante $id. Esto permite identificar esquemas y referenciarlos entre sí sin depender de la ruta del archivo del documento:

schema:
  $id: "https://api.example.com/schemas/user"
  type: object

Esto no estaba admitido anteriormente en OpenAPI.

$dynamicRef y $dynamicAnchor #

Introducidas en Draft 2020-12, estas palabras clave permiten esquemas recursivos y polimórficos con enlace tardío, herramientas potentes para describir estructuras de árbol o modelos de datos extensibles sin problemas de $ref circulares:

schema:
  $dynamicAnchor: node
  type: object
  properties:
    children:
      type: array
      items:
        $dynamicRef: "#node"

unevaluatedProperties y unevaluatedItems #

Estas palabras clave ofrecen un control preciso sobre las propiedades adicionales y los elementos de arreglo que no están cubiertos por palabras clave hermanas del esquema, como properties o items. Permiten crear esquemas más estrictos y cerrados:

schema:
  type: object
  properties:
    name:
      type: string
  unevaluatedProperties: false

A diferencia de additionalProperties, unevaluatedProperties tiene en cuenta las propiedades definidas en las ramas de allOf, anyOf y oneOf, lo que lo hace mucho más potente para esquemas compuestos complejos.

const #

La palabra clave const restringe un campo a un único valor exacto:

schema:
  type: string
  const: "enabled"

Esto sustituye el patrón habitual de usar enum con un solo elemento.

prefixItems #

En Draft 2020-12, la validación de tuplas utiliza prefixItems (un arreglo de esquemas) en lugar de la antigua sintaxis de arreglo en items:

schema:
  type: array
  prefixItems:
    - type: string
    - type: number
  items: false

if / then / else #

La aplicación condicional de esquemas, introducida en Draft 7 y plenamente compatible en 2020-12, ahora es válida en los esquemas de OpenAPI 3.1:

schema:
  if:
    properties:
      type:
        const: "business"
  then:
    required: [taxId]
  else:
    required: [personalId]

Palabras clave hermanas de $ref #

En OpenAPI 3.0, las palabras clave situadas junto a un $ref se ignoraban sin avisar. En OpenAPI 3.1, siguiendo el comportamiento de JSON Schema, las palabras clave hermanas se combinan con el esquema referenciado:

schema:
  $ref: "#/components/schemas/BaseUser"
  description: "A user with administrator privileges"
  properties:
    adminLevel:
      type: integer

Esto permite realizar sobrescrituras locales precisas sin duplicar definiciones de esquema completas.

El campo jsonSchemaDialect #

OpenAPI 3.1 añade un nuevo campo de nivel superior, jsonSchemaDialect, al objeto raíz del documento, que permite a los diseñadores de API establecer el dialecto de JSON Schema predeterminado para todos los objetos de esquema del documento:

openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema

Si se omite, el valor predeterminado es el dialecto de esquema de OpenAPI 3.1, que es un superconjunto de JSON Schema 2020-12 con ampliaciones de vocabulario específicas de OpenAPI.

Modificaciones de esquema específicas de OpenAPI eliminadas #

OpenAPI 3.1 elimina las palabras clave que existían en la versión 3.0 debido a la divergencia con JSON Schema:

  • nullable: sustituido por arreglos de tipos: type: [string, "null"].
  • exclusiveMinimum/exclusiveMaximum booleanos: sustituidos por los límites exclusivos numéricos de Draft 7+.

Los equipos que migren de la versión 3.0 a la 3.1 deben actualizar estos patrones en todos sus esquemas.

Impacto en las herramientas #

La plena alineación con JSON Schema significa que los esquemas de OpenAPI 3.1 pueden usarse de forma nativa con todo el ecosistema de JSON Schema:

  • Bibliotecas de validación: AJV, jsonschema y otras pueden validar datos con esquemas de OpenAPI 3.1 sin necesidad de adaptadores específicos de OpenAPI.
  • Registros de esquemas: los esquemas pueden publicarse en registros como Confluent Schema Registry o compartirse entre servicios.
  • Generadores de código: herramientas como quicktype, que generan tipos a partir de JSON Schema, ahora pueden trabajar directamente con esquemas de OpenAPI 3.1.
  • Herramientas de documentación: Redoc y Stoplight Elements representan correctamente las palabras clave específicas de la versión 3.1.

Conclusión #

La plena alineación de OpenAPI 3.1 con JSON Schema Draft 2020-12 es una mejora trascendental que resuelve años de fricciones entre los ecosistemas de OpenAPI y JSON Schema. Al adoptar el vocabulario completo de JSON Schema, incluidos $id, $dynamicRef, unevaluatedProperties, const y los esquemas condicionales, OpenAPI 3.1 pasa a ser un ciudadano de primera clase del amplio mundo de las herramientas de esquemas. Para los equipos que crean API, esto se traduce en menos traducciones, mayor compatibilidad entre herramientas y una expresividad de esquemas mayor que en cualquier versión anterior de la especificación OpenAPI.

Última actualización: 29 de abril de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.