Schema object without a type attribute in Swagger 2.0

user_1294964 0
Viewed 6106

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.

swagger-2.0 swagger openapi jsonschema
1 Answers

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:

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.x, 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.

user_1131160
Related