Proposal to enable support for alternate schemas

After reading the updated documentation for examples in PR 636 I realized we may be able to use the exact same approach for schemas.

As I understand it, in OpenAPI.vNext, examples come in one of three flavours:

• A JSON object, which infers the payload is some media type that is based on JSON.
• A string, which infers the contents of the example string comply with the declared media type of the response.
• A $ref which points to a file, that contains a sequence of bytes that correspond to the media type of the response.

The 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.

I’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.

Users 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 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.

Those who do wish to support non-JSON content get the same mechanism for both Schemas and Examples.

Building on the “representations/content” proposal , a header object could be described like this:

{
   "headers": {
       "my-user-agent" : {
          "content"  : {
             "text/plain" : {
                     "schematype" : "HTTP-ABNF",
                     "schema" : "product *( RWS ( product / comment ) )",
                     "examples" : [
                                  "foo/v1.0 (Yo! like my app?) OS/2.0"
                          ]
                   }
           }
      }
  }
}

This also brings another interesting possibility. Consider the following path parameter.

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "content": {
    "text/plain": {
       "schematype":"rfc6570",
       "schema" : ";username*" 
    }
  }
}

This 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.

And 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.

[olensmar]

I general I don’t think it’s a good idea to let existing tooling dictate what we put in future versions of the spec - but on the other hand the spec shouldn’t be too “academic” for its own good and push tooling vendors away if is too complex to support. In this case I’m stuck in the middle; I understand that creating tooling that supports all kinds of schema languages is unrealistic - but it’s equally unrealistic to expect users to translate their existing schemas to JSON Schema to be able to use the spec (which seems to be a common scenario).

Middle ground could be to have an “official extension” - (“x-schema” or something) for this that tooling can optionally support - but that puts this at risk of going down the WS-* route, which is a mess to say the least.

Another possibility could be to have a (very) fixed set of schema types (JSON-Schema and XML-Schema) initially supported in OAS 3.0 - and others to be considered further down the road if a general need arises.

[olensmar]

just my 5 cents; I’ve talked to several teams transitioning from SOAP to REST but wanting to keep the XML-Schemas in which they’ve modeled their domains, allowing them to reference an external existing schema would definitely help in this scenario as JSON Schema is not a viable alternative in most cases