Skip to content

Commit 4375616

Browse files
cmheazeldarrelmiller
cmheazel
authored and
darrelmiller
committed
Alternative Schema Proposal (#1868)
* 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. * Swift patterned update Updated the Alternative Schema proposal to follow the Apple SWIFT pattern. * Alternative Schema Cleanup Additional Cleanup to the Alternative Schema Proposal * April 18 update Moved proposal document up one level. Added numeric pre-fixes to proposal files. Per TSC meeting of April 18, 2019
1 parent 1bb2c28 commit 4375616

8 files changed

+289
-0
lines changed

‎proposals/000_OAS-proposal-template.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Feature name
2+
3+
4+
## Metadata
5+
6+
|Tag |Value |
7+
|---- | ---------------- |
8+
|Proposal |[NNNN](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{directory_or_file_name})|
9+
|Authors|[Author 1](https://github.com/{author1}), [Author 2](https://github.com/{author2})|
10+
|Review Manager |TBD |
11+
|Status |Proposal, Draft, Promoted, or Abandoned|
12+
|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/{NNNN}/implementations.md)|
13+
|Issues |[{issueid}](https://github.com/OAI/OpenAPI-Specification/issues/{Issueid})|
14+
|Previous Revisions |[{revid}](https://github.com/OAI/OpenAPI-Specification/pull/{revid}) |
15+
16+
.Change Log
17+
18+
|Date |Responsible Party |Description |
19+
|---- | ---------------- | ---------- |
20+
21+
## Introduction
22+
23+
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.
24+
25+
## Motivation
26+
27+
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.
28+
29+
## Proposed solution
30+
31+
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?
32+
33+
## Detailed design
34+
35+
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.
36+
37+
## Backwards compatibility
38+
39+
Proposals should be structure so that they can be handled by existing OAS compliant software. Any potential issues should be identified and discussed.
40+
41+
## Alternatives considered
42+
43+
Describe alternative approaches to addressing the same problem, and why you chose this approach instead.
44+

‎proposals/001_Alternative Schema Proposal.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Alternative Schema
2+
3+
## Metadata
4+
5+
|Tag |Value |
6+
|---- | ---------------- |
7+
|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)|
8+
|Authors|[Chuck Heazel](https://github.com/{cmheazel})|
9+
|Review Manager |TBD |
10+
|Status |**Draft** |
11+
|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md)
12+
|Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)|
13+
|Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) |
14+
15+
.Change Log
16+
17+
|Date |Responsible Party |Description |
18+
|---- | ---------------- | ---------- |
19+
|3/15/19 |C. Heazel|Initial Markup Draft |
20+
|4/17/19 |C. Heazel|Re-structured based on Apple Swift|
21+
22+
## Introduction
23+
24+
This a proposal to add a new field called ``alternativeSchema`` to the OAS.
25+
26+
## Motivation
27+
28+
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.
29+
30+
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.
31+
32+
## Proposed solution
33+
34+
This proposal makes the following changes to the OAS 3.0 specification:
35+
36+
1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field.
37+
1. Addition of the Alternative Schema Object.
38+
1. Addition of Alternative Schema examples.
39+
1. Addition of a preliminary discussion of the Alternative Schema registry.
40+
41+
## Detailed design
42+
43+
### Extend the Schema Object
44+
45+
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)
46+
47+
### Add the Alternative Schema Object
48+
49+
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)
50+
51+
### Provide Alternative Schema Examples
52+
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)
53+
54+
### Alternative Schema Registry
55+
56+
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].
57+
58+
*** Note this is a placeholder registry. Don't take the values seriously. ***
59+
60+
Inital contents of the registry will include:
61+
62+
|Name |Link |Description |
63+
|--- | --- | --- |
64+
|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema |
65+
66+
## Backwards compatibility
67+
68+
This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly.
69+
70+
## Alternatives considered
71+
72+
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.
73+

‎proposals/Alternative Schema/CONTRIBUTORS.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
* Chuck Heazel [@cmheazel](https://github.com/cmheazel)
2+
* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)

‎proposals/Alternative Schema/DEVELOPMENT.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Development Guidelines
2+
3+
TBD
4+
5+
## Specification Driving factors
6+
7+
TBD
8+
9+
## Specification Change Criteria
10+
11+
TBD
12+
13+
## Specification Change Process
14+
15+
TBD
16+
17+
## Tracking Process
18+
19+
* GitHub is the medium of record for all spec designs, use cases, and so on.
20+
21+
22+
## Release Process
23+
24+
TBD
25+
26+
## Draft Features
27+
28+
29+
## Transparency
30+
31+
32+
33+
## Participation
34+
35+
36+
37+
## Community Roles
38+

‎proposals/Alternative Schema/alternative_schema_examples.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Change: Add Alternative Schema Examples
2+
3+
The following text is to be inserted after the Alternative Schema Object section.
4+
5+
### Alternative Schema Examples
6+
7+
Minimalist usage of alternative schema:
8+
9+
schema:
10+
x-oas-draft-alternativeSchema:
11+
type: jsonSchema
12+
location: ./real-jsonschema.json
13+
14+
Combination of OAS schema and alternative:
15+
16+
schema:
17+
type: object
18+
nullable: true
19+
x-oas-draft-alternativeSchema:
20+
type: jsonSchema
21+
location: ./real-jsonschema.json
22+
23+
Multiple different versions of alternative schema:
24+
25+
schema:
26+
anyOf:
27+
- x-oas-draft-alternativeSchema:
28+
type: jsonSchema
29+
location: ./real-jsonschema-08.json
30+
- x-oas-draft-alternativeSchema:
31+
type: jsonSchema
32+
location: ./real-jsonschema-07.json
33+
34+
Combined alternative schemas:
35+
36+
schema:
37+
allOf:
38+
- x-oas-draft-alternativeSchema:
39+
type: xmlSchema
40+
location: ./xmlSchema.xsd
41+
- x-oas-draft-alternativeSchema:
42+
type: schematron
43+
location: ./schema.sch
44+
45+
Mixed OAS schema and alternative schema:
46+
47+
schema:
48+
type: array
49+
items:
50+
x-oas-draft-alternativeSchema:
51+
type: jsonSchema
52+
location: ./real-jsonschema.json
53+

‎proposals/Alternative Schema/alternative_schema_object.adoc

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Change: Add the Alternative Schema Object
2+
3+
The following text is to be inserted after the XML Object section
4+
5+
### Alternative Schema Object
6+
7+
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.
8+
9+
==== Fixed Fields
10+
11+
|Field Name | Type | Description |
12+
|---|:---:|---|
13+
|type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. |
14+
|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. |
15+
16+
This object MAY be extended with Specification Extensions.

‎proposals/Alternative Schema/implementations.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Implementations
2+
3+
## Overview
4+
5+
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.
6+
7+
These tools are not endorsed by the OAI
8+
9+
## Implementations:
10+
11+
#### Low-Level tooling
12+
13+
| Title | Project Link | Language | Description
14+
| ----------- | ----------- | ----------- | -----------
15+
|TBD |TBD |TBD |TBD |
16+
17+
#### Editors
18+
19+
| Title | Project Link | Language |Description |
20+
|----------------|--------------|----------|---------------------|
21+
|TBD |TBD |TBD |TBD |
22+
23+
#### User Interfaces
24+
25+
| Title | Project Link | Language |Description |
26+
|----------------|--------------|----------|---------------------|
27+
|TBD |TBD |TBD |TBD |
28+
29+
#### Mock Servers
30+
| Title | Project Link | Language | Description |
31+
| -------------- | ------------ | -------- | ----------- |
32+
|TBD |TBD |TBD |TBD |
33+
34+
#### Server Implementations
35+
| Title | Project Link | Language |Description |
36+
|----------------|--------------|----------|---------------------|
37+
|TBD |TBD |TBD |TBD |
38+
39+
#### Code Generators
40+
41+
| Title | Project Link | Language |Description |
42+
|----------------|--------------|----------|---------------------|
43+
|TBD |TBD |TBD |TBD |
44+
45+
46+

‎proposals/Alternative Schema/schema_object.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Change: Extend the Schema Object to support Alternative Schemas
2+
3+
The following content shall be used to replace the Fixed Fields table in the Schema Object section
4+
5+
#### Fixed Fields
6+
7+
|Field Name | Type | Description |
8+
|---|:---:|---|
9+
| nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.|
10+
| 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. |
11+
| 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`. |
12+
| 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`. |
13+
| 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. |
14+
| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema.
15+
| 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.|
16+
| deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.|
17+
|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. |

0 commit comments

Comments
 (0)