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

问题描述

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

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).

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).

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.

解决方案

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

"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. Keywords and instance primitive types

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.

For example, consider this schema:

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

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

• 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.

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

• 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.

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.

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

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