{"action":"created","issue":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/764","repository_url":"https://api.github.com/repos/OAI/OpenAPI-Specification","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/764/labels{/name}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/764/comments","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/764/events","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/764","id":172348768,"number":764,"title":"Proposal to enable support for alternate schemas","user":{"login":"darrelmiller","id":447694,"avatar_url":"https://avatars.githubusercontent.com/u/447694?v=3","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":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":18,"created_at":"2016-08-21T23:48:20Z","updated_at":"2016-10-03T14:31:44Z","closed_at":null,"body":"After reading the updated documentation for `examples` in PR [636](https://github.com/OAI/OpenAPI-Specification/pull/636) I realized we may be able to use the exact same approach for schemas.\r\n\r\nAs I understand it, in OpenAPI.vNext, examples come in one of three flavours: \r\n-  A JSON object, which infers the payload is some media type that is based on JSON.\r\n- A string, which infers the contents of the example string comply with the declared media type of the response. \r\n- A $ref which points to a file, that contains a sequence of bytes that correspond to the media type of the response.\r\n\r\nThe documentation for examples states that if an example is a string, there is no guarantee that tooling will understand the media type of the example and be able to validate it.\r\n\r\nI'm proposing that we use the same mechanism to allow the Schema property to describe different schema types.  We would introduce the ability to assign a string primitive to the schema object, or use a $ref to point to a file containing a schema.  A new optional peer property called `schematype` is needed to identify the format of schema value.  Schematype values should be standardized by the OpenAPI specification using some kind of registry of known values, however, there is no requirement for tooling to support all schema types to be compliant with the OpenAPI specification.\r\n\r\nUsers of OpenAPI who wish to continue using only JSON and JSON Schema to describe their APIs can do so with no changes.  Those who wish to use Avro #466, or [JSON Content Rules](https://tools.ietf.org/html/draft-newton-json-content-rules-06) to describe their JSON can use a string or $ref schema value.  Using schemas like XSD, Relax-NG, Schematron, Kwalify for YAML, or ABNF for parameter values becomes possible.\r\n\r\nThose who do wish to support non-JSON content get the same mechanism for both Schemas and Examples.\r\n\r\nBuilding on the \"representations/content\" [proposal](https://github.com/OAI/OpenAPI-Specification/pull/761) , a header object could be described like this:\r\n\r\n```\r\n{\r\n   \"headers\": {\r\n       \"my-user-agent\" : {\r\n          \"content\"  : {\r\n             \"text/plain\" : {\r\n                     \"schematype\" : \"HTTP-ABNF\",\r\n                     \"schema\" : \"product *( RWS ( product / comment ) )\",\r\n                     \"examples\" : [\r\n                                  \"foo/v1.0 (Yo! like my app?) OS/2.0\"\r\n                          ]\r\n                   }\r\n           }\r\n      }\r\n  }\r\n}\r\n```\r\n\r\nThis also brings another interesting possibility.  Consider the following path parameter.\r\n\r\n```\r\n{\r\n  \"name\": \"username\",\r\n  \"in\": \"path\",\r\n  \"description\": \"username to fetch\",\r\n  \"required\": true,\r\n  \"content\": {\r\n    \"text/plain\": {\r\n       \"schematype\":\"rfc6570\",\r\n       \"schema\" : \";username*\" \r\n    }\r\n  }\r\n}\r\n```\r\nThis approach, in effect, enables all of the URI template goodness.  Matrix parameters, path segment parameters, unencoded parameters.  I'm not suggesting this is the best way to bring RFC 6570 support to OpenAPI, but it is the least intrusive way to do it.\r\n\r\nAnd one just one more thing...   For those people who want to use \"pure\" JSON  Schema, for whatever is the current definition of pure, so that external tools can validate the schemas, then they could choose to use this syntax for schemas instead of the Open API flavoured JSON Schema."},"comment":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments/251121337","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/764#issuecomment-251121337","issue_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/764","id":251121337,"user":{"login":"fehguy","id":249413,"avatar_url":"https://avatars.githubusercontent.com/u/249413?v=3","gravatar_id":"","url":"https://api.github.com/users/fehguy","html_url":"https://github.com/fehguy","followers_url":"https://api.github.com/users/fehguy/followers","following_url":"https://api.github.com/users/fehguy/following{/other_user}","gists_url":"https://api.github.com/users/fehguy/gists{/gist_id}","starred_url":"https://api.github.com/users/fehguy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fehguy/subscriptions","organizations_url":"https://api.github.com/users/fehguy/orgs","repos_url":"https://api.github.com/users/fehguy/repos","events_url":"https://api.github.com/users/fehguy/events{/privacy}","received_events_url":"https://api.github.com/users/fehguy/received_events","type":"User","site_admin":false},"created_at":"2016-10-03T14:31:44Z","updated_at":"2016-10-03T14:31:44Z","body":"@dilipkrish we did discuss how we handle \"experimental\" features in the spec, which are quite different from extensions.\r\n\r\n@olensmar there are many reasons why we decided to not do this, I suggest reviewing the discussion in the recordings if you want to get caught up.  It's not just a tooling issue, and unfortunately it's a little late in the process to chime in.  The spec can't be in flux forever"}}
{"actor":{"display_login":"fehguy"}}