Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecate Path Item Object ref field (#2635) #2656

Merged
merged 3 commits into from
Mar 10, 2022

Conversation

char0n
Copy link
Contributor

@char0n char0n commented Jul 23, 2021

The field has been deprecated in favor of
using Reference Object in OAS 3.2.0 and forward.

Signed-off-by: Vladimir Gorej [email protected]

 The  field has been deprecated in favor of
using Reference Object in OAS 3.2.0 and forward.

Signed-off-by: Vladimir Gorej <[email protected]>
@char0n
Copy link
Contributor Author

char0n commented Jul 23, 2021

Not really sure if my wording in deprecation message is ideal. I'm very open to any suggestions ;]

@MikeRalphson
Copy link
Member

Hmm. I think $ref within a pathItem object is a useful construct for OAS document composition, and it is only the $ref field with sibling operationObject properties which appears to be almost unused and I feel should be deprecated. As your PR #2655 removes the ambiguous use of referenceObjects to refer to pathItems, the $ref field remains the only way to refer to pathItems in external resources.

As to wording, I feel we should not "throw forward" to other versions of the spec, for two reasons:

  • it may imply an ordering in which we need to release v3.2.0 and v3.1.1
  • versions of the spec beyond v3.2.0 (such as a v4.x) may handle this in different ways

so personally, I would prefer the wording to be self-contained as to the situation within the version of the spec the markdown file refers to.

@char0n
Copy link
Contributor Author

char0n commented Jul 23, 2021

Yep, fully agree. I'll try to come up with self-contained wording deprecating just use-case of $ref accompanied with operation fields.

@char0n
Copy link
Contributor Author

char0n commented Jul 29, 2021

We've came up with 3 possible versions of deprecation message (thanks @frankkilcommins)

1.)

The usage of `$ref` property has been deprecated when accompanied with other properties different from `summary` and `description`.

2.)

Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`.

3.)

Usage of the `$ref` property has been deprecated for use cases where properties other than `summary` and/or `description` are specified within the Path Item Object.

@MikeRalphson please let me know which one works best for you and I'll amend the PR.

@char0n
Copy link
Contributor Author

char0n commented Aug 4, 2021

@MikeRalphson just pinging here, regarding my last comment.

@char0n
Copy link
Contributor Author

char0n commented Aug 26, 2021

I've pushed one of the sentence that I thought is most appropriate.

@karenetheridge
Copy link
Member

Can you add deprecated: true to the corresponding section in the schema.yaml file?

@char0n
Copy link
Contributor Author

char0n commented Aug 27, 2021

@karenetheridge sure, but I'm not sure it's possible at this time. As already stipulated here current JSON Schema doesn't properly validate what the spec is defining. We would first need to completely fix the schema before we can introduce deprecated keyword.

@karenetheridge
Copy link
Member

Maybe this should be in a separate PR, but should this bit of the schema be changed?

 $id: 'https://spec.openapis.org/oas/3.1/schema/2021-05-20'
 $schema: 'https://json-schema.org/draft/2020-12/schema'
 type: object
 ...
 $defs:
 ...
   paths:
     type: object
     patternProperties:
       '^/':
-        $ref: '#/$defs/path-item'
+        $ref: '#/$defs/path-item-or-reference'
     $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false

@ivank
Copy link

ivank commented Jan 31, 2022

Doesn't path-item always allow "reference"? At least that's what the wording on it seems to imply.
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-item-object

Its been weird that some tooling are allowing openapi paths to be reference, for easier splitting into separate files, but this validation actually prevents this. Maybe I'm reading this wrong but the spec actually state that all paths should be able to be references?

@webron webron merged commit 17970c5 into OAI:v3.1.1-dev Mar 10, 2022
charjr pushed a commit to charjr/OpenAPI-Specification that referenced this pull request Apr 27, 2023
* Deprecate Path Item Object ref field (OAI#2635)

 The  field has been deprecated in favor of
using Reference Object in OAS 3.2.0 and forward.

Signed-off-by: Vladimir Gorej <[email protected]>

* Deprecate Path Item Object ref field specific usecases

Refs OAI#2635

* fix change
charjr pushed a commit to charjr/OpenAPI-Specification that referenced this pull request Apr 27, 2023
* Deprecate Path Item Object ref field (OAI#2635)

 The  field has been deprecated in favor of
using Reference Object in OAS 3.2.0 and forward.

Signed-off-by: Vladimir Gorej <[email protected]>

* Deprecate Path Item Object ref field specific usecases

Refs OAI#2635

* fix change
@handrews handrews added this to the v3.1.1 milestone May 17, 2024
@handrews handrews added the re-use: traits/merges Selective or modified re-use label May 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
re-use: traits/merges Selective or modified re-use
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants