swagger-api / swagger-api/swagger-editor
Schema with missing type is implied as object if properties keyword is present
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:
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 fieldid - if it is an
array- it must have at least one element.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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