$ref objects are legal in all path-item objects

[karenetheridge]

See #2657 - this was added to the specification but not the schema.

[handrews]

@karenetheridge this should not be changed in the 3.1 schema, which I fixed to only allow Path Item Objects in #3355 (matching the 3.1.1 change in #2655).

This change would only go in the not-yet-existing 3.2 schema. I'm not sure whether we add that on this branch or on main (my recollection is that the 3.1 schema was added on main), but it should be clarified once we figure out our new branching policy.

I think for now it's better to close this, we should follow your advice and sync the 3.0 and 3.1 schemas (#3400) first, not to mention figure out how to deploy and set proper $ids for the accumulated changes in GitHub (#150, #2500) and then worry about setting up 3.2's schema. Otherwise it will be a 3rd out-of-sync schema given the current mess.

[karenetheridge]

ok I was assuming that schemas/3.1/schema.yaml here actually was the 3.2 schema, but just hadn't been renamed yet. But could it really be true that no schema changes have been made between 3.1.x and 3.2 yet?

[karenetheridge]

If someone could put a "blocked" label on this PR, I'd be much obliged.. and then I'll rebase it with the real 3.2 schema when it springs into existence.

[handrews]

@karenetheridge replacing my previous comments - I've been conveying how the process worked for 3.1. We can definitely change it, but I'm going to leave that to the TSC. Perhaps changing this to a "draft" PR would capture the "blocked" status?

[karenetheridge]

Setting to draft. I would highly recommend changing the process so the schema is kept current with the specification, and ideally change the schema in the same PR as spec changes (we don't have to force contributors to make schema changes, as someone else can add another commit to make that change if desired). But having the schema-in-waiting available would be enormously helpful for someone creating a beta implementation of an upcoming version before it is released.

e.g. right now I'm looking at what's changed in the spec for 3.2, and I'm having to make those changes in the schema myself - which would be duplicate work!

[handrews]

I've reworked the issues tracking schema management so that no one has to slog through over a decade of stale comments:

• Define and document our schema publishing process #3715
• Schema development: main or branch, in parallel or at release time? #3716

[ralfhandl]

Depends on

• Did we break 3.2 compatibility by removing the Path Item $ref special case? #3734

[handrews]

@karenetheridge since we're backing the spec change out (#3734, #4094) and it would need to be done in a new 3.2 schema anyway, I'm going to reluctantly close this. 😭

Even if we make a different change to improve the Path Item Object $ref, it will probably require a different schema change to describe it.