new rule: $ref noticed in invalid places

[XVincentX]

In both OAS2 and OAS3, $ref is only allowed in certain places. Spectral is resolving all references anywhere, instead of following the rules of the specification.

Consider this document:

swagger: "2.0"
host: localhost
info:
  description: bar
  title: "IO APIs, shared specs"
  version: "0.1"
paths: {}
definitions:  # definitions non può contenere $ref
  $ref: file.yml

This is technically invalid OAS2, since refs is not allowed here. Spectral does not give any feedback, just says this is valid.

I understand and support the use case, however it would be great if I could at least see a warning saying "Yo man, I resolved this for you but you should not do this"

[P0lip]

I'm assuming Spectral is resolving the references for me any way and that's why the validation is passing.

Yeah, that's exactly the cause of the issue. oas2-schema and oas3-schema operate on resolved content, therefore they have no idea about $refs at the time they are executed.

[philsturgeon]

@XVincentX did you actually mean to say "$refs are not allowed in OpenAPI 2 documents" or did you mean to say something else? Because $ref is definitely allowed in OpenAPI v2 documents.

[XVincentX]

I'm sorry I didn't clarify enough — refs are not supported in the definitions section — it must be just a dictionary of Schema Objects

[philsturgeon]

Ah yeah absolutely. That's confused me in the past. Some tools just resolve everything everywhere and some tools only resolve the specific allowed places. If we resolve everything all the time we are going against the spec, furthering confusion, and giving people a false sense of security in their description docs which might not work in other places outside of stoplight.

But if we error we're being to strict, so it sounds like a warning is pretty consistent with how we want to deal with this sort of thing.