OpenAPITools / OpenAPITools/openapi-diff
Changing response field type from `oneOf: string, number` to `string` shouldn't break
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 1.1k
- Forks
- 190
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
In the response body, if you change the following field:
content:
application/json:
schema:
properties:
id:
oneOf:
- type: integer
- type: string
required:
- id
type: object
to:
content:
application/json:
schema:
properties:
id:
type: integer
required:
- id
type: object
Then openapi-diff reports this as a breaking change.
To Reproduce
base.yml
openapi: 3.0.1
info:
title: User Service
version: 1.0.0
paths:
/users:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: integer
required:
- name
required: true
responses:
201:
description: Created
content:
application/json:
schema:
properties:
id:
oneOf:
- type: integer
- type: string
required:
- id
type: object
revision.yml
openapi: 3.0.1
info:
title: User Service
version: 1.0.0
paths:
/users:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: integer
required:
- name
required: true
responses:
201:
description: Created
content:
application/json:
schema:
properties:
id:
type: integer
required:
- id
type: object
- Download the two files base.yml and revision.yml
- Run
openapi-diff breaking base.yml revision.yml - Observe the following output:
==========================================================================
== API CHANGE LOG ==
==========================================================================
User Service
--------------------------------------------------------------------------
-- What's Changed --
--------------------------------------------------------------------------
- POST /users
Return Type:
- Changed 201 Created
Media types:
- Changed application/json
Schema: Broken compatibility
Changed property type: id (object -> integer)
--------------------------------------------------------------------------
-- Result --
--------------------------------------------------------------------------
API changes broke backward compatibility
--------------------------------------------------------------------------
Expected behavior
openapi-diff shouldn't mark this as a breaking change. Actually, the response body should be considered as a covariant contract: narrowing a field type isn't a breaking change.
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 with the supplied base.yml and revision.yml files and run openapi-diff breaking base.yml revision.yml to reproduce the reported compatibility result. Trace the schema comparison path for the response property id, then add coverage showing that narrowing oneOf to type: integer is accepted and no breaking-change result is reported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100