Clarify or remove language about "conflicts" in Path Item Object $ref property

The Path Item Object documentation for the $ref property says:

Allows for an external definition of this path item. The referenced structure MUST be in the format of a Path Item Object. If there are conflicts between the referenced definition and this Path Item's definition, the behavior is undefined.

I don't understand what conflict could arise. I assume that the value of this $ref property is a JSON Reference, like all of the other $ref properties defined in the spec. In that case, $ref should not have any sibling properties, and if it did, those would be ignored according to the JSON Reference spec.

So, for consistency and clarity, can we remove this language?

@webron

That $ref is not a Reference Object like the other ones. It is special. There are historical reasons why this happened. @webron explained it to me, but my memory is a sieve, so I forget the details. Yes it sucks that this is different. I'm not sure it can be fixed without breaking lots of existing specs.

@darrelmiller

Thanks @darrelmiller.

To clarify: I understand that this is not a Reference Object, as defined in the OpenAPI spec. But isn't it still a JSON Reference? Or, trying to be more precise: Shouldn't a Path Item Object having a valid $ref property (and no other properties) be treated as a JSON Reference Object, as described in the draft spec?

If so, JSON Reference specifies:

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

That would seem to preclude any possibility of the Path Item Object having a conflict between an inline definition and a referenced definition.

I don't see anything in the Path Item Object's $ref description saying that it should conform to JSON Reference. In fact, it doesn't say much at all about the expected value and semantics of the $ref property. It also doesn't assert the requirement that if $ref is present, all other Path Item Object properties are disallowed. I just assumed, as I think most users will, that this $ref is supposed to work like the other $ref properties, even if it's not defined in the same way, via Reference Object.

@webron, maybe you can help clear this up:

Would it really break something to add this constraint, and to say that the value of the $ref conforms to JSON Reference and JSON Pointer, same as it is in the Reference Object?
Is that breakage somehow more problematic than the other breakage that's being introduced in this major release?
If the TDC decides to make it a proper JSON Reference, would it be easier to change the Paths Object so that the /{path} pattern is typed as [Path Item Object | Reference Object], similar to other cases in the spec?

If $ref in the Path Item Object context really is a unique case, and needs to allow usage in combination with other properties, I think the spec should clarify this, and hopefully refer to some background describing the rationale.

It's something unfortunate we carry over from 2.0 as we had no time to deal with.
It is indeed not a JSON Reference. The referenced PIO is added to the path and that's where conflict may arise. Changing that would be a breaking change, and I'd rather avoid that at this stage of the spec cycle.

The referenced PIO is added to the path and that's where conflict may arise.

OK, sorry, I'm not sure I understand what that means.

Does it mean that the referenced path is relative to the referrer...? So that /foo containing $ref: "BarPath.yaml#/paths/~1bar" is supposed to describe the path /foo/bar ? (I hope not....)

Or does it mean that the properties of the referrent (external path item) are supposed to be merged in with the referrer (inline path item)? So /foo containing get and $ref: "FooPath.yaml#/paths/~1foo" can merge in FooPath.yaml#/paths/~1foo containing patch, yielding a single /foo path with get and patch methods?

Is this supposed to be a recursive merge? If /foo/get has responses/200, but no responses/404, would we merge in FooPath.yaml#/paths/~1foo/get/responses/404? Or does the precedence rule preclude any merging of a referenced get into an inline get?

It's this:

Or does it mean that the properties of the referrent (external path item) are supposed to be merged in with the referrer (inline path item)? So /foo containing get and $ref: "FooPath.yaml#/paths/~1foo" can merge in FooPath.yaml#/paths/~1foo/patch, yielding a single /foo path with get and patch methods?

And there's no recursive merge. If there's a get in both the referenced PIO and the containing one, it's invalid.

@webron

I made a small correction to my earlier description, for clarity:

...properties of the referrent (external path item) are supposed to be merged in with the referrer (inline path item). So /foo containing get and $ref: "FooPath.yaml#/paths/~1foo" can merge in FooPath.yaml#/paths/~1foo containing patch, yielding a single /foo path with get and patch methods.

(Emphasis added.)

@webron , thanks for clarifying. I will give this some thought & respond later...

Explain unclear semantics of property `$ref` in Path Item Object