Schema object without a type attribute in Swagger 2.0

by

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.

More Related Contents:

  1. How to return an array of objects in SwaggerHub?
  2. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  3. Swagger schema properties ignored when using $ref – why?
  4. Swagger 2.0: Multiple Path objects with different paths but same request and response
  5. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  6. Swagger: wildcard path parameters
  7. Swagger: take one or more values from enum
  8. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  9. How to specify if a field is optional or required in OpenAPI/Swagger?
  10. Swagger/OpenAPI mock server
  11. How to document dynamic query parameter names in OpenAPI (Swagger)?
  12. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  13. How to define a property that can be string or null in OpenAPI (Swagger)?
  14. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  15. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  16. Swagger complex response model with dynamic key value hash maps
  17. How to define an optional parameter in path using swagger
  18. Swagger: “equivalent path already exists” despite different parameters
  19. Freeform subobject in json-schema
  20. OpenAPI query string parameter with list of objects
  21. Re-using model with different required properties
  22. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  23. How not to copy-paste 3 generic error responses in almost all paths?
  24. How to define global parameters in OpenAPI?
  25. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  26. OpenAPI path/query parameters nested structure serialization
  27. Sending cookie session id with Swagger 3.0
  28. How to change Swagger-ui URL prefix?
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment