{"action":"created","issue":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/536","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/536/labels{/name}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/536/comments","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/536/events","html_url":"https://github.com/OAI/OpenAPI-Specification/pull/536","id":125855820,"number":536,"title":"Replace $ref field by reference to jsonReference object","user":{"login":"joelwurtz","id":90466,"avatar_url":"https://avatars.githubusercontent.com/u/90466?v=3","gravatar_id":"","url":"https://api.github.com/users/joelwurtz","html_url":"https://github.com/joelwurtz","followers_url":"https://api.github.com/users/joelwurtz/followers","following_url":"https://api.github.com/users/joelwurtz/following{/other_user}","gists_url":"https://api.github.com/users/joelwurtz/gists{/gist_id}","starred_url":"https://api.github.com/users/joelwurtz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/joelwurtz/subscriptions","organizations_url":"https://api.github.com/users/joelwurtz/orgs","repos_url":"https://api.github.com/users/joelwurtz/repos","events_url":"https://api.github.com/users/joelwurtz/events{/privacy}","received_events_url":"https://api.github.com/users/joelwurtz/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-01-11T00:20:24Z","updated_at":"2016-01-11T21:28:29Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/536","html_url":"https://github.com/OAI/OpenAPI-Specification/pull/536","diff_url":"https://github.com/OAI/OpenAPI-Specification/pull/536.diff","patch_url":"https://github.com/OAI/OpenAPI-Specification/pull/536.patch"},"body":"This allow to have more consistency, and also better tool integration (as it can know a particular path can have a jsonReference)"},"comment":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments/170695322","html_url":"https://github.com/OAI/OpenAPI-Specification/pull/536#issuecomment-170695322","issue_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/536","id":170695322,"user":{"login":"webron","id":241629,"avatar_url":"https://avatars.githubusercontent.com/u/241629?v=3","gravatar_id":"","url":"https://api.github.com/users/webron","html_url":"https://github.com/webron","followers_url":"https://api.github.com/users/webron/followers","following_url":"https://api.github.com/users/webron/following{/other_user}","gists_url":"https://api.github.com/users/webron/gists{/gist_id}","starred_url":"https://api.github.com/users/webron/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/webron/subscriptions","organizations_url":"https://api.github.com/users/webron/orgs","repos_url":"https://api.github.com/users/webron/repos","events_url":"https://api.github.com/users/webron/events{/privacy}","received_events_url":"https://api.github.com/users/webron/received_events","type":"User","site_admin":false},"created_at":"2016-01-11T21:28:28Z","updated_at":"2016-01-11T21:28:28Z","body":"Thanks for this, but I'm afraid this doesn't work out. As you've noticed, but `schema` and `pathItem` already have a `$ref` in it which you removed and integrated elsewhere in a different manner.\r\n\r\nHowever, validation wise, the current state is the right one.\r\n\r\nFor `schema` `$ref`s, it is not *technically* forbidden to have other properties with `$ref`. The only thing the JSON Reference spec says is that other properties SHALL be ignored, but it does not say they cannot be included. If someone wishes to add a `description` with a `$ref` even though it 'SHALL' be ignored, so be it.\r\n\r\nFor the Path Item Object, the situation is a tad more complicated. We have made a mistake in version 2.0 of the spec by allowing `$ref` to live alongside other properties in that object. Yes, it breaks the JSON Reference spec, but when we realized that it was too late to change. So technically, the Swagger/OpenAPI Spec 2.0 allow for that to exist, regardless of how JSON References parsers behave. It's an unfortunate mistake that would hopefully be resolved in the next version, but the JSON Schema for the spec must represent that option as valid."}}