swagger-api / swagger-api/swagger-parser

3.1.0 Boolean schemas are silently omitted or cause parsing errors

Open
#1,770 1 comment 2 reactions 0 assignees View on GitHub

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.