Swagger 2.0中没有类型属性的架构对象 [英] Schema object without a type attribute in Swagger 2.0

问题描述

Swagger/OpenAPI 2.0中的Schema对象是否必须具有type属性?

Does a Schema object in Swagger/OpenAPI 2.0 have to have the type attribute or not?

一方面，根据JSON Schema Draft 4规范，未指定type属性为OK，这意味着该实例可以是任何类型(对象，数组或基元).

On the one hand, according to the JSON Schema Draft 4 spec, not specifying the type attribute is OK and means that the instance can be of any type (an object, an array or a primitive).

另一方面，我已经看到很多Swagger模式，这些模式包含的Schema对象没有type属性，但是具有properties属性，这清楚地表明模式作者希望实例是一个实例.适当的对象(并且不希望将数组或图元接受为有效值).

On the other hand, I've seen a lot of Swagger schemas which contain Schema objects without the type attribute, but with the properties attribute, which makes it clear that the schema author wants the instance to be a proper object (and doesn't want to accept arrays or primitive as valid values).

所有这些模式都不正确吗?还是properties暗示type: object? Swagger或JSON Schema规范都没有说明这种情况.实际上，我看到有一些评论明确指出并非如此.

Are all those schemas incorrect? Or is type: object implied by the presence of properties? There's nothing in either the Swagger or the JSON Schema spec that says that is the case. In fact, I've seen comments that explicitly say that's NOT the case.

推荐答案

就像JSON模式一样，OpenAPI模式对象任何类型.

Like in JSON Schema, OpenAPI schema objects do not require a type, and you are correct in that no type means any type.

特定于类型"的关键字，例如properties，items，minLength等.不对架构强制执行类型.它以另一种方式起作用–当根据架构验证实例时，这些关键字仅在实例具有相应类型时才适用，否则将被忽略.这是 JSON模式验证规格:

"Type-specific" keywords such as properties, items, minLength, etc. do not enforce a type on the schema. It works the other way around – when an instance is validated against a schema, these keywords only apply when the instance is of the corresponding type, otherwise they are ignored. Here's the relevant part of the JSON Schema Validation spec:

4.1.关键字和实例基本类型

某些验证关键字仅适用于一种或多种原始类型.如果实例的原始类型无法通过给定的关键字进行验证，则应对此关键字和实例进行验证.

Some validation keywords only apply to one or more primitive types. When the primitive type of the instance cannot be validated by a given keyword, validation for this keyword and instance SHOULD succeed.

例如，考虑以下模式:

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

这是一个有效的架构，即使它结合了对象特定的关键字properties和required和字符串特定的关键字minLength.此架构的意思是:

It's a valid schema, even though it combines object-specific keywords properties and required and string-specific keyword minLength. This schema means:

• 如果实例是一个对象，则它必须具有一个名为id的整数属性.例如，{"id": 4}和{"id": -1, "foo": "bar"}有效，但{}和{"id": "ACB123"}无效.

• If the instance is an object, it must have an integer property named id. For example, {"id": 4} and {"id": -1, "foo": "bar"} are valid, but {} and {"id": "ACB123"} are not.

如果实例是字符串，则它必须至少包含8个字符. "Hello, world!"有效，但""和abc无效.

If the instance is a string, it must contain at least 8 characters. "Hello, world!" is valid, but "" and abc are not.

任何其他类型的实例都是有效的-true，false，-1.234，[]，[1, 2, 3]，[1, "foo", true]等.在OpenAPI 3.0中，未类型化的架构也允许null值.

Any instances of other types are valid - true, false, -1.234, [], [1, 2, 3], [1, "foo", true], etc. In OpenAPI 3.0, untyped schemas also allow null values.

如果存在从其他关键字推断type的工具(例如，处理不具有type但具有properties的模式作为始终对象)，则这些工具并不完全遵循OpenAPI规范和JSON模式

If there are tools that infer the type from other keywords (for example, handle schemas with no type but with properties as always objects), then these tools are not exactly following the OpenAPI Specification and JSON Schema.

底线:如果模式必须始终是对象，则显式添加type: object.否则，您可能会得到意想不到的结果.

Bottom line: If a schema must always be an object, add type: object explicitly. Otherwise you might get unexpected results.

这篇关于Swagger 2.0中没有类型属性的架构对象的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！