Alternative Schema Proposal

proposals/000_OAS-proposal-template.md

@@ -0,0 +1,44 @@
+# Feature name
+
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})|
+|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})|
+|Review Manager |TBD |
+|Status |Proposal, Draft, Promoted, or Abandoned|
+|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)|
+|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})|
+|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) |
+
+.Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+
+## Introduction
+
+A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing.
+
+## Motivation
+
+Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help OpenAPI developers create better code.
+
+## Proposed solution
+
+Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient?
+
+## Detailed design
+
+Describe the design of the solution in detail. This should include an exact description of the changes to the contents of the OpenAPI specification. That description should include a extract of each section of the OpenAPI specification which is impacted by the proposal with all proposed modifications applied. These extracts may be provided through additional files which are identified and described in this section.
+
+## Backwards compatibility
+
+Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed.
+
+## Alternatives considered
+
+Describe alternative approaches to addressing the same problem, and why you chose this approach instead.
+

proposals/001_Alternative Schema Proposal.md

@@ -0,0 +1,73 @@
+# Alternative Schema
+
+## Metadata
+
+|Tag |Value |
+|---- | ---------------- |
+|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)|
+|Authors|[Chuck Heazel](https://github.com/{cmheazel})|
+|Review Manager |TBD |
+|Status |**Draft** |
+|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md)
+|Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)|
+|Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) |
+
+.Change Log
+
+|Date |Responsible Party |Description |
+|---- | ---------------- | ---------- |
+|3/15/19 |C. Heazel|Initial Markup Draft |
+|4/17/19 |C. Heazel|Re-structured based on Apple Swift|
+
+## Introduction
+
+This a proposal to add a new field called ``alternativeSchema`` to the OAS.
+
+## Motivation
+
+OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used.
+
+For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be.
+
+## Proposed solution
+
+This proposal makes the following changes to the OAS 3.0 specification:
+
+1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field.
+1. Addition of the Alternative Schema Object.
+1. Addition of Alternative Schema examples.
+1. Addition of a preliminary discussion of the Alternative Schema registry.
+
+## Detailed design
+
+###  Extend the Schema Object 
+
+The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md)
+
+###  Add the Alternative Schema Object 
+
+The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md)
+
+### Provide Alternative Schema Examples
+Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md)
+
+### Alternative Schema Registry
+
+Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at https://spec.openapis.org/registries/alternative-schema[https://spec.openapis.org/registries/alternative-schema].
+
+*** Note this is a placeholder registry. Don't take the values seriously. ***  
+
+Inital contents of the registry will include:
+
+|Name  |Link  |Description | 
+|--- | --- | --- |
+|jsonSchema |TBD  |JSON Schema | |xsdSchema |TBD  |XML Schema |
+
+## Backwards compatibility
+
+This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly.
+
+## Alternatives considered
+
+Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language.
+

proposals/Alternative Schema/CONTRIBUTORS.md

@@ -0,0 +1,2 @@
+* Chuck Heazel [@cmheazel](https://github.com/cmheazel)
+* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)

proposals/Alternative Schema/DEVELOPMENT.md

@@ -0,0 +1,38 @@
+## Development Guidelines
+
+TBD
+
+## Specification Driving factors
+
+TBD
+
+## Specification Change Criteria
+
+TBD
+
+## Specification Change Process
+
+TBD
+
+## Tracking Process
+
+* GitHub is the medium of record for all spec designs, use cases, and so on.
+
+
+## Release Process
+
+TBD
+
+## Draft Features
+
+
+## Transparency
+
+
+
+## Participation
+
+
+
+## Community Roles
+

proposals/Alternative Schema/alternative_schema_examples.md

@@ -0,0 +1,53 @@
+## Change: Add Alternative Schema Examples
+
+The following text is to be inserted after the Alternative Schema Object section.
+
+### Alternative Schema Examples
+
+Minimalist usage of alternative schema:
+
+    schema:
+        x-oas-draft-alternativeSchema:
+          type: jsonSchema
+          location: ./real-jsonschema.json
+
+Combination of OAS schema and alternative:
+
+    schema:
+        type: object
+        nullable: true
+        x-oas-draft-alternativeSchema:
+            type: jsonSchema
+            location: ./real-jsonschema.json
+
+Multiple different versions of alternative schema:
+
+    schema:
+        anyOf:
+            - x-oas-draft-alternativeSchema:
+                type: jsonSchema
+                location: ./real-jsonschema-08.json
+            - x-oas-draft-alternativeSchema:
+                type: jsonSchema
+                location: ./real-jsonschema-07.json
+
+Combined alternative schemas:
+
+    schema:
+        allOf:
+            - x-oas-draft-alternativeSchema:
+                type: xmlSchema
+                location: ./xmlSchema.xsd
+            - x-oas-draft-alternativeSchema:
+                type: schematron
+                location: ./schema.sch
+
+Mixed OAS schema and alternative schema:
+
+    schema:
+        type: array
+        items:
+            x-oas-draft-alternativeSchema:
+                type: jsonSchema
+                location: ./real-jsonschema.json
+

proposals/Alternative Schema/alternative_schema_object.adoc

@@ -0,0 +1,16 @@
+## Change: Add the Alternative Schema Object
+
+The following text is to be inserted after the XML Object section
+
+### 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 |
+|---|:---:|---|
+|type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. |
+|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.

proposals/Alternative Schema/implementations.md

@@ -0,0 +1,46 @@
+# Implementations
+
+## Overview
+
+Below is a list of tooling that claims to implement the Alternative Schema proposal. While support for this feature matures, refer to the details of projects listed below for any notes about stability and roadmap. The process to improve the OpenAPI specification includes feedback from end-users and tooling creators. We strongly encourage draft tooling be made available for early users of OAS drafts.
+
+These tools are not endorsed by the OAI
+
+## Implementations:
+
+#### Low-Level tooling
+
+| Title | Project Link | Language | Description
+| ----------- | ----------- | ----------- | -----------
+|TBD |TBD |TBD |TBD |
+
+#### Editors
+
+| Title          | Project Link | Language |Description                          |
+|----------------|--------------|----------|---------------------|
+|TBD |TBD |TBD |TBD |
+
+#### User Interfaces
+
+| Title          | Project Link | Language |Description                          |
+|----------------|--------------|----------|---------------------|
+|TBD |TBD |TBD |TBD |
+
+#### Mock Servers
+| Title          | Project Link | Language | Description |
+| -------------- | ------------ | -------- | ----------- |
+|TBD |TBD |TBD |TBD |
+
+#### Server Implementations
+| Title          | Project Link | Language |Description          |
+|----------------|--------------|----------|---------------------|
+|TBD |TBD |TBD |TBD |
+
+#### Code Generators
+
+| Title          | Project Link | Language |Description          |
+|----------------|--------------|----------|---------------------|
+|TBD |TBD |TBD |TBD |
+
+
+

proposals/Alternative Schema/schema_object.md

@@ -0,0 +1,17 @@
+## Change: Extend the Schema Object to support Alternative Schemas
+
+The following content shall be used to replace the Fixed Fields table in the Schema Object section
+
+#### Fixed Fields
+
+|Field Name | Type | Description |
+|---|:---:|---|
+| nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.|
+| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. |
+| readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. |
+| writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. |
+| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. |
+| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema.
+| 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.|
+| deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.|
+|x-oas-draft-alternativeSchema  |alternative Schema Object  |An external schema that participates in the validation of content along with other schema keywords. |