From dd48f9ec7e04f1ce97d208c13431b808d6871471 Mon Sep 17 00:00:00 2001 From: Chuck Heazel Date: Fri, 15 Mar 2019 16:26:04 -0400 Subject: [PATCH 1/4] 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 2/4] 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 3/4] 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 4/4] 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