swagger-api / swagger-api/swagger-parser
3.1.0 Boolean schemas are silently omitted or cause parsing errors
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 867
- Forks
- 560
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
Boolean schemas (schemas where the value is true/false) are silently omitted or cause parsing errors
Swagger-parser version: 2.1.16
Sample spec:
openapi: 3.1.0
info:
version: 1.0.0
title: Example
license:
name: MIT
servers:
- url: http://api.example.xyz/v1
paths:
/person/display/{personId}:
get:
parameters:
- name: personId
in: path
required: true
description: The id of the person to retrieve
schema:
type: string
operationId: list
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/BooleanTrue"
components:
schemas:
BooleanTrue: true
ArrayWithTrueItems:
type: array
items: true
ObjectWithTrueProperty:
properties:
someProp: true
ObjectWithTrueAdditionalProperties:
additionalProperties: true
AllOfWithTrue:
allOf:
- true
AnyOfWithTrue:
anyOf:
- true
OneOfWithTrue:
oneOf:
- true
NotWithTrue:
not: true
UnevaluatedItemsTrue:
unevaluatedItems: true
UnevaluatedPropertiesTrue:
unevaluatedProperties: true
PrefixitemsWithNoAdditionalItemsAllowed:
$schema: https://json-schema.org/draft/2020-12/schema
prefixItems:
- {}
- {}
- {}
items: false
PrefixitemsWithBooleanSchemas:
$schema: https://json-schema.org/draft/2020-12/schema
prefixItems:
- true
- false
For these schemas, the booleans are not stored correctly or are omitted or a parser error is raised:
- BooleanTrue
- ArrayWithTrueItems
- ObjectWithTrueProperty
- AllOfWithTrue
- AnyOfWithTrue
- OneOfWithTrue
- NotWithTrue
- UnevaluatedItemsTrue
- UnevaluatedPropertiesTrue
- PrefixitemsWithNoAdditionalItemsAllowed
- PrefixitemsWithBooleanSchemas
Note: contains: true works and does not have this bug
This issue is the biggest contributor to 3.1.0 json schema test suite failures
I am working on adding 3.1.0 features to my code generation project at https://github.com/openapi-json-schema-tools/openapi-json-schema-generator and I use your parser.
One way that I am verifying that my 3.1.0 json schema features are implemented correctly is by running the json schema test suite against my implementation.
Bugs in swagger-parser require me to skip certain tests because the parser is omitting or incorrectly processing document data. Of all those bugs, this one blocks the largest number of json schema tests.
Per this PR I count >= 85 test schemas that are excluded by boolean schemas not being processed correctly. This could easily be > 170 tests that are skipped because each test schema can have n tests running against it.
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
Start by reproducing the issue with the supplied OpenAPI 3.1.0 sample and compare parser output for each listed boolean-schema location. Use the JSON Schema Test Suite cases referenced in the report to check behavior. Done means boolean schemas are retained and parsed without errors, including the listed array, object, combinator, and prefixItems examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100