{"action":"created","issue":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1532","repository_url":"https://api.github.com/repos/OAI/OpenAPI-Specification","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1532/labels{/name}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1532/comments","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1532/events","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/1532","id":312379009,"number":1532,"title":"Proposal: x-oas-draft-alternativeSchemas ","user":{"login":"darrelmiller","id":447694,"avatar_url":"https://avatars2.githubusercontent.com/u/447694?v=4","gravatar_id":"","url":"https://api.github.com/users/darrelmiller","html_url":"https://github.com/darrelmiller","followers_url":"https://api.github.com/users/darrelmiller/followers","following_url":"https://api.github.com/users/darrelmiller/following{/other_user}","gists_url":"https://api.github.com/users/darrelmiller/gists{/gist_id}","starred_url":"https://api.github.com/users/darrelmiller/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/darrelmiller/subscriptions","organizations_url":"https://api.github.com/users/darrelmiller/orgs","repos_url":"https://api.github.com/users/darrelmiller/repos","events_url":"https://api.github.com/users/darrelmiller/events{/privacy}","received_events_url":"https://api.github.com/users/darrelmiller/received_events","type":"User","site_admin":false},"labels":[{"id":895077835,"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/labels/draft-feature","name":"draft-feature","color":"ffc6c9","default":false},{"id":933073817,"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/labels/draft:proposal","name":"draft:proposal","color":"e8cb96","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":44,"created_at":"2018-04-09T03:17:41Z","updated_at":"2018-05-18T16:05:20Z","closed_at":null,"author_association":"MEMBER","body":"A long standing request has been to add support for alternate schemas.  See #764  #1443 \r\n\r\nThere are many concerns about the effect this will have on the tooling ecosystem, however, there is also a strong desire from the community to support both more recent versions of JSON Schema and other formats such as XSD Schema, Protobuf Schema.\r\n\r\nInstead of simply adding this feature to the specification and hoping that tooling vendors will implement it.  I propose we use the draft feature (PR #1531 ) process to validate the value and feasibility of this feature.\r\n\r\n```\r\nopenapi: 3.0.2\r\ninfo:\r\n  title: A sample using real JSON Schema and xsd\r\n  version: 1.0.0\r\npaths:\r\n  /:\r\n    get:\r\n      responses:\r\n        '200':\r\n          description: Ok\r\n          content:\r\n            application/json:\r\n              x-oas-draft-alternate-schema:\r\n                type: json-schema\r\n                externalValue: ./rootschema.json\r\n            application/xml:\r\n              x-oas-draft-alternate-schema:\r\n                type: xml-schema\r\n                externalValue: ./rootschema.xsd\r\n```\r\n\r\n- The property is called `alternate-schema` because it can be used in instead of, or in addition to the OAS Schema object.  If both are present then both schemas must be respected.\r\n- The `type` field is required and must match one of the values identified in an alternate schema registry which will be created as part of this proposal.  The alternate schema registry will provide a link to a specification for the schema file.\r\n- It is recommended that tools provide users with warnings when they encounter an alternate schema `type` that they do not support.  Tools should not fail to process a description, unless the schema is essential to the operation. Ideally they should continue as if the alternate-schema is not present in a form of graceful degradation.\r\n- The `externalValue` property is required and must be a relative or absolute URL.\r\n- The `alternate-schema` property can be used anywhere the `schema` property can be used.\r\n\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments/390254841","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/1532#issuecomment-390254841","issue_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/1532","id":390254841,"user":{"login":"handrews","id":2358015,"avatar_url":"https://avatars2.githubusercontent.com/u/2358015?v=4","gravatar_id":"","url":"https://api.github.com/users/handrews","html_url":"https://github.com/handrews","followers_url":"https://api.github.com/users/handrews/followers","following_url":"https://api.github.com/users/handrews/following{/other_user}","gists_url":"https://api.github.com/users/handrews/gists{/gist_id}","starred_url":"https://api.github.com/users/handrews/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/handrews/subscriptions","organizations_url":"https://api.github.com/users/handrews/orgs","repos_url":"https://api.github.com/users/handrews/repos","events_url":"https://api.github.com/users/handrews/events{/privacy}","received_events_url":"https://api.github.com/users/handrews/received_events","type":"User","site_admin":false},"created_at":"2018-05-18T16:05:20Z","updated_at":"2018-05-18T16:05:20Z","author_association":"NONE","body":"@tedepstein \r\n\r\n> If the Schema Object does specify constraining properties, then the content must be JSON, and must conform to the native Schema Object constraints, as well as any alternative schemas.\r\n\r\nJSON Schema does not require the content to be JSON, only that the content can be mapped into [the data model](https://tools.ietf.org/html/draft-handrews-json-schema-01#section-4.2.1), which is derived from JSON.  Some media types, such as YAML as long as it doesn't use the more exotic features, are trivial to map, while others (XML) do not have an obvious mapping.\r\n\r\n> (Maybe) if the Schema Object specifies non-constraining properties like `title`, `definition`, and `documentation` those become part of the schema object definition, but do not require the content to be valid JSON.\r\n\r\nThis gets into the difference between [assertions](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-3.2) and [annotations](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01#section-3.3).  How annotations get used is application-defined, so OAS can say anything it wants about that."}}
{"actor":{"display_login":"handrews"}}