Alternative Schema and Custom Security Schemes

versions/3.1.0.md

@@ -2324,6 +2324,7 @@ Field Name | Type | Description
 <a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
 <a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
 <a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+<a name="alternativeSchema"></a>alternativeSchema | [Alternative Schema Object](#alternativeSchemaObject) | An external schema that participates in the validation of content along with other schema keywords.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -3162,25 +3163,109 @@ animals:
 </aliens>
 ```
 
+#### <a name="alternativeSchemaObject"></a>Alternative Schema Object
+
+This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the ``type``, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="alternativeSchemaType"></a>type | `string` | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry.
+<a name="alternativeSchemaLocation"></a>location | `url` | **REQUIRED**.  This is a absolute or relative reference to an external resource containing a schema of a known type.  This reference may contain a fragment identifier to reference only a subset of an external document.
+
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
+
+##### Examples
+
+Minimalist usage of alternative schema:
+
+```yaml
+schema:
+  alternativeSchema:
+    type: jsonSchema
+    location: ./real-jsonschema.json
+```
+
+Combination of OAS schema and alternative:
+
+```yaml
+schema:
+  type: object
+  nullable: true
+  alternativeSchema:
+    type: jsonSchema
+    location: ./real-jsonschema.json
+```
+
+Multiple different versions of alternative schema:
+
+```yaml
+schema:
+  anyOf:
+  - alternativeSchema:
+      type: jsonSchema
+      location: ./real-jsonschema-08.json
+  - alternativeSchema:
+      type: jsonSchema
+      location: ./real-jsonschema-07.json
+```
+
+Combined alternative schemas:
+
+```yaml
+schema:
+  allOf:
+  - alternativeSchema:
+      type: xmlSchema
+      location: ./xmlSchema.xsd
+  - alternativeSchema:
+      type: schematron
+      location: ./schema.sch
+```
+
+Mixed OAS schema and alternative schema:
+
+```yaml
+schema:
+  type: array
+  items:
+    alternativeSchema:
+        type: jsonSchema
+        location: ./real-jsonschema.json
+```
+
+##### Alternative Schema Registry
+
+It is important that there is a common understanding of the values which can be used to populate the alterative schema "type" property. An registry of alternative schema types is hosted at [https://spec.openapis.org/registries/alternative-schema](https://spec.openapis.org/registries/alternative-schema). This register serves as a controlled vocabulary which should be used to populate the "type" property.  The Inital contents of the registry include:
+
+Name | Link | Description
+---|:---:|---
+<a name="jsonSchemaType"></a>jsonSchema | `https://spec.openapis.org/registries/alternative-schema#jsonSchema` | JSON schema documents
+<a name="xmlSchemaType"></a>xsdSchema | `https://spec.openapis.org/registries/alternative-schema#xsdSchema` | XML schema documents 
+<a name="schematronType"></a>schematron | `https://spec.openapis.org/registries/alternative-schema#schematron` | XML schematron rule sets 
+
 #### <a name="securitySchemeObject"></a>Security Scheme Object
 
 Defines a security scheme that can be used by the operations.
-Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). Additional "custom" schemes can be described but the level of tool support will be limited.
 
 ##### Fixed Fields
 Field Name | Type | Applies To | Description
 ---|:---:|---|---
-<a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
+<a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`, `"custom"`.
 <a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
 <a name="securitySchemeScheme"></a>scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).
 <a name="securitySchemeBearerFormat"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted.  Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
 <a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
 <a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
+<a name="customType"></a>extensionType | `string` | `custom` | **REQUIRED**. When the security scheme type is custom, the customType field provides an identifier for the type of custom scheme. The valid values for this field are not controlled. Use of a well known identifier or MIME Type is encouraged to avoid collisions.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
+Custom schemes may be processed in much the same manner as extensions. Implementations shall accept "custom" as a valid value for the securitySchemeType field.  They shall also validate that the customType field is present and populated when the value of securitySchemeType is "custom". Any additional data needed to describe the custom schema shall be provided using [Specification Extensions](#specificationExtensions). 
+
 ##### Security Scheme Object Example
 
 ###### Basic Authentication Sample