Skip to content
Permalink
Browse files

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
  • Loading branch information...
cmheazel authored and darrelmiller committed Apr 25, 2019
1 parent 1bb2c28 commit 4375616d8670f4938c678a3390a4a35bb4ad0d8b
@@ -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.

@@ -0,0 +1,73 @@
# Alternative Schema

## Metadata

|Tag |Value |
|---- | ---------------- |
|Proposal |[Alternative Schema](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema)|
|Authors|[Chuck Heazel](https://github.com/{cmheazel})|
|Review Manager |TBD |
|Status |**Draft** |
|Implementations |[Click Here](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/implementations.md)
|Issues |[1532](https://github.com/OAI/OpenAPI-Specification/issues/1532)|
|Previous Revisions |[March 15](https://github.com/OAI/OpenAPI-Specification/pull/1868#issue-261689900) |

.Change Log

|Date |Responsible Party |Description |
|---- | ---------------- | ---------- |
|3/15/19 |C. Heazel|Initial Markup Draft |
|4/17/19 |C. Heazel|Re-structured based on Apple Swift|

## Introduction

This a proposal to add a new field called ``alternativeSchema`` to the OAS.

## Motivation

OpenAPI allows APIs to describe the syntax of their request and response messaged using a JSON Schema-like syntax. However, not all messages will be in JSON. The ability to refer to one or more external schema will allow an API to describe the syntax of a message regardless of the format used.

For example: Some XML payloads are defined by an XML schema (the syntax) and a suite of Schematron rules (valid values). JSON Schema cannot effectively represent their content. By providing access to the appropriate appropriate XML Schema and Schematron files, the payload can be validated the way it was intended to be.

## Proposed solution

This proposal makes the following changes to the OAS 3.0 specification:

1. Extend the Schema Object by the addition of the x-oas-draft-alternativeSchema field.
1. Addition of the Alternative Schema Object.
1. Addition of Alternative Schema examples.
1. Addition of a preliminary discussion of the Alternative Schema registry.

## Detailed design

### Extend the Schema Object

The OpenAPI Schema Object is extended by the addition of the x-oas-draft-alternativeSchema field. The proposed changes to the OpenAPI specification are provided in [schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/schema_object.md)

### Add the Alternative Schema Object

The new object, the Alternative Schema Object is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_object.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_object.md)

### Provide Alternative Schema Examples
Examples of the use of the Alternative Schema capability is added to the OpenAPI specification. The proposed changes to the OpenAPI specification are provided in [alternative_schema_examples.md](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/Alternative%20Schema/alternative_schema_examples.md)

### Alternative Schema Registry

Values used to populate the Alternative Schema Object are required to come from the Alternative Schema Registry. The preliminary Alternative Schema Registry is located at https://spec.openapis.org/registries/alternative-schema[https://spec.openapis.org/registries/alternative-schema].

*** Note this is a placeholder registry. Don't take the values seriously. ***

Inital contents of the registry will include:

|Name |Link |Description |
|--- | --- | --- |
|jsonSchema |TBD |JSON Schema | |xsdSchema |TBD |XML Schema |

## Backwards compatibility

This proposal makes use of the extensibility features of OpenAPI. All changes sould appear as extensions and handled accordingly.

## Alternatives considered

Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an extenal link was prefered. Considerable discussion was held over exactly how the links should be represented in the Schema Object. The selected option should support the greatest number of possible combinations of external schema that can be expressed with the OpenAPI schema language.

@@ -0,0 +1,2 @@
* Chuck Heazel [@cmheazel](https://github.com/cmheazel)
* Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
@@ -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

@@ -0,0 +1,53 @@
## Change: Add Alternative Schema Examples

The following text is to be inserted after the Alternative Schema Object section.

### Alternative Schema Examples

Minimalist usage of alternative schema:

schema:
x-oas-draft-alternativeSchema:
type: jsonSchema
location: ./real-jsonschema.json

Combination of OAS schema and alternative:

schema:
type: object
nullable: true
x-oas-draft-alternativeSchema:
type: jsonSchema
location: ./real-jsonschema.json

Multiple different versions of alternative schema:

schema:
anyOf:
- x-oas-draft-alternativeSchema:
type: jsonSchema
location: ./real-jsonschema-08.json
- x-oas-draft-alternativeSchema:
type: jsonSchema
location: ./real-jsonschema-07.json

Combined alternative schemas:

schema:
allOf:
- x-oas-draft-alternativeSchema:
type: xmlSchema
location: ./xmlSchema.xsd
- x-oas-draft-alternativeSchema:
type: schematron
location: ./schema.sch

Mixed OAS schema and alternative schema:

schema:
type: array
items:
x-oas-draft-alternativeSchema:
type: jsonSchema
location: ./real-jsonschema.json

@@ -0,0 +1,16 @@
## Change: Add the Alternative Schema Object

The following text is to be inserted after the XML Object section

### Alternative Schema Object

This object makes it possible to reference an external file that contains a schema that does not follow the OAS specification. If tooling does not support the _type_, tooling MUST consider the content valid but SHOULD provide a warning that the alternative schema was not processed.

==== Fixed Fields

|Field Name | Type | Description |
|---|:---:|---|
|type | string | **REQUIRED**. The value MUST match one of the values identified in the alternative Schema Registry. |
|location | url | **REQUIRED**. This is a absolute or relative reference to an external resource containing a schema of a known type. This reference may contain a fragment identifier to reference only a subset of an external document. |

This object MAY be extended with Specification Extensions.
@@ -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 |



@@ -0,0 +1,17 @@
## Change: Extend the Schema Object to support Alternative Schemas

The following content shall be used to replace the Fixed Fields table in the Schema Object section

#### Fixed Fields

|Field Name | Type | Description |
|---|:---:|---|
| nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.|
| discriminator | [Discriminator Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaComposition) for more details. |
| readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. |
| writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`. |
| xml | [XML Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. |
| externalDocs | [External Documentation Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#externalDocumentationObject) | Additional external documentation for this schema.
| example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.|
| deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.|
|x-oas-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. |

0 comments on commit 4375616

Please sign in to comment.
You can’t perform that action at this time.