About the $ref in header objects of mozilla.com/kinto/1.14/swagger.yaml

[timburks]

Is this valid?

When I look in the 2.0 schema or the specification, I don't see any mention of $ref being supported for header objects, although it is specifically mentioned in other parts of the spec, like here.

OTOH, if $ref can be allowed in arbitrary places, I'm confused as to why it is explicitly mentioned in the OpenAPI spec.

[MikeRalphson]

I'll have to take a look. I know I had to modify my converter/validator because of that slightly strange header $ref construct. I'm surprised swagger-parser doesn't flag it up, as that does a validation pass against the schema, but perhaps that uses a modified / loosened version of the official schema? Or perhaps it only validates against the schema after resolving all the $refs, and is using a valid-anywhere JSON-schema approach to $refs.

[whitlockjc]

In 2.0, $ref is not allowed everywhere. The problem depends on how the parsing/validating tools work. If you dereferenced all $ref prior to validating, you're unlikely to see JSON Schema validation errors due to $ref being in the wrong place. If you validate the original source prior to dereferencing the $refs, you should see JSON Schema validation errors if they are in the places not permitted by 2.0.

[MikeRalphson]

@timburks So, the consensus is that it's not valid, but it may not get fixed, owing to us not knowing how many other definitions are affected, as neither of the validators we use spot the problem.

Or is this the only example shown up by Gnostic tools?

Including @gabisurita as the submitter of the definition originally.

[whitlockjc]

Since JSON Reference is a non-OAI thing, I think it's fine to use JSON References wherever you want so long as when you're done processing it and hand it to some OAI tooling, things are where they should be. And then as I type this, I realize that allowing such things could be confusing so maybe it's better to just avoid it and use tooling that catches it?

Speaking of, sway has an open issue to handle this better and I can fix it as soon as I release the updated json-refs this week. I don't expect you to wait for this fix but just giving you a heads up.

[MikeRalphson]

Tim confirmed the Kinto definition is the only one in the collection with this problem.