Объект схемы без атрибута типа в Swagger 2.0

Question

Должен ли объект схемы в Swagger/OpenAPI 2.0 иметь type атрибут или нет?

С одной стороны, согласно спецификации JSON Schema Draft 4, без указания type Атрибут OK и означает, что экземпляр может быть любого типа (объект, массив или примитив).

С другой стороны, я видел много схем Swagger, которые содержат объекты Schema без type атрибут, но с properties атрибут, который дает понять, что автор схемы хочет, чтобы экземпляр был правильным объектом (и не хочет принимать массивы или примитивы в качестве допустимых значений).

Все эти схемы неверны? Или type: object подразумевается наличием properties? В спецификации Swagger или JSON Schema нет ничего, что говорило бы об этом. На самом деле, я видел комментарии, которые явно говорят, что это не так.

Answer 1

Как и в схеме JSON, объектам схемы OpenAPI не требуется type и ты прав в этом нет type означает любой тип.

"Тип-специфичные" ключевые слова, такие как properties, items, minLength и т. д. не вводите тип в схему. Это работает наоборот - когда экземпляр проверяется по схеме, эти ключевые слова применяются только тогда, когда экземпляр имеет соответствующий тип, в противном случае они игнорируются. Вот соответствующая часть спецификации проверки схемы JSON:

4.1. Ключевые слова и экземпляры примитивных типов

Некоторые ключевые слова проверки применимы только к одному или нескольким примитивным типам. Когда примитивный тип экземпляра не может быть проверен с помощью данного ключевого слова, проверка для этого ключевого слова и экземпляра ДОЛЖНА завершиться успешно.

Например, рассмотрим эту схему:

definitions:
  Something:
    properties:
      id:
        type: integer
    required: [id]
    minLength: 8

Это допустимая схема, хотя она сочетает в себе ключевые слова, специфичные для объекта properties а также required и ключевое слово для конкретной строки minLength, Эта схема означает:

• Если экземпляр является объектом, он должен иметь целочисленное свойство с именем id, Например, {"id": 4} а также {"id": -1, "foo": "bar"} действительны, но {} а также {"id": "ACB123"} не.

• Если экземпляр является строкой, он должен содержать не менее 8 символов. "Hello, world!" действителен, но "" а также abc не.

• Любые экземпляры других типов действительны - true, false, -1.234, [], [1, 2, 3], [1, "foo", true], так далее.
  (Кроме null - OpenAPI 2.0 не имеет null типа и не поддерживает null кроме как в свойствах расширения. OpenAPI 3.0 поддерживает null значение для схем с nullable: true.)

Если есть инструменты, которые выводят type из других ключевых слов (например, обрабатывать схемы без type но с properties как всегда объекты), то эти инструменты не совсем соответствуют спецификации OpenAPI и схеме JSON.

Итог: если схема всегда должна быть объектом, добавьте type: object в явном виде. В противном случае вы можете получить неожиданные результаты.