Clarify if JSON References are restricted to properties that explicitly allow them

[tedepstein]

$ref properties and Reference Objects were a big point of confusion in 2.0, because some people assumed they were allowed anywhere within an OpenAPI spec. There are multiple Swagger-OpenAPI 2.0 tutorials that show disallowed use of $ref properties. Comments from @webron and others that eventually made it clear to me that JSON References are only allowed in specific contexts, where it's explicitly shown in the language spec.

I remember hearing that OpenAPI 3.0 was going to allow $refs anywhere. (Or at least, wherever an object of any kind is expected.) But I don't see any evidence of that change in the current 3.0 draft spec.

Can we assume that JSON References in OpenAPI 3.0 are still only allowed in the specific contexts described in the 3.0 spec? If so, that's fine, but I would suggest adding that restriction to the spec, so it's easy to find and understand. And if not, that change should also be called out explicitly.

[darrelmiller]

We have attempted to be explicit about where $ref can be used. Also, now that reusable stuff is contained in the components object it should be more clear about what can be $ref'd.

[tedepstein]

Also, now that reusable stuff is contained in the components object it should be more clear about what can be $ref'd.

OK, so is it fair to say that:

• The components object has typed maps of everything that can be $ref'd, with one exception...
• Path Items, which don't appear in components, can also be $ref'd (though not through Reference Objects, as discussed in Clarify or remove language about "conflicts" in Path Item Object $ref property #1038).
• Outside of the components section, wherever any of these referenceable objects is allowed, it can be specified inline, or by reference to an object conforming to the allowed type. (And the spec aims to be consistent with that general rule, by showing [ExpectedType | Reference Object] as the value space.)
• JSON References provided as $ref values don't have to refer to an object in the components map. The components object is provided as a convenient place to put referenceable objects, but a $ref can always point to a conforming object in any part of any legal JSON or YAML file.

Is that right?

[darrelmiller]

That is how I understand it, other than one really weird exception that I just realized when reading your fourth point. I have envisioned that $ref should only be used to reference things in the components collection. With the exception of an external reference that can reference in any arbitrary fragment of a JSON/YAML file.

However, I just realized that there is nothing stopping an external reference pointing back to the current OpenAPI spec, at which point you can point to any part of the document.

Therefore, your last statement is correct, but not what I was hoping. The idea of $refs being able to point to other operational parts of the spec, that might also reference other parts of the spec is a complexity that I had hope to avoid.

The only way to enforce what I was thinking is to require external docs to be valid OAS docs and only allow references into component sections. However, I know this would never fly with the TDC as there is already a feeling that our current use of $refs is too limiting.

[webron]

@darrelmiller - what @tedepstein summarized is pretty much the spirit of what we intended in 2.0, and have hopefully managed to capture in the changes to 3.0.

As for the fourth point, I believe that's right and intentional. We've had people $ref extensions before, or even, unfortunately, schemas from other inline definitions. I would never recommend doing either, but - a. any resolver shouldn't have an issue with it, and b. trying to restrict it in the spec would make it more cumbersome to read/write, and can be painful for tooling.

[tedepstein]

@webron , thanks for clarifying. Though it's possible to infer all of these things from the spec as it's written, I might still suggest stating them explicitly. I'm not sure exactly where these clarifications should be stated; probably in the Reference Object documentation.

When I get a moment, I'll open a PR with suggested clarifications, and you (collectively, the TDC) can decide if they improve the spec.

[handrews]

Given that we're very explicit about where Reference Objects are allowed (and we've done the best we can about the Path Item $ref mess), it's not clear to me what to do with this. @tedepstein did you ever decide on what clarifications would help? Otherwise I'm inclined to close this as probably having more to do with the confusion of moving from 2.0 to 3.0 than the current state of the spec.

[github-actions]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.