Deprecate Path Item Object ref field (#2635)

[char0n]

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

Signed-off-by: Vladimir Gorej vladimir.gorej@gmail.com

[char0n]

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

[MikeRalphson]

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]

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

[char0n]

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]

@MikeRalphson just pinging here, regarding my last comment.

[char0n]

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

[karenetheridge]

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

[char0n]

@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]

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]

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?