Support x-sunset/deprecated at parameter level

[pledesert-sg]

Is your feature request related to a problem? Please describe.
It may be necessary to remove an optional field. openapi support parameter deprecation, but oasdiff ignores it.

Describe the solution you'd like
Treat parameter deprecation the same as route deprecation, (a parameter should have an associated x-sunset valid with the route grace period)

Describe alternatives you've considered
Alternative will be to use oneOf and deprecation of schema, but it is even trickier for oasdiff (migrating existing schema to oneOf is considered a breaking change). Other alternative is to deprecate the whole route, and create a new route with version, but it is not optimal and respectful of REST principles.

Additional context
orig.yml:

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

deprecate.yml:

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  deprecated: true
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

deprecated_with_sunset.yml

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  deprecated: true
                  x-sunset: '2022-10-01'
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

removed.yml

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

---

$ oasdiff breaking --fail-on WARN orig.yml deprecate.yml ; echo $?

0

-> no sunset, expected missing sunset warning

---

$  oasdiff breaking --fail-on WARN deprecated_with_sunset.yml removed.yml ; echo $?
1 changes: 0 error, 1 warning, 0 info
warning [request-property-removed] at removed.yml
        in API POST /echo
                removed the request property 'message'


1

• deprecated after sunset end, expecting no warning

[reuvenharrison]

Hi @pledesert-sg
You are right. Deprecation is currently supported only for endpoints.
Supporting deprecation for schemas would require adapting the endpoint deprecation code to schemas.
Maybe someone from the community wants to pick this up?

Thanks,
Reuven