Що змінилося між OpenAPI 3.0 і 3.1 і чому важлива сумісність з JSON Schema?

OpenAPI 3.0 використовував власний діалект JSON Schema - «розширену підмножину»: частину ключових слів підтримував інакше, частину не підтримував, а частину додав від себе (nullable). Через це одну й ту саму схему не можна було напряму використати і в OpenAPI, і в бібліотеках валідації JSON Schema.

OpenAPI 3.1 зробив схеми повністю сумісними з JSON Schema 2020-12.

Основні зміни в схемах:

1. nullable прибрано - замість нього масив типів:

# 3.0
salary_from:
  type: integer
  nullable: true

# 3.1
salary_from:
  type: [integer, 'null']

2. Приклади: example (одне значення) застаріло на користь examples - масиву, як у JSON Schema.

3. exclusiveMinimum / exclusiveMaximum - тепер числа, а не булеві прапорці.

4. $ref поруч з іншими ключовими словами - дозволено (у 3.0 сусідні ключі ігнорувалися), тож можна послатися на схему й додати опис.

5. Нові можливості JSON Schema: const, if/then/else, prependItems, $defs, unevaluatedProperties, оголошення діалекту через $schema.

6. Опис файлів: замість format: binary - contentMediaType і contentEncoding.

Інші зміни специфікації:

• вебхуки (webhooks) - опис запитів, які API надсилає клієнтам;
• paths став необов'язковим - документ може описувати лише компоненти чи вебхуки;
• info.summary, ідентифікатор ліцензії SPDX.

Чому сумісність важлива на практиці:

• одна схема - кілька застосувань: та сама схема валідує запити на сервері, генерує типи (TypeScript, Zod), описує дані в документації й перевіряє відповіді в контрактних тестах - без перетворень і розбіжностей;
• екосистема JSON Schema (валідатори, генератори форм, редактори) працює з OpenAPI-схемами напряму;
• менше «дивних» відмінностей, через які інструменти по-різному трактували одну специфікацію.

Міграція 3.0 → 3.1 - не лише заміна номера версії: nullable, example, exclusiveMinimum треба переписати. І перевірити, що всі інструменти ланцюжка (генератори клієнтів, UI документації, шлюзи) підтримують 3.1 - деякі досі працюють коректно лише з 3.0.

OpenAPI 3.2 (2025) розширює 3.1 зворотно сумісно (потокові медіатипи, ієрархічні теги, метод QUERY) і не змінює модель схем.

Докладніше в документації: Міграція з OpenAPI 3.0 на 3.1