OAS: External references in path items are broken

[ben-lc]

Expected Behavior

An external reference can be used on a path item with $ref key as specified in openapi 2+ specs :
Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a Path Item Object. In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving Relative References.
Adding an external reference should throw no error if it references a valid path item and should be handled by apicurio dereferencer.

Actual Behavior

In source mode an issue is thrown Path Item Reference must refer to a valid Path Item Definition . When preview or export with dereferencement is done an error is thrown.

Steps to Reproduce the Problem

1. open an openapi spec
2. in source mode add for example

paths:
    /stuffs:
        $ref: >-
            https://raw.githubusercontent.com/Apicurio/apicurio-data-models/refs/heads/1.x/src/test/resources/fixtures/dereference/oai3/domino-issue-1366.expected.json#/paths/~1addresslookup

1. save the doc
2. try to preview the spec

Specifications

• apicurio studio: 0.2.62.Final
• apicurio data models: 1.1.30

Cause

The referenced path item node can't be fetched because / must be unescaped from ~1 to get correct path item key . (see Apitomy/apitomy-data-models#858).

The second error during dereference is because the Dereferencer class in apicurio-data-models doesn't implement path item case. It tries to add the referenced node into components and then change originel external ref to an internal one. But path items can't be defined in components. The referenced node is supposed to be "merged" according the spec.

Proposed fix

I can write a PR to fix the second issue. I propose to do a simple non recursive merge of the external path item properties into the internal one and ignore external path item properties if they are already defined in internal path item (since spec says In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined).

[ben-lc]

I created #3031 to fix a bug in uri creation when a path item references a path containing templates.

I created Apitomy/apitomy-data-models#859 in apicurio-data-models to update the Dereferencer in order to deal with path item ref as explained in the proposed fix.

Wdyt @EricWittmann

[EricWittmann]

I agree with your approach here. The local properties should take precedent over the remote properties, for sure. +1

Also this was a big miss in our dereferencing support in data-models, so thanks for catching this and contributing a fix. I'll need to forward-port your data-models work to v2, unless you feel motivated to do that yourself. :)

[EricWittmann]

Oh I see now that we haven't migrated the dereferencing functionality from v1 to v2 yet, so no need to forward-port the PathItem work you've done.

[EricWittmann]

I'm releasing data-models 1.1.31 now.

[ben-lc]

Great thanks.