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.
(Except null
- OpenAPI 2.0 does not have the null
type and does not support null
except in extension properties. OpenAPI 3.0 supports the null
value for schemas with nullable: true
.)
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.