swagger-api / swagger-api/swagger-editor

Schema with missing type is implied as object if properties keyword is present

Open
#5,719 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
9.5k
Forks
2.4k
Avg merge
17h 15m
Merged PRs (30d)
18

Description

Environment: https://editor.swagger.io/
Version: 5.2.1

Assume there is a following specification:

openapi: 3.1.1
info:
  title: Sample API
  version: 0.0.1
components:
  schemas:
    user:
      description: User
      properties: {}

Swagger UI shows user schema type as object instead of any:
Image

It seems to me that Swagger contradicts OAS Specification.
Could you please clarify, is it a bug or am I mising something in the specs?
Maybe it is some kind of convention adopted in Swagger community?


I've checked both specifications - OAS 3.1.1 and Json Schema 2020-12.
It isn't stated anywhere that instance type should be implicitly implied as object in case properties keyword is present.

OAS Specification states the opposite:

JSON Schema keywords and format values operate on JSON “instances” which may be one of the six JSON data types, “null”, “boolean”, “object”, “array”, “number”, or “string”, with certain keywords and formats only applying to a specific type. For example, the pattern keyword and the date-time format only apply to strings, and treat any instance of the other five types as automatically valid. This means JSON Schema keywords and formats do NOT implicitly require the expected type. Use the type keyword to explicitly constrain the type.

If I do interpret it right, it means that properties keyword must apply to instances with type object. But it does not imply that the instance must be of type object. Strictly speaking, one could define the following fancy schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "minLength": 3
  "properties": {
    "id": {}
  },
  "required": ["id"],
  "items": {},
  "minItems": 1
}

And it would mean that the instance may be of any valid JSON type, but:

  • if it is a string - it must have at least 3 chars
  • if it is an object - it must have a field id
  • if it is an array - it must have at least one element.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the behavior in https://editor.swagger.io/ using the minimal OpenAPI 3.1.1 specification in the issue. Compare the displayed schema type with the cited OAS 3.1.1 and JSON Schema 2020-12 rules; done means the editor's behavior is clarified or corrected to match the applicable specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.