diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 8a768b3d1c..543bc78cba 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -80,9 +80,9 @@ Where suitable, features will be introduced as draft but OAI approved extensions By introducing new features this way we enable new features to be designed, documented and then implemented by tools that are interested in the feature, without putting the burden of implementation on all tooling. If the feature is successfully implemented and there is demonstrable value added by the feature, it will become a candidate for inclusion in a future release of the specification, at which point all tools will be expected to support the feature. -Draft feature extensions are identified by the `x-oas-draft-` prefix and can only be used where existing extensions are permitted. +Draft feature extensions are identified by the `x-oai-draft-` prefix and can only be used where existing extensions are permitted. This ensures no existing tooling will affected by the introduction of the draft feature. -If the feature is deemed appropriate for inclusion in the OAS, the `x-oas-draft-` prefix will be removed. +If the feature is deemed appropriate for inclusion in the OAS, the `x-oai-draft-` prefix will be removed. Tooling that supports draft features should plan for the future removal of the prefix. When tooling adds support for a later version of OAS that includes the final implementation of the feature, it MUST not support the use of the draft prefix for that feature. Draft features will only be promoted into minor or major releases of the specification and therefore will be transparent to OpenAPI description writers and tooling providers who choose not to use the feature while in its draft state. diff --git a/proposals/001_Alternative Schema Proposal.md b/proposals/001_Alternative Schema Proposal.md index 9f176ea28e..e5ee97ff79 100644 --- a/proposals/001_Alternative Schema Proposal.md +++ b/proposals/001_Alternative Schema Proposal.md @@ -16,8 +16,9 @@ |Date |Responsible Party |Description | |---- | ---------------- | ---------- | -|3/15/19 |C. Heazel|Initial Markup Draft | -|4/17/19 |C. Heazel|Re-structured based on Apple Swift| +|2019-03-15 |C. Heazel|Initial Markup Draft | +|2019-04-17 |C. Heazel|Re-structured based on Apple Swift| +|2020-06-04 |@MikeRalphson|Change `x-oas-` prefix to `x-oai-` | ## Introduction @@ -33,7 +34,7 @@ For example: Some XML payloads are defined by an XML schema (the syntax) and a s 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. Extend the Schema Object by the addition of the x-oai-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. @@ -42,7 +43,7 @@ This proposal makes the following changes to the OAS 3.0 specification: ### 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) +The OpenAPI Schema Object is extended by the addition of the x-oai-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 @@ -55,13 +56,14 @@ Examples of the use of the Alternative Schema capability is added to the OpenAPI 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. *** +** 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 | +|jsonSchema |TBD |JSON Schema | +|xsdSchema |TBD |XML Schema | ## Backwards compatibility @@ -69,5 +71,5 @@ This proposal makes use of the extensibility features of OpenAPI. All changes so ## 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. +Embedding non-JSON content in the OAS document would have imposed an unacceptable burden on tooling. Therefore, an external 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_examples.md b/proposals/Alternative Schema/alternative_schema_examples.md index 96f7189576..bbf17f4a04 100644 --- a/proposals/Alternative Schema/alternative_schema_examples.md +++ b/proposals/Alternative Schema/alternative_schema_examples.md @@ -7,7 +7,7 @@ The following text is to be inserted after the Alternative Schema Object section Minimalist usage of alternative schema: schema: - x-oas-draft-alternativeSchema: + x-oai-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json @@ -16,7 +16,7 @@ Combination of OAS schema and alternative: schema: type: object nullable: true - x-oas-draft-alternativeSchema: + x-oai-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json @@ -24,10 +24,10 @@ Multiple different versions of alternative schema: schema: anyOf: - - x-oas-draft-alternativeSchema: + - x-oai-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema-08.json - - x-oas-draft-alternativeSchema: + - x-oai-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema-07.json @@ -35,10 +35,10 @@ Combined alternative schemas: schema: allOf: - - x-oas-draft-alternativeSchema: + - x-oai-draft-alternativeSchema: type: xmlSchema location: ./xmlSchema.xsd - - x-oas-draft-alternativeSchema: + - x-oai-draft-alternativeSchema: type: schematron location: ./schema.sch @@ -47,7 +47,7 @@ Mixed OAS schema and alternative schema: schema: type: array items: - x-oas-draft-alternativeSchema: + x-oai-draft-alternativeSchema: type: jsonSchema location: ./real-jsonschema.json diff --git a/proposals/Alternative Schema/schema_object.md b/proposals/Alternative Schema/schema_object.md index df8c64c8ff..bb78ab1235 100644 --- a/proposals/Alternative Schema/schema_object.md +++ b/proposals/Alternative Schema/schema_object.md @@ -1,6 +1,6 @@ ## 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 +The following content shall be used to replace the Fixed Fields table in the Schema Object section. Note that this suggested change applies to v3.0.2 and **NOT** later versions. #### Fixed Fields @@ -14,4 +14,4 @@ The following content shall be used to replace the Fixed Fields table in the Sch | 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. | +|x-oai-draft-alternativeSchema |alternative Schema Object |An external schema that participates in the validation of content along with other schema keywords. |