Intended behaviour when $ref alongside other keywords?

[jamescrowley]

I've noticed that this library will de-reference $ref alongside other properties like this:

properties:
  $ref: "common.yaml"
  message_type:
    type: string

and in common.yaml

someCommonProp:
   type: string

becomes

properties:
  message_type:
    type: string
  someCommonProp:
    type:string

For context, I was using $ref in the above way, and looking to 'fix' the ordering of someCommonProp in the resulting document, before realising that this is 'mis-using' $ref (to my current understanding)

According to JSON Reference spec

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

Is there a current intended behaviour here?

I noted there's an issue regarding supporting the 2019-09 JSON Schema spec - #145 - which changes the approach to this, for which the above behaviour wouldn't be compatible with (from my limited understanding).

I just thought I'd flag the issue here, as it seems like we'd be on our way to making a breaking change to possibly undocumented behaviour that others also mistakenly rely on?

[philsturgeon]

Hey @jamescrowley!

This is one of many confusing things in OpenAPI and JSON Schema that tooling has rarely agreed upon despite being written down in the spec. 😓

Some tools will just look at ref siblings and carry on. Some will panic and fail. Seeing as OAS 3.1 and JSON Schema 2019-09 both agree on so many things, including that this is ok, it seems like this incorrect behavior will eventually become correct. 🤣

We could do with adding a default on switch to allow ref siblings, and people that really don't want them can turn it off. Then in some future major version the default could switch, or it could just automatically do the right thing based on the $schema version...

Either way, #helpwanted!

[Eli-Black-Work]

I think that in our project, we use $ref alongside other attributes. It's handy for merging bunch of common attributes and some custom attributes together 🙂

I like the idea of a flag toggling support for this 🙂

[philsturgeon]

I’m gonna make a call on this and let it continue doing what it’s doing. Tools like Spectral will let you pick the strictness of things like this and it already has a rule specifically alerting you to ref siblings. A rewrite of the lib is happening for modern JSON schema which allows them anyway, so at this point there doesn’t seem like much need for the library to restrict this or add toggles.

If anyone feels differently please do send a PR, but there’s loads of other work to be doing too! :)