Ambiguity between Reference Object and PathItem Object

Hi everybody, not sure if this is the right place to ask this, but I’ve intercepted an ambiguity while building tooling for OAS 3.1

{
  "openapi": "3.1.0",
  "components": {
    "pathItems": {
      "pathItem1": {
        "$ref": "#/components/pathItems/pathItem2",
      },
      "pathItem2": {
        "summary": "path item summary",
        "description": "path item description",
        "get": {}
      }
    }
  }
}

Given following document, pathItem1 can be interpreted either as Reference Object or Path Item Object. It’s hard to tell what the author intended. He could have intended for pathItem1 to be a Reference Object. Or he may have intended pathItem1 to be a Path Item Object. As Path Item Object can have exactly the same shape as Reference Object the intention of the author is lost.

Can you please advice how to approach that?

Instead of having this ambiguity and $ref field in Path Item Object, wouldn’t it be cleaner to use Reference Object explicitly in every place where Path Item Object is allowed?

Current workaround could be assert the presence of $ref field and one of the other fixed fields from Path Item Object (like get, post, etc…). If assertion like that passes, we can say with limited certainty that author intended to define a Path Item Object.

[char0n]

@darrelmiller IMHO 3.1.1 - 1 and 3.1.1 - 3 contradict each other. If our aim is to remove $ref field field from Path Item Object in next breaking change release following steps seems like more appropriate:

3.1.1

The aim here is provide clarification to limit ambiguity

1. Clarification - Change Type Reference Object | Path Item Object in all places within spec to Path Item Object
2. Deprecate the use of $ref fixed field in Path Item Object

3.2.0

The aim here is to have only one referencing mechanism iwithing OAS 3.2 spec (reducing complexity) - Referece Object (JSON Schema spec has it’s own $ref mechanism)

1. Remove $ref from Path Item Object fixed fields
2. Change Type Path Item Object in all places within spec to Reference Object | Path Item Object

[char0n]

The schema doesn’t validate this properly. It only allows for a Path Item Object (with no Reference Object properties) OR a Reference Object. A Path Item Object with Reference Object properties would fail validation.

So this technically means that if Object looks like a Reference Object, it will always be considered a Reference Object.

What is the reason for including Reference Object properties in Path Item Object as opposed to just using a Reference Object?

As @webron mentioned it’s a remnant from older specifications, where components/pathItems fields did not exist and Paths Object only allows Path Item Object as a value of it’s pattern fields. So including $ref field in Path Item Object was the only way to reference another Path Item Object from Paths Object.

It also doesn’t seem very well specified. It doesn’t specify how a reference works in this context, but implies that there differences from a normal Reference Object. A Reference Object has rules for merging “summary” and “description”, but other properties are not merged in the referenced object. Path Item Object implies that some merging takes place, but doesn’t specify how (e.g. deep or shallow merge)

As the merging rules as undefined by the specification, tooling authors have to come up with something that makes sense. I’ve chosen the same merging rules as Reference Object and Schema Object follows. Fields from referencing object will shallowly override fields from referenced object.

Is it assumed that Reference Object behaviors apply here unless otherwise specified? Do the merging rules for “summary” and “description” in a Reference Object apply?

Acoording to this: 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. the Reference Oject behaviors don’t apply and the behavior is undefined.

As a workaround, I think you can always treat a $ref as part of the Path Item Object and never a Reference Object and always get what the user intended.

This would contradict the current schema validation. IMHO better way and possibly more forward compatible one would be to stay with the current validation and consider everything that looks like a Reference Object a Reference Object.

If a Path Item Object only has Reference Object properties, it would evaluate the same as if it were a Reference Object. The only difference in processing it as a Reference Object is that any Path Item Object properties will be ignored. Since the user wouldn’t include Path Item properties if they expected those properties to be ignored, we can be confident that if those properties appear, we should process it as a Path Item Object. I think that in all cases, processing it as a Path Item Object should result in the desired behavior.

So if I understand this correctly, whenever there there is a choice between Reference Object | Path Item Object and the Object defines a $ref field, we should always consider it a Path Item Object. This will have an implication on fields merging as Path Item Object doesn’t define it and every tooling author can choose how to define the merging. It is also not aligned with current schema validation.

I still think that this is problematic and opens door for unnecessary interpretations. In order to reduce the complexity and eliminate the ambiguity I propose following:

• remove $ref field from Path Item Object
• define a Type for Paths Object field pattern as this: Path Item Object | Reference Object

This small change will make things right in backward compatible manner.