From dd48f9ec7e04f1ce97d208c13431b808d6871471 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Fri, 15 Mar 2019 16:26:04 -0400 Subject: [PATCH 01/21] Alternative Schema Proposal This commit contains the markup for the Alternative Schema Proposal and some supporting documention. A directory structure is proposed so that the supporting data for a proposal is all in the same place. --- .../Alternative Schema Proposal.md | 114 ++++++++++++++++++ proposals/Alternative Schema/CONTRIBUTORS.md | 2 + proposals/Alternative Schema/DEVELOPMENT.md | 38 ++++++ .../Alternative Schema/implementations.md | 46 +++++++ 4 files changed, 200 insertions(+) create mode 100644 proposals/Alternative Schema/Alternative Schema Proposal.md create mode 100644 proposals/Alternative Schema/CONTRIBUTORS.md create mode 100644 proposals/Alternative Schema/DEVELOPMENT.md create mode 100644 proposals/Alternative Schema/implementations.md diff --git a/proposals/Alternative Schema/Alternative Schema Proposal.md b/proposals/Alternative Schema/Alternative Schema Proposal.md new file mode 100644 index 0000000000..ecc8093012 --- /dev/null +++ b/proposals/Alternative Schema/Alternative Schema Proposal.md @@ -0,0 +1,114 @@ +# OpenAPI Proposal - Alternative Schema + +## Status: Draft Feature + +## Version: March 15, 2019 + +## Related Issues [1532](https://github.com/OAI/OpenAPI-Specification/issues/1532) + +.Change Log + +|Date |Responsible Party |Description | +|---- | ---------------- | ---------- | +|3/15/19 |C. Heazel|Initial Markup Draft | + +## Introduction +This a proposal to add a new field called ``alternativeSchema`` to the OAS https://github.com/OAI/OpenAPI-Specification/issues/1532#schemaObject[Schema Object]. While still in draft, the field name will be prefixed with ``x-oas-draft-``. + +This draft feature 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. + +## Content Changes + +### 1) Extend the Schema Object + +#### Schema Object + +##### Fixed Fields + +|Field Name | Type | Description | +|---|:---:|--- | +|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | + +### 2) Add Alternative Schema Object + +#### 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. + +### 3) Add Alternative Schema Examples + +#### 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 + +### 4) Alternative Schema Registry + +#### Alternative Schema Registry + +*** Note this is a placeholder registry. Don't take the values seriously. *** + +The Alternative Schema Registry is located at https://spec.openapis.org/registries/alternative-schema[https://spec.openapis.org/registries/alternative-schema]. Inital contents of the registry include: + +|Name |Link |Description | +|--- | --- | --- | +|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema | diff --git a/proposals/Alternative Schema/CONTRIBUTORS.md b/proposals/Alternative Schema/CONTRIBUTORS.md new file mode 100644 index 0000000000..227901b37a --- /dev/null +++ b/proposals/Alternative Schema/CONTRIBUTORS.md @@ -0,0 +1,2 @@ +* Chuck Heazel [@cmheazel](https://github.com/cmheazel) +* Darrel Miller [@darrelmiller](https://github.com/darrelmiller) \ No newline at end of file diff --git a/proposals/Alternative Schema/DEVELOPMENT.md b/proposals/Alternative Schema/DEVELOPMENT.md new file mode 100644 index 0000000000..65ff4b1684 --- /dev/null +++ b/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 + diff --git a/proposals/Alternative Schema/implementations.md b/proposals/Alternative Schema/implementations.md new file mode 100644 index 0000000000..f1d61e48f2 --- /dev/null +++ b/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 | + + + From 24e15cbc6494f4f7bc9a83a6384975e1aa3c50f4 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 17 Apr 2019 13:47:32 +0200 Subject: [PATCH 02/21] Swift patterned update Updated the Alternative Schema proposal to follow the Apple SWIFT pattern. --- .../Alternative Schema Proposal.md | 128 ++++++------------ .../alternative_schema_examples.md | 51 +++++++ .../alternative_schema_object.adoc | 14 ++ proposals/Alternative Schema/schema_object.md | 10 ++ proposals/OAS-proposal-template.md | 44 ++++++ 5 files changed, 163 insertions(+), 84 deletions(-) create mode 100644 proposals/Alternative Schema/alternative_schema_examples.md create mode 100644 proposals/Alternative Schema/alternative_schema_object.adoc create mode 100644 proposals/Alternative Schema/schema_object.md create mode 100644 proposals/OAS-proposal-template.md diff --git a/proposals/Alternative Schema/Alternative Schema Proposal.md b/proposals/Alternative Schema/Alternative Schema Proposal.md index ecc8093012..c0f5c5e1ca 100644 --- a/proposals/Alternative Schema/Alternative Schema Proposal.md +++ b/proposals/Alternative Schema/Alternative Schema Proposal.md @@ -1,114 +1,74 @@ -# OpenAPI Proposal - Alternative Schema - -## Status: Draft Feature - -## Version: March 15, 2019 - -## Related Issues [1532](https://github.com/OAI/OpenAPI-Specification/issues/1532) - +# 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) +|Rationale |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/RATIONALE.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 https://github.com/OAI/OpenAPI-Specification/issues/1532#schemaObject[Schema Object]. While still in draft, the field name will be prefixed with ``x-oas-draft-``. - -This draft feature 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. - -## Content Changes - -### 1) Extend the Schema Object - -#### Schema Object - -##### Fixed Fields -|Field Name | Type | Description | -|---|:---:|--- | -|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | +This a proposal to add a new field called ``alternativeSchema`` to the OAS. -### 2) Add Alternative Schema Object +## Motivation -#### Alternative Schema Object +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. -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. +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. -===== Fixed Fields +## Proposed solution -|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 proposal makes the following changes to the OAS 3.0 specification: -This object MAY be extended with Specification Extensions. - -### 3) Add Alternative Schema Examples +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. -#### Examples +## Detailed design -Minimalist usage of alternative schema: +### Extend the Schema Object - schema: - x-oas-draft-alternativeSchema: - type: jsonSchema - location: ./real-jsonschema.json +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) -Combination of OAS schema and alternative: +### Add the Alternative Schema Object - schema: - type: object - nullable: true - x-oas-draft-alternativeSchema: - type: jsonSchema - location: ./real-jsonschema.json +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) -Multiple different versions of alternative schema: +### 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) - schema: - anyOf: - - x-oas-draft-alternativeSchema: - type: jsonSchema - location: ./real-jsonschema-08.json - - x-oas-draft-alternativeSchema: - type: jsonSchema - location: ./real-jsonschema-07.json +### Alternative Schema Registry -Combined alternative schemas: +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]. - schema: - allOf: - - x-oas-draft-alternativeSchema: - type: xmlSchema - location: ./xmlSchema.xsd - - x-oas-draft-alternativeSchema: - type: schematron - location: ./schema.sch +*** Note this is a placeholder registry. Don't take the values seriously. *** -Mixed OAS schema and alternative schema: +Inital contents of the registry will include: - schema: - type: array - items: - x-oas-draft-alternativeSchema: - type: jsonSchema - location: ./real-jsonschema.json +|Name |Link |Description | +|--- | --- | --- | +|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema | -### 4) Alternative Schema Registry +## Backwards compatibility -#### Alternative Schema Registry +This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly. -*** Note this is a placeholder registry. Don't take the values seriously. *** +## Alternatives considered -The Alternative Schema Registry is located at https://spec.openapis.org/registries/alternative-schema[https://spec.openapis.org/registries/alternative-schema]. Inital contents of the registry include: +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. -|Name |Link |Description | -|--- | --- | --- | -|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema | diff --git a/proposals/Alternative Schema/alternative_schema_examples.md b/proposals/Alternative Schema/alternative_schema_examples.md new file mode 100644 index 0000000000..5d72194b5b --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_examples.md @@ -0,0 +1,51 @@ +## Change: Add Alternative Schema Examples + +### 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 + diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.adoc new file mode 100644 index 0000000000..a6c6edec80 --- /dev/null +++ b/proposals/Alternative Schema/alternative_schema_object.adoc @@ -0,0 +1,14 @@ +## Change: Add the Alternative Schema Object + +### 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. diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md new file mode 100644 index 0000000000..59092746ee --- /dev/null +++ b/proposals/Alternative Schema/schema_object.md @@ -0,0 +1,10 @@ +## Change: Extend the Schema Object to support Alternative Schemas + +### Schema Object + +#### Fixed Fields + +|Field Name | Type | Description | +|---|:---:|--- | +|{existing} |{existing} |{existing} | +|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. | diff --git a/proposals/OAS-proposal-template.md b/proposals/OAS-proposal-template.md new file mode 100644 index 0000000000..9d2a0f5269 --- /dev/null +++ b/proposals/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. + From e727f104c6ee278ee9ac103ed0d0bfb0575c8be7 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 17 Apr 2019 14:15:54 +0200 Subject: [PATCH 03/21] Alternative Schema Cleanup Additional Cleanup to the Alternative Schema Proposal --- .../Alternative Schema Proposal.md | 3 +-- .../alternative_schema_examples.md | 4 +++- .../alternative_schema_object.adoc | 4 +++- proposals/Alternative Schema/schema_object.md | 13 ++++++++++--- proposals/OAS-proposal-template.md | 2 +- 5 files changed, 18 insertions(+), 8 deletions(-) diff --git a/proposals/Alternative Schema/Alternative Schema Proposal.md b/proposals/Alternative Schema/Alternative Schema Proposal.md index c0f5c5e1ca..737714dd0e 100644 --- a/proposals/Alternative Schema/Alternative Schema Proposal.md +++ b/proposals/Alternative Schema/Alternative Schema Proposal.md @@ -8,8 +8,7 @@ |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) -|Rationale |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/RATIONALE.md)| +|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) | diff --git a/proposals/Alternative Schema/alternative_schema_examples.md b/proposals/Alternative Schema/alternative_schema_examples.md index 5d72194b5b..96f7189576 100644 --- a/proposals/Alternative Schema/alternative_schema_examples.md +++ b/proposals/Alternative Schema/alternative_schema_examples.md @@ -1,6 +1,8 @@ ## Change: Add Alternative Schema Examples -### Examples +The following text is to be inserted after the Alternative Schema Object section. + +### Alternative Schema Examples Minimalist usage of alternative schema: diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.adoc index a6c6edec80..011f26b6b6 100644 --- a/proposals/Alternative Schema/alternative_schema_object.adoc +++ b/proposals/Alternative Schema/alternative_schema_object.adoc @@ -1,5 +1,7 @@ ## 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. @@ -7,7 +9,7 @@ This object makes it possible to reference an external file that contains a sche ==== 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. | diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md index 59092746ee..df8c64c8ff 100644 --- a/proposals/Alternative Schema/schema_object.md +++ b/proposals/Alternative Schema/schema_object.md @@ -1,10 +1,17 @@ ## Change: Extend the Schema Object to support Alternative Schemas -### Schema Object +The following content shall be used to replace the Fixed Fields table in the Schema Object section #### Fixed Fields |Field Name | Type | Description | -|---|:---:|--- | -|{existing} |{existing} |{existing} | +|---|:---:|---| +| 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. | diff --git a/proposals/OAS-proposal-template.md b/proposals/OAS-proposal-template.md index 9d2a0f5269..d6843f5bd2 100644 --- a/proposals/OAS-proposal-template.md +++ b/proposals/OAS-proposal-template.md @@ -9,7 +9,7 @@ |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)| +|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}) | From 059c4a138e460eaa2e5ff08951d04664072a5581 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Thu, 18 Apr 2019 18:56:14 +0200 Subject: [PATCH 04/21] April 18 update Moved proposal document up one level. Added numeric pre-fixes to proposal files. Per TSC meeting of April 18, 2019 --- .../{OAS-proposal-template.md => 000_OAS-proposal-template.md} | 0 ...tive Schema Proposal.md => 001_Alternative Schema Proposal.md} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename proposals/{OAS-proposal-template.md => 000_OAS-proposal-template.md} (100%) rename proposals/{Alternative Schema/Alternative Schema Proposal.md => 001_Alternative Schema Proposal.md} (100%) diff --git a/proposals/OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md similarity index 100% rename from proposals/OAS-proposal-template.md rename to proposals/000_OAS-proposal-template.md diff --git a/proposals/Alternative Schema/Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md similarity index 100% rename from proposals/Alternative Schema/Alternative Schema Proposal.md rename to proposals/001_Alternative Schema Proposal.md From 4a51b6f18ce78ac90c457b6c2305bc4c2bd509d6 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 1 May 2019 17:45:07 -0400 Subject: [PATCH 05/21] Cleanup from last TSC review Fixed broken links and typos. Changed names of the proposal phases based on TSC direction. --- proposals/000_OAS-proposal-template.md | 2 +- proposals/001_Alternative Schema Proposal.md | 7 ++++--- ...ive_schema_object.adoc => alternative_schema_object.md} | 0 3 files changed, 5 insertions(+), 4 deletions(-) rename proposals/Alternative Schema/{alternative_schema_object.adoc => alternative_schema_object.md} (100%) diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md index d6843f5bd2..acf8ee7fcb 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/000_OAS-proposal-template.md @@ -8,7 +8,7 @@ |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| +|Status |Draft, Pilot, Graduated, 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}) | diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 737714dd0e..1c76628579 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -5,9 +5,9 @@ |Tag |Value | |---- | ---------------- | |Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| -|Authors|[Chuck Heazel](https://github.com/{cmheazel})| +|Authors|[Chuck Heazel](https://github.com/cmheazel)| |Review Manager |TBD | -|Status |**Draft** | +|Status |**Pilot** | |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) | @@ -18,6 +18,7 @@ |---- | ---------------- | ---------- | |3/15/19 |C. Heazel|Initial Markup Draft | |4/17/19 |C. Heazel|Re-structured based on Apple Swift| +|5/1/19 |C. Heazel|Cleaned up typos and broken links. Updated the proposal stage names.| ## Introduction @@ -53,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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]. +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located [here](https://spec.openapis.org/registries/alternative-schema). *** Note this is a placeholder registry. Don't take the values seriously. *** diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.md similarity index 100% rename from proposals/Alternative Schema/alternative_schema_object.adoc rename to proposals/Alternative Schema/alternative_schema_object.md From 0db22da177b1c9cd18a18a74073dabdcc295b262 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 1 May 2019 17:48:20 -0400 Subject: [PATCH 06/21] Fixed URL for Registry --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 1c76628579..897c39ed27 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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 [here](https://spec.openapis.org/registries/alternative-schema). +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located [here](https://spec.openapis.org/registry/alternative-schema). *** Note this is a placeholder registry. Don't take the values seriously. *** From a912886143b2644f7960e16e84ee507edbfb0c8b Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 8 May 2019 08:02:00 -0400 Subject: [PATCH 07/21] Status update roll-back --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 897c39ed27..75ab1e6c6b 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -7,7 +7,7 @@ |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 |**Pilot** | +|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) | From c4c7c8213efa7532a472544b8162f21c161f842b Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 8 May 2019 08:12:01 -0400 Subject: [PATCH 08/21] Roll-back the roll-back --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 75ab1e6c6b..897c39ed27 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -7,7 +7,7 @@ |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** | +|Status |**Pilot** | |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) | From bc14281f0a9ceed9967179e5645afed4a1937dad Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:13:15 -0400 Subject: [PATCH 09/21] Update to work around conflicts --- proposals/000_OAS-proposal-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md index acf8ee7fcb..d6843f5bd2 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/000_OAS-proposal-template.md @@ -8,7 +8,7 @@ |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 |Draft, Pilot, Graduated, or Abandoned| +|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}) | From 753769410f2eb13425363b2f93eb7798443fcc93 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:16:12 -0400 Subject: [PATCH 10/21] Conflict resolution update Changes status value --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 897c39ed27..75ab1e6c6b 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -7,7 +7,7 @@ |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 |**Pilot** | +|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) | From a229147678da75a2c5bba0b44a9ec56355037b1d Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:19:12 -0400 Subject: [PATCH 11/21] Conflict resolution Added { } around cmheazel --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 75ab1e6c6b..12e11a972a 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -5,7 +5,7 @@ |Tag |Value | |---- | ---------------- | |Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| -|Authors|[Chuck Heazel](https://github.com/cmheazel)| +|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) From d1338b96b7a925b308ccbea55968a6173eb50047 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:21:40 -0400 Subject: [PATCH 12/21] Conflict resolution Changed "registry" to "registries" in registry URL --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 12e11a972a..b8f7c24736 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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 [here](https://spec.openapis.org/registry/alternative-schema). +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located [here](https://spec.openapis.org/registries/alternative-schema). *** Note this is a placeholder registry. Don't take the values seriously. *** From 8e948453e5144fe42bd5cb96fa699b6cf855ef98 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:25:23 -0400 Subject: [PATCH 13/21] Conflict resolution Added incorrect hyperlink for for registry in attempt to resolve conflict. --- proposals/001_Alternative Schema Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index b8f7c24736..297cea40fa 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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 [here](https://spec.openapis.org/registries/alternative-schema). +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] and [here](https://spec.openapis.org/registries/alternative-schema). *** Note this is a placeholder registry. Don't take the values seriously. *** From 1980cc0f0715ea6cf268870b3517bcc9890f5530 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:46:33 -0400 Subject: [PATCH 14/21] restore to previous --- proposals/000_OAS-proposal-template.md | 2 +- proposals/001_Alternative Schema Proposal.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md index d6843f5bd2..acf8ee7fcb 100644 --- a/proposals/000_OAS-proposal-template.md +++ b/proposals/000_OAS-proposal-template.md @@ -8,7 +8,7 @@ |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| +|Status |Draft, Pilot, Graduated, 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}) | diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 297cea40fa..897c39ed27 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -5,9 +5,9 @@ |Tag |Value | |---- | ---------------- | |Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)| -|Authors|[Chuck Heazel](https://github.com/{cmheazel})| +|Authors|[Chuck Heazel](https://github.com/cmheazel)| |Review Manager |TBD | -|Status |**Draft** | +|Status |**Pilot** | |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) | @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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] and [here](https://spec.openapis.org/registries/alternative-schema). +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located [here](https://spec.openapis.org/registry/alternative-schema). *** Note this is a placeholder registry. Don't take the values seriously. *** From f99a7974691290a8067297b1e2254ab4affe5caf Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:47:49 -0400 Subject: [PATCH 15/21] Deleted conflicting files --- proposals/000_OAS-proposal-template.md | 44 ------------ proposals/001_Alternative Schema Proposal.md | 74 -------------------- 2 files changed, 118 deletions(-) delete mode 100644 proposals/000_OAS-proposal-template.md delete mode 100644 proposals/001_Alternative Schema Proposal.md diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md deleted file mode 100644 index acf8ee7fcb..0000000000 --- a/proposals/000_OAS-proposal-template.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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 |Draft, Pilot, Graduated, 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. - diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md deleted file mode 100644 index 897c39ed27..0000000000 --- a/proposals/001_Alternative Schema Proposal.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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 |**Pilot** | -|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| -|5/1/19 |C. Heazel|Cleaned up typos and broken links. Updated the proposal stage names.| - -## 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 [here](https://spec.openapis.org/registry/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. - From a7bb859a75f2ce31bc13608b11a90b61c9a400e8 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 3 Jun 2019 16:58:11 -0400 Subject: [PATCH 16/21] Restored deleted files 000_OAS-proposal-template.md and 001_Alternative-Schema-Proposal.md were removed to fix conflict when merging back into OAI master. --- proposals/000_OAS-proposal-template.md | 44 ++++++++++++ proposals/001_Alternative-Schema-Proposal.md | 75 ++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 proposals/000_OAS-proposal-template.md create mode 100644 proposals/001_Alternative-Schema-Proposal.md diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md new file mode 100644 index 0000000000..acf8ee7fcb --- /dev/null +++ b/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 |Draft, Pilot, Graduated, 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. + diff --git a/proposals/001_Alternative-Schema-Proposal.md b/proposals/001_Alternative-Schema-Proposal.md new file mode 100644 index 0000000000..f3a63fbcc6 --- /dev/null +++ b/proposals/001_Alternative-Schema-Proposal.md @@ -0,0 +1,75 @@ +# 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 |**Pilot** | +|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| +|5/1/19 |C. Heazel|Cleaned up typos and broken links. Updated the proposal stage names.| + +## 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 [here](https://spec.openapis.org/registry/alternative-schema). + +*** Note this is a placeholder registry. Don't take the values seriously. *** + +Inital contents of the registry will include: + +|Value |Description |Issue | +|--- | --- | --- | +|jsonSchema |JSON Schema |#1532 | +|xsdSchema |XML Schema |#1532 | + +## 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. + From c8affb91cecfbb3362b4c3a2f17c881c34401d99 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Mon, 22 Jul 2019 19:20:50 -0400 Subject: [PATCH 17/21] Attempt to fix alternative schema July 22, 2019 --- proposals/000_OAS-proposal-template.md | 44 +++++++++++ proposals/001_Alternative Schema Proposal.md | 73 ------------------- .../alternative_schema_object.adoc | 16 ---- 3 files changed, 44 insertions(+), 89 deletions(-) create mode 100644 proposals/000_OAS-proposal-template.md delete mode 100644 proposals/001_Alternative Schema Proposal.md delete mode 100644 proposals/Alternative Schema/alternative_schema_object.adoc diff --git a/proposals/000_OAS-proposal-template.md b/proposals/000_OAS-proposal-template.md new file mode 100644 index 0000000000..acf8ee7fcb --- /dev/null +++ b/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 |Draft, Pilot, Graduated, 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. + diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md deleted file mode 100644 index 737714dd0e..0000000000 --- a/proposals/001_Alternative Schema Proposal.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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. - diff --git a/proposals/Alternative Schema/alternative_schema_object.adoc b/proposals/Alternative Schema/alternative_schema_object.adoc deleted file mode 100644 index 011f26b6b6..0000000000 --- a/proposals/Alternative Schema/alternative_schema_object.adoc +++ /dev/null @@ -1,16 +0,0 @@ -## 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. From 4ddc53fc0affb40e19143cc8b79ce7a2cf3e2a0e Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 21 Aug 2019 08:44:29 -0400 Subject: [PATCH 18/21] Changed registry URL Registry URL was causing a conflict with the master branch. --- proposals/001_Alternative-Schema-Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative-Schema-Proposal.md b/proposals/001_Alternative-Schema-Proposal.md index f3a63fbcc6..4b2e2c85ae 100644 --- a/proposals/001_Alternative-Schema-Proposal.md +++ b/proposals/001_Alternative-Schema-Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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 [here](https://spec.openapis.org/registry/alternative-schema). +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. *** From f56841f585c4f67b8599a1a8440c74161013582c Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 21 Aug 2019 08:57:06 -0400 Subject: [PATCH 19/21] Alternative Schema Registry URL --- proposals/001_Alternative-Schema-Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative-Schema-Proposal.md b/proposals/001_Alternative-Schema-Proposal.md index 4b2e2c85ae..ae4318add9 100644 --- a/proposals/001_Alternative-Schema-Proposal.md +++ b/proposals/001_Alternative-Schema-Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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]. +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 . *** Note this is a placeholder registry. Don't take the values seriously. *** From a1df975cbd098112712fc7c3311b06dd3a3729e8 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 21 Aug 2019 09:12:44 -0400 Subject: [PATCH 20/21] Merge branch 'master' of https://github.com/cmheazel/OpenAPI-Specification --- proposals/001_Alternative-Schema-Proposal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/001_Alternative-Schema-Proposal.md b/proposals/001_Alternative-Schema-Proposal.md index ae4318add9..9a86931531 100644 --- a/proposals/001_Alternative-Schema-Proposal.md +++ b/proposals/001_Alternative-Schema-Proposal.md @@ -54,7 +54,7 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI ### 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 . +Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. *** Note this is a placeholder registry. Don't take the values seriously. *** From 0d457a02766e9d7875ca65c48caf286c93f3ff93 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Wed, 21 Aug 2019 09:26:25 -0400 Subject: [PATCH 21/21] Delete 001_Alternative-Schema-Proposal.md --- proposals/001_Alternative-Schema-Proposal.md | 75 -------------------- 1 file changed, 75 deletions(-) delete mode 100644 proposals/001_Alternative-Schema-Proposal.md diff --git a/proposals/001_Alternative-Schema-Proposal.md b/proposals/001_Alternative-Schema-Proposal.md deleted file mode 100644 index 9a86931531..0000000000 --- a/proposals/001_Alternative-Schema-Proposal.md +++ /dev/null @@ -1,75 +0,0 @@ -# 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 |**Pilot** | -|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| -|5/1/19 |C. Heazel|Cleaned up typos and broken links. Updated the proposal stage names.| - -## 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. - -*** Note this is a placeholder registry. Don't take the values seriously. *** - -Inital contents of the registry will include: - -|Value |Description |Issue | -|--- | --- | --- | -|jsonSchema |JSON Schema |#1532 | -|xsdSchema |XML Schema |#1532 | - -## 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. -