Allow referencing Path Item only via Reference Object (#2635)

[char0n]

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

[gimbimloki]

@char0n @MikeRalphson
Hello. When OAS 3.2.0 is released, could I use Reference Objects in Paths Object like below?

paths:
  $ref: foo.yaml
  $ref: bar.yaml

[handrews]

@gimbimloki YAML does not allow for duplicate keys, so no (and that's not something OAS can change).

Duplicate keys in JSON are a more complex topic, but the TL;DR is that most JSON implementations don't support them in a usable way.

[gimbimloki]

@handrews Thank you for your reply.
So, Only one '$ref' can be in Paths Object, is it right?

[handrews]

@gimbimloki Keys must be unique in YAML. Non-unique keys in JSON do not have consistent behavior (usually one is discarded). Therefore it is impossible to have two $refs in the same object in YAML, and in JSON the result is unpredictable. It has nothing to do with the Paths Object, specifically, but the effect is that yes, you can only have one $ref in the Paths Object (or in any other object in this or any other YAML/JSON specification, no matter what).

[karenetheridge]

This change feels incomplete, as it's now allowing a path-item entry to be a regular reference, but then not changing the definition of a path-item itself to disallow $ref from being present adjacent to other path-item properties like summary, description, parameters, get etc.

So now (in 3.2.0), this is still legal:

paths:
  /pets/{petId}:
    $ref: "#/components/pathItems/one_pet"
components:
  pathItems:
    one_pet:
      $ref: "#/components/pathItems/more_pet_things"
      summary: a single pet
      get:
        ... operation things here
    more_pet_things:
      $ref: "#/components/pathItems/even_more_pet_things"
      description: ...
      post:
        ... operation things here
    even_more_pet_things:
      put:
        ...

...which means that when processing a request for PUT /pets/123 we end up getting bits of the request description from all of /components/path-items/*, which is the mess that we had in 3.1.0.

To fix this, I think we need to remove the $ref property from /$defs/path-item (which is a schema change). That way we can still have a chain of multiple $refs (just as we allow for other entity types like response, header etc) but no non-$ref fields can appear anywhere along the chain, only at the leaf.

Additionally, the reference under /paths/{path} (/$defs/paths/patternProperties/^~1/$ref) should be changed from #/$defs/path-item to #/$defs/path-item-or-reference.

(I can submit a PR to make this change for 3.2.)

---

addendum:

I misread the schema in the 3.2 branch -- it did not get the $ref property added to path-item (it was never in 3.1 until it was added in #3355, which did not propagate to the 3.2 branch). So most of my complaint above is moot -- there is just one small correction to make for 3.2, to allow for /paths/<some path>/$ref or to exist, so I'll submit that as a PR now.