oas-validator/README.md - servicecomb-toolkit - Git at Google

 # OAS Validator | [中文](./README-ZH.md)

 OpenAPI V3 Spec validation tools.

 ## Project structure

 * oas-validator-core: core apis and skeletons implementations
 * oas-validator-core-spring: Spring Boot Starter for core skeletons
 * oas-validator-test: test helpers for core api
 * oas-validator-compliance: check style validators
 * oas-validator-compliance-spring: Spring Boot Starter for check style validators
 * oas-validator-compatibility: compatibility validators
 * oas-validator-compatibility-spring: Spring Boot Starter for compatibility validators
 * oas-validator-web: web ui

 ## Style check rules

 OAS must compatible with [OAS 3.0.2][openapi-3.0.2], besides must obey the following rules.

 ### String patterns

 * <a name="lower-camel-case"></a> Lower Camel Case: initial letter lowercase camel case, regex is `^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$`
 * <a name="upper-camel-case"></a> Upper Camel Case: initial letter uppercase camel case, regex is `^[A-Z]([a-z0-9]+[A-Z]?)*$`
 * <a name="upper-hyphen-case"></a> Upper Hyphen Case: initial letter uppercase, multiple words concat with `-`, such as `Content-Type`, `Accept`, `X-Rate-Limit-Limit`, regex is `^([A-Z][a-z0-9]*-)*([A-Z][a-z0-9]*)$`

 ### OpenAPI Object [doc][spec-openapi]

 <a name="openapi-compliance"></a>

 * `openapi` property must be 3.0.x and >= 3.0.2
 * `info` propety, see [Info Object style check rules](#info-compliance)
 * `paths` property, must provide, see  [Paths Object style check rules](#paths-compliance)
 * `components` property, see [Components Object style check rules](#components-compliance)
 * `tags` property should at least provide one [Tag Object][spec-tag]
   * see  [Tag Object style check rules](#tag-compliance)
 * `security` property, should not provide

 ### Info Object [doc][spec-info]

 <a name="info-compliance"></a>

 * `description` property, required

 ### Tag Object [doc][spec-tag]

 <a name="tag-compliance"></a>

 - `name` property, must be [Upper Camel Case](#upper-camel-case)
 - `description` property, required
 - Every tag should be referenced by at least one [Operation Object][spec-operation]

 ### Paths Object [doc][spec-paths]

 <a name="paths-compliance"></a>

 * path must be [Lower Camel Case](#lower-camel-case), including [Path Templating][spec-path-templating] variable
   * see  [Path Item Object style check rules](#path-item-compliance)

 ### Path Item Object [doc][spec-path-item]

 <a name="path-item-compliance"></a>

 * `get/post/put/delete/...` properties, see  [Operation Object style check rules](operation-compliance)
 * `parameters` property, see  [Parameter Object style check rules](#parameter-compliance)

 ### Operation Object [doc][spec-operation]

 <a name="operation-compliance"></a>

 * `summary` property, required
 * `operationId` property, must be [Lower Camel Case](#lower-camel-case)
 * `parameters` property, see  [Parameter Object style check rules](#parameter-compliance)
 * `requestBody` property, see  [Request Body Object style check rules](#request-body-compliance)
 * `responses` property, see  [Responses Object style check rules](#responses-compliance)
 * `tags` property, can only provide one tag, must be in the range of [OpenAPI Object][spec-openapi]   `tags` property
 * `servers` property, should not provide

 ### Parameter Object [doc][spec-parameter]

 <a name="parameter-compliance"></a>

 * `description` property, required
 * `name` property
   * if `in` is path, query or cookie, then must be [Lower Camel Case](#lower-camel-case)
   * if `in` is header, then must be [Upper Hyphen Case](#upper-hyphen-case)
 * `schema` property, see  [Schema Object check sytle rules](#schema-compliance)
 * `content` property, see  [Media Type Object style check rules](#media-type-compliance)

 ### Request Body Object [doc][spec-request-body]

 <a name="request-body-compliance"></a>

 * `description` property, required
 * `content` property, see  [Media Type Object style check rules](#media-type-compliance)

 ### Media Type Object [doc][spec-media-type]

 <a name="media-type-compliance"></a>

 * `schema` property, required. See  [Schema Object style check rules](#schema-compliance)
 * `encoding` property, see  [Encoding Object style check rules](#encoding-compliance)

 ### Responses Object [doc][spec-responses]

 <a name="responses-compliance"></a>

 * See [Response Object style check rules](#response-compliance)

 ### Response Object [doc][spec-response]

 <a name="response-compliance"></a>

 * `description` property, required
 * `headers` property, name (`headers` key) must be [Upper Hyphen Case](#upper-hyphen-case)
   * See [Header Object style check rules](#header-compliance)
 * `content` property, see [Media Type Object style check rules](#media-type-compliance)

 ### Schema Object [doc][spec-schema]

 <a name="schema-compliance"></a>

 * `title` property, required if parent is [Schema Object][spec-schema] or [Components Object][spec-components]
 * `properties` property, name(`properties` key) must be [Lower Camel Case](#lower-camel-case)
   * Sub Schema, see [Schema Object style check rules](#schema-compliance)

 ### Encoding Object [doc][spec-encoding]

 <a name="encoding-compliance"></a>

 * `headers` property, name(`headers` key) must be [Upper Hyphen Case](#upper-hyphen-case)
   * See [Header Object style check rules](#header-compliance)

 ### Header Object [doc][spec-header]

 <a name="header-compliance"></a>

 * `description` property, required
 * `schema` property, see [Schema Object style check rules](#schema-compliance)
 * `content` property, see [Media Type Object style check rules](#media-type-compliance)

 ### Components Object [doc][spec-components]

 <a name="components-compliance"></a>

 * `schemas` property, name must be [Upper Camel Case](#upper-camel-case)
   * See [Schema Object style check rules](#schema-compliance)
 * `responses` property, name must be [Upper Camel Case](#upper-camel-case)
   * See [Response Object style check rules](#response-compliance)
 * `parameters` property, name must be [Upper Camel Case](#upper-camel-case)
   * See [Parameter Object style check rules](#parameter-compliance)
 * `examples` property, name must be [Upper Camel Case](#upper-camel-case)
 * `requestBodies` property, name must be [Upper Camel Case](#upper-camel-case)
   * See [Request Body style check rules](#request-body-compliance)
 * `headers` property, name must be [Upper Hyphen Case](#upper-hyphen-case)
   * See [Header style check rules](#header-compliance)
 * `links` property, name must be [Upper Camel Case](#upper-camel-case)
 * `callbacks` property, name must be [Upper Camel Case](#upper-camel-case)

 ## Compatibility check rules

 Check whether new OAS spec compatibile with old spec.

 Notice: OAS could use [Reference Object][spec-reference], two  OAS which are different in text maybe semantically same. For example, below old OAS doesn't use [Reference Object][spec-reference] while the new one uses:

 Old OAS

 ```yaml
 openapi: "3.0.0"
 info:
   version: 1.0.0
   title: Swagger Petstore
   license:
     name: MIT
 servers:
   - url: http://petstore.swagger.io/v1
 paths:
   /pets:
     post:
       summary: List all pets
       operationId: listPets
       requestBody:
         content:
           application/json:
             schema:
               type: array
               items:
                 type: object
                 properties:
                   Foo:
                     type: string
       responses:
         '200':
           description: A paged array of pets
 ```

 New OAS

 ```yaml
 paths:
   /pets:
     post:
       operationId: listPets
       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Foo'
       responses:
         '200':
           description: A paged array of pets
 components:
   schemas:
     Foo:
       type: array
       items:
         type: object
         properties:
           Foo:
             type: string
 ```

 So, when do compatibility check we resolve [Reference Object][spec-reference] in old and new OAS first, then do the check, below is the code snippet using [swagger-parser][swagger-parser]:

 ```java
 OpenAPIV3Parser parser = new OpenAPIV3Parser();

 ParseOptions parseOptions = new ParseOptions();
 parseOptions.setResolve(true);
 parseOptions.setResolveCombinators(true);
 parseOptions.setResolveFully(true);
 parseOptions.setFlatten(false);

 SwaggerParseResult parseResult = parser.readContents(content, null, parseOptions);
 ```

 So if  compatibility violations be found, the reported location will be different from the location in origin OAS spec.

 ### Paths Object [doc][spec-paths]

 <a name="paths-compatibility"></a>

 * New OAS must include all the `path` appears in 旧OAS. If `path` uses [Path Templating][spec-path-templating], even the variable name changed, will be considered semantically different. For example `/pets/{foo}` and `/pets/{bar}` are different.
   * See [Path Item Object compatibility check rules](#path-item-compatibility)

 ### Path Item Object [doc][spec-path-item]

 <a name="path-item-compatibility"></a>

 * New OAS must inclued all old OAS get/put/post/delete/...[Operation Object][spec-operation]

 ### Operation Object [doc][spec-operation]

 <a name="operation-compatibility"></a>

 * `operationId` property,  new and old must be identical
 * `parameters` property, check work must also consider [Path Item Object parameters property][spec-path-item-parameters]:
   * New OAS could add new [Parameter Object][spec-parameter], but the new [Parameter Object][spec-parameter] `required` property must be `false`
   * New OAS could delete[Parameter Object][spec-parameter]
   * The check on [Parameter Object][spec-parameter] see [Parameter Object compatibility check rules](#parameter-compatibility)(Under the same [Operation Object][spec-operation] [Parameter Object][spec-parameter] is identified by `name` and `in` property)。
 * `requestBody` property, see [Request Body Object compatibility check rules](#request-body-compatibility)
 * `responses` property, see[Responses Object compatibility check rules](#responses-compatibility)

 ### Parameter Object [doc][spec-parameter]

 <a name="parameter-compatibility"></a>

 * `required` property, only allow `true(old) -> false(new)` change
 * `allowEmptyValue` property, only allow `false(old) -> true(new)` change
 * `style` property, new and old must be identical
 * `explode` property, new and old must be identical
 * `allowReserved` property, only allow `false(old) -> true(new)` change
 * `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)
 * `content`property, new OAS must include all old OAS media type (`content` keys), and add new media type is not allowed
   * see [Media Type Object compatibility check rules](#media-type-compatibility)

 ### Request Body Object [doc][spec-request-body]

 <a name="request-body-compatibility"></a>

 * `content`property, new OAS must include all old OAS media type (`content` keys)
   * See [Media Type Object compatibility check rules](#media-type-compatibility)
 * `required` property, only allow `true(old) -> false(new)` change

 ### Media Type Object [doc][spec-media-type]

 <a name="media-type-compatibility"></a>

 * `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)
 * `encoding` property, this property only apply to `requestBody`, so new OAS and old OAS property name(`encoding` key) must be identical
   * See [Encoding Object compatibility check rules](#encoding-compatibility)

 ### Responses Object [doc][spec-responses]

 <a name="responses-compatibility"></a>

 * `default` property, if old OAS doesn't define `default`, then new OAS should not define `default` too.
 * `{Http Status Code}` property, new OAS is not allowed to add one.
 * See [Response Object compatibility check rules](#response-compatibility)

 ### Response Object [doc][spec-response]

 <a name="response-compatibility"></a>

 * `headers` property, new OAS must include all old OAS header name(`headers` keys), and add new header name is allowed
   * [Header Object][spec-header] see [Header Object compatibility check rules](#header-compatibility)
 * `content` property, new OAS must include all old OAS media type(`content` keys), and add new media type is allowed
   - [Media Type Object][spec-media-type] see [Media Type Object compatibility check rules](#media-type-compatibility)

 ### Schema Object [doc][spec-schema]

 <a name="schema-compatibility"></a>

 OAS allows Schema Object be directly or indirectly in:

 * Request: [Parameter Object][spec-parameter], [Request Body Object][spec-request-body], [Header Object][spec-header]
 * Response: [Header Object][spec-header], [Response Object][spec-response]

 In different context compatibility check rules are different.

 ### In request context

 When Schema Object is in response context, only allow change from more specific form to less specific form.

 * `type, format` combination allowed change:

 | Old (type,format)  | New (type,format)                                              |
 | ---------------- | ------------------------------------------------------------ |
 | integer, null    | integer, int64<br />number, double<br />number, null         |
 | integer, int32   | integer, int64<br />integer, null<br />number, float<br />number, double<br />number, null |
 | integer, int64   | integer, null<br />number, double<br />number, null          |
 | number, null     | number, double                                               |
 | number, float    | number, null<br />number, double                             |
 | number, double   | number, null                                                 |
 | string, null     | string, password                                             |
 | string, password | string, null                                                 |

 * `allOf`, `oneOf`, `anyOf` property, combine them first then do check
 * `multipleOf` property, if old OAS is null, then new OAS must == old OAS or new OAS is a factor of old OAS, eg, 6(old)->3(new)
 * `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be >= old OAS
 * `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be <= old OAS.
 * `exclusiveMaximum`, `exclusiveMinimum` property, only allow change `true(old)->false(new)`
 * `uniqueItems` property, only allow change `true(old)->false(new)`
 * `required` property, new OAS must == old OAS or new OAS is old OAS subset
 * `enum` property, new OAS must == old OAS or new OAS is old OAS superset
 * `properties` property, new OAS could add or delete property name(`properties` key)
 * `nullable` property, only allow change `false(old)->true(new)`
 * `discriminator` property, new and old must be identical
 * `xml` property, new and old must be identical
 * `readOnly`, `writeOnly` property, new and old must be identical

 ### In response context

 When Schema Object is in response context, only allow change from less specific form to more specific form.

 * `type, format` combination allowed change:

 | Old (type,format)  | New (type,format)                    |
 | ---------------- | ---------------------------------- |
 | integer, null    | integer, int64<br />integer, int32 |
 | integer, int64   | integer, null<br />interger, int32 |
 | number, null     | number, double<br />number, float  |
 | number, double   | number, null<br />number, float    |
 | string, null     | string, password                   |
 | string, password | string, null                       |

 * `allOf`, `oneOf`, `anyOf` property, combine them first then do check
 * `multipleOf` property if old OAS is null. new OAS must == old OAS or new OAS must be a multiple of old OAS, eg, 3(old)->6(new)
 * `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must <= old OAS
 * `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must >= old OAS
 * `exclusiveMaximum`, `exclusiveMinimum` property, only allow change  `false(old)->true(new)`
 * `uniqueItems` property, only allow change `false(old)->true(new)`
 * `required` new OAS must == old OAS or new OAS is old OAS superset
 * `enum` property, new OAS must == old OAS or new OAS is old OAS subset
 * `properties` property, new OAS could add or delete property name(`properties` key)
 * `nullable` property , only allow change `true(old)->false(new)`
 * `discriminator` property, new and old must be identical
 * `xml` property, new and old must be identical
 * `readOnly`, `writeOnly` property, new and old must be identical

 ### Encoding Object [doc][spec-encoding]

 <a name="encoding-compatibility"></a>

 Notice: Encoding Object only apply to Request Body Object

 * `contentType` property, new and old must be identical
 * `headers` property, new OAS can not add new he header name (`headers` key), but and delete header name
   * [Header Object][spec-header] see [Header Object compatibility check rules](#header-compatibility)
 * `style` property, new and old must be identical
 * `explode` property, new and old must be identical
 * `allowReserved` property, only allow change `false(old) -> true(new)`

 ### Header Object [doc][spec-header]

 <a name="header-compatibility"></a>

 - `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)

 ### Components Object [doc][spec-components]

 <a name="components-compatibility"></a>

 [Components Object][spec-components] defines reusable OAS Object, but when doing compatibility check all `$ref` are resolved, so no need to check [Components Object][spec-components] compatibility.


 [spec-operation]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
 [openapi-3.0.2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
 [spec-openapi]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
 [spec-server]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
 [spec-info]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
 [spec-paths]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#paths-object
 [spec-path-item]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject
 [spec-parameter]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
 [spec-request-body]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject
 [spec-security-scheme]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject
 [spec-components]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#components-object
 [spec-tag]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject
 [spec-schema]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject

 [spec-media-type]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#media-type-object
 [spec-response]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object
 [spec-path-templating]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-templating
 [spec-parameterIn]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterIn
 [spec-encoding]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#encodingObject
 [spec-header]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#header-object
 [spec-info]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
 [spec-reference]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#reference-object
 [swagger-parser]: https://github.com/swagger-api/swagger-parser
 [spec-path-item-parameters]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#user-content-pathitemparameters
 [spec-responses]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject
	# OAS Validator \| [中文](./README-ZH.md)

	OpenAPI V3 Spec validation tools.

	## Project structure

	* oas-validator-core: core apis and skeletons implementations
	* oas-validator-core-spring: Spring Boot Starter for core skeletons
	* oas-validator-test: test helpers for core api
	* oas-validator-compliance: check style validators
	* oas-validator-compliance-spring: Spring Boot Starter for check style validators
	* oas-validator-compatibility: compatibility validators
	* oas-validator-compatibility-spring: Spring Boot Starter for compatibility validators
	* oas-validator-web: web ui

	## Style check rules

	OAS must compatible with [OAS 3.0.2][openapi-3.0.2], besides must obey the following rules.

	### String patterns

	* <a name="lower-camel-case"></a> Lower Camel Case: initial letter lowercase camel case, regex is `^[a-z]+((\d)\|([A-Z0-9][a-z0-9]+))*([A-Z])?$`
	* <a name="upper-camel-case"></a> Upper Camel Case: initial letter uppercase camel case, regex is `^[A-Z]([a-z0-9]+[A-Z]?)*$`
	* <a name="upper-hyphen-case"></a> Upper Hyphen Case: initial letter uppercase, multiple words concat with `-`, such as `Content-Type`, `Accept`, `X-Rate-Limit-Limit`, regex is `^([A-Z][a-z0-9]-)([A-Z][a-z0-9]*)$`

	### OpenAPI Object [doc][spec-openapi]

	<a name="openapi-compliance"></a>

	* `openapi` property must be 3.0.x and >= 3.0.2
	* `info` propety, see [Info Object style check rules](#info-compliance)
	* `paths` property, must provide, see [Paths Object style check rules](#paths-compliance)
	* `components` property, see [Components Object style check rules](#components-compliance)
	* `tags` property should at least provide one [Tag Object][spec-tag]
	* see [Tag Object style check rules](#tag-compliance)
	* `security` property, should not provide

	### Info Object [doc][spec-info]

	<a name="info-compliance"></a>

	* `description` property, required

	### Tag Object [doc][spec-tag]

	<a name="tag-compliance"></a>

	- `name` property, must be [Upper Camel Case](#upper-camel-case)
	- `description` property, required
	- Every tag should be referenced by at least one [Operation Object][spec-operation]

	### Paths Object [doc][spec-paths]

	<a name="paths-compliance"></a>

	* path must be [Lower Camel Case](#lower-camel-case), including [Path Templating][spec-path-templating] variable
	* see [Path Item Object style check rules](#path-item-compliance)

	### Path Item Object [doc][spec-path-item]

	<a name="path-item-compliance"></a>

	* `get/post/put/delete/...` properties, see [Operation Object style check rules](operation-compliance)
	* `parameters` property, see [Parameter Object style check rules](#parameter-compliance)

	### Operation Object [doc][spec-operation]

	<a name="operation-compliance"></a>

	* `summary` property, required
	* `operationId` property, must be [Lower Camel Case](#lower-camel-case)
	* `parameters` property, see [Parameter Object style check rules](#parameter-compliance)
	* `requestBody` property, see [Request Body Object style check rules](#request-body-compliance)
	* `responses` property, see [Responses Object style check rules](#responses-compliance)
	* `tags` property, can only provide one tag, must be in the range of [OpenAPI Object][spec-openapi] `tags` property
	* `servers` property, should not provide

	### Parameter Object [doc][spec-parameter]

	<a name="parameter-compliance"></a>

	* `description` property, required
	* `name` property
	* if `in` is path, query or cookie, then must be [Lower Camel Case](#lower-camel-case)
	* if `in` is header, then must be [Upper Hyphen Case](#upper-hyphen-case)
	* `schema` property, see [Schema Object check sytle rules](#schema-compliance)
	* `content` property, see [Media Type Object style check rules](#media-type-compliance)

	### Request Body Object [doc][spec-request-body]

	<a name="request-body-compliance"></a>

	* `description` property, required
	* `content` property, see [Media Type Object style check rules](#media-type-compliance)

	### Media Type Object [doc][spec-media-type]

	<a name="media-type-compliance"></a>

	* `schema` property, required. See [Schema Object style check rules](#schema-compliance)
	* `encoding` property, see [Encoding Object style check rules](#encoding-compliance)

	### Responses Object [doc][spec-responses]

	<a name="responses-compliance"></a>

	* See [Response Object style check rules](#response-compliance)

	### Response Object [doc][spec-response]

	<a name="response-compliance"></a>

	* `description` property, required
	* `headers` property, name (`headers` key) must be [Upper Hyphen Case](#upper-hyphen-case)
	* See [Header Object style check rules](#header-compliance)
	* `content` property, see [Media Type Object style check rules](#media-type-compliance)

	### Schema Object [doc][spec-schema]

	<a name="schema-compliance"></a>

	* `title` property, required if parent is [Schema Object][spec-schema] or [Components Object][spec-components]
	* `properties` property, name(`properties` key) must be [Lower Camel Case](#lower-camel-case)
	* Sub Schema, see [Schema Object style check rules](#schema-compliance)

	### Encoding Object [doc][spec-encoding]

	<a name="encoding-compliance"></a>

	* `headers` property, name(`headers` key) must be [Upper Hyphen Case](#upper-hyphen-case)
	* See [Header Object style check rules](#header-compliance)

	### Header Object [doc][spec-header]

	<a name="header-compliance"></a>

	* `description` property, required
	* `schema` property, see [Schema Object style check rules](#schema-compliance)
	* `content` property, see [Media Type Object style check rules](#media-type-compliance)

	### Components Object [doc][spec-components]

	<a name="components-compliance"></a>

	* `schemas` property, name must be [Upper Camel Case](#upper-camel-case)
	* See [Schema Object style check rules](#schema-compliance)
	* `responses` property, name must be [Upper Camel Case](#upper-camel-case)
	* See [Response Object style check rules](#response-compliance)
	* `parameters` property, name must be [Upper Camel Case](#upper-camel-case)
	* See [Parameter Object style check rules](#parameter-compliance)
	* `examples` property, name must be [Upper Camel Case](#upper-camel-case)
	* `requestBodies` property, name must be [Upper Camel Case](#upper-camel-case)
	* See [Request Body style check rules](#request-body-compliance)
	* `headers` property, name must be [Upper Hyphen Case](#upper-hyphen-case)
	* See [Header style check rules](#header-compliance)
	* `links` property, name must be [Upper Camel Case](#upper-camel-case)
	* `callbacks` property, name must be [Upper Camel Case](#upper-camel-case)

	## Compatibility check rules

	Check whether new OAS spec compatibile with old spec.

	Notice: OAS could use [Reference Object][spec-reference], two OAS which are different in text maybe semantically same. For example, below old OAS doesn't use [Reference Object][spec-reference] while the new one uses:

	Old OAS

	```yaml
	openapi: "3.0.0"
	info:
	version: 1.0.0
	title: Swagger Petstore
	license:
	name: MIT
	servers:
	- url: http://petstore.swagger.io/v1
	paths:
	/pets:
	post:
	summary: List all pets
	operationId: listPets
	requestBody:
	content:
	application/json:
	schema:
	type: array
	items:
	type: object
	properties:
	Foo:
	type: string
	responses:
	'200':
	description: A paged array of pets
	```

	New OAS

	```yaml
	paths:
	/pets:
	post:
	operationId: listPets
	requestBody:
	content:
	application/json:
	schema:
	$ref: '#/components/schemas/Foo'
	responses:
	'200':
	description: A paged array of pets
	components:
	schemas:
	Foo:
	type: array
	items:
	type: object
	properties:
	Foo:
	type: string
	```

	So, when do compatibility check we resolve [Reference Object][spec-reference] in old and new OAS first, then do the check, below is the code snippet using [swagger-parser][swagger-parser]:

	```java
	OpenAPIV3Parser parser = new OpenAPIV3Parser();

	ParseOptions parseOptions = new ParseOptions();
	parseOptions.setResolve(true);
	parseOptions.setResolveCombinators(true);
	parseOptions.setResolveFully(true);
	parseOptions.setFlatten(false);

	SwaggerParseResult parseResult = parser.readContents(content, null, parseOptions);
	```

	So if compatibility violations be found, the reported location will be different from the location in origin OAS spec.

	### Paths Object [doc][spec-paths]

	<a name="paths-compatibility"></a>

	* New OAS must include all the `path` appears in 旧OAS. If `path` uses [Path Templating][spec-path-templating], even the variable name changed, will be considered semantically different. For example `/pets/{foo}` and `/pets/{bar}` are different.
	* See [Path Item Object compatibility check rules](#path-item-compatibility)

	### Path Item Object [doc][spec-path-item]

	<a name="path-item-compatibility"></a>

	* New OAS must inclued all old OAS get/put/post/delete/...[Operation Object][spec-operation]

	### Operation Object [doc][spec-operation]

	<a name="operation-compatibility"></a>

	* `operationId` property, new and old must be identical
	* `parameters` property, check work must also consider [Path Item Object parameters property][spec-path-item-parameters]:
	* New OAS could add new [Parameter Object][spec-parameter], but the new [Parameter Object][spec-parameter] `required` property must be `false`
	* New OAS could delete[Parameter Object][spec-parameter]
	* The check on [Parameter Object][spec-parameter] see [Parameter Object compatibility check rules](#parameter-compatibility)(Under the same [Operation Object][spec-operation] [Parameter Object][spec-parameter] is identified by `name` and `in` property)。
	* `requestBody` property, see [Request Body Object compatibility check rules](#request-body-compatibility)
	* `responses` property, see[Responses Object compatibility check rules](#responses-compatibility)

	### Parameter Object [doc][spec-parameter]

	<a name="parameter-compatibility"></a>

	* `required` property, only allow `true(old) -> false(new)` change
	* `allowEmptyValue` property, only allow `false(old) -> true(new)` change
	* `style` property, new and old must be identical
	* `explode` property, new and old must be identical
	* `allowReserved` property, only allow `false(old) -> true(new)` change
	* `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)
	* `content`property, new OAS must include all old OAS media type (`content` keys), and add new media type is not allowed
	* see [Media Type Object compatibility check rules](#media-type-compatibility)

	### Request Body Object [doc][spec-request-body]

	<a name="request-body-compatibility"></a>

	* `content`property, new OAS must include all old OAS media type (`content` keys)
	* See [Media Type Object compatibility check rules](#media-type-compatibility)
	* `required` property, only allow `true(old) -> false(new)` change

	### Media Type Object [doc][spec-media-type]

	<a name="media-type-compatibility"></a>

	* `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)
	* `encoding` property, this property only apply to `requestBody`, so new OAS and old OAS property name(`encoding` key) must be identical
	* See [Encoding Object compatibility check rules](#encoding-compatibility)

	### Responses Object [doc][spec-responses]

	<a name="responses-compatibility"></a>

	* `default` property, if old OAS doesn't define `default`, then new OAS should not define `default` too.
	* `{Http Status Code}` property, new OAS is not allowed to add one.
	* See [Response Object compatibility check rules](#response-compatibility)

	### Response Object [doc][spec-response]

	<a name="response-compatibility"></a>

	* `headers` property, new OAS must include all old OAS header name(`headers` keys), and add new header name is allowed
	* [Header Object][spec-header] see [Header Object compatibility check rules](#header-compatibility)
	* `content` property, new OAS must include all old OAS media type(`content` keys), and add new media type is allowed
	- [Media Type Object][spec-media-type] see [Media Type Object compatibility check rules](#media-type-compatibility)

	### Schema Object [doc][spec-schema]

	<a name="schema-compatibility"></a>

	OAS allows Schema Object be directly or indirectly in:

	* Request: [Parameter Object][spec-parameter], [Request Body Object][spec-request-body], [Header Object][spec-header]
	* Response: [Header Object][spec-header], [Response Object][spec-response]

	In different context compatibility check rules are different.

	### In request context

	When Schema Object is in response context, only allow change from more specific form to less specific form.

	* `type, format` combination allowed change:

	\| Old (type,format) \| New (type,format) \|
	\| ---------------- \| ------------------------------------------------------------ \|
	\| integer, null \| integer, int64<br />number, double<br />number, null \|
	\| integer, int32 \| integer, int64<br />integer, null<br />number, float<br />number, double<br />number, null \|
	\| integer, int64 \| integer, null<br />number, double<br />number, null \|
	\| number, null \| number, double \|
	\| number, float \| number, null<br />number, double \|
	\| number, double \| number, null \|
	\| string, null \| string, password \|
	\| string, password \| string, null \|

	* `allOf`, `oneOf`, `anyOf` property, combine them first then do check
	* `multipleOf` property, if old OAS is null, then new OAS must == old OAS or new OAS is a factor of old OAS, eg, 6(old)->3(new)
	* `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be >= old OAS
	* `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must be <= old OAS.
	* `exclusiveMaximum`, `exclusiveMinimum` property, only allow change `true(old)->false(new)`
	* `uniqueItems` property, only allow change `true(old)->false(new)`
	* `required` property, new OAS must == old OAS or new OAS is old OAS subset
	* `enum` property, new OAS must == old OAS or new OAS is old OAS superset
	* `properties` property, new OAS could add or delete property name(`properties` key)
	* `nullable` property, only allow change `false(old)->true(new)`
	* `discriminator` property, new and old must be identical
	* `xml` property, new and old must be identical
	* `readOnly`, `writeOnly` property, new and old must be identical

	### In response context

	When Schema Object is in response context, only allow change from less specific form to more specific form.

	* `type, format` combination allowed change:

	\| Old (type,format) \| New (type,format) \|
	\| ---------------- \| ---------------------------------- \|
	\| integer, null \| integer, int64<br />integer, int32 \|
	\| integer, int64 \| integer, null<br />interger, int32 \|
	\| number, null \| number, double<br />number, float \|
	\| number, double \| number, null<br />number, float \|
	\| string, null \| string, password \|
	\| string, password \| string, null \|

	* `allOf`, `oneOf`, `anyOf` property, combine them first then do check
	* `multipleOf` property if old OAS is null. new OAS must == old OAS or new OAS must be a multiple of old OAS, eg, 3(old)->6(new)
	* `maximum`, `maxLength`, `maxItems`, `maxProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must <= old OAS
	* `minimum`, `minLenght`, `minItems`, `minProperties`, if old OAS is null, then new OAS must be null too. Otherwise, new OAS must >= old OAS
	* `exclusiveMaximum`, `exclusiveMinimum` property, only allow change `false(old)->true(new)`
	* `uniqueItems` property, only allow change `false(old)->true(new)`
	* `required` new OAS must == old OAS or new OAS is old OAS superset
	* `enum` property, new OAS must == old OAS or new OAS is old OAS subset
	* `properties` property, new OAS could add or delete property name(`properties` key)
	* `nullable` property , only allow change `true(old)->false(new)`
	* `discriminator` property, new and old must be identical
	* `xml` property, new and old must be identical
	* `readOnly`, `writeOnly` property, new and old must be identical

	### Encoding Object [doc][spec-encoding]

	<a name="encoding-compatibility"></a>

	Notice: Encoding Object only apply to Request Body Object

	* `contentType` property, new and old must be identical
	* `headers` property, new OAS can not add new he header name (`headers` key), but and delete header name
	* [Header Object][spec-header] see [Header Object compatibility check rules](#header-compatibility)
	* `style` property, new and old must be identical
	* `explode` property, new and old must be identical
	* `allowReserved` property, only allow change `false(old) -> true(new)`

	### Header Object [doc][spec-header]

	<a name="header-compatibility"></a>

	- `schema` property, see [Schema Object compatibility check rules](#schema-compatibility)

	### Components Object [doc][spec-components]

	<a name="components-compatibility"></a>

	[Components Object][spec-components] defines reusable OAS Object, but when doing compatibility check all `$ref` are resolved, so no need to check [Components Object][spec-components] compatibility.


	[spec-operation]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
	[openapi-3.0.2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
	[spec-openapi]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
	[spec-server]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
	[spec-info]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
	[spec-paths]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#paths-object
	[spec-path-item]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject
	[spec-parameter]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
	[spec-request-body]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#requestBodyObject
	[spec-security-scheme]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject
	[spec-components]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#components-object
	[spec-tag]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#tagObject
	[spec-schema]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject

	[spec-media-type]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#media-type-object
	[spec-response]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object
	[spec-path-templating]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-templating
	[spec-parameterIn]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterIn
	[spec-encoding]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#encodingObject
	[spec-header]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#header-object
	[spec-info]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
	[spec-reference]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#reference-object
	[swagger-parser]: https://github.com/swagger-api/swagger-parser
	[spec-path-item-parameters]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#user-content-pathitemparameters
	[spec-responses]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responsesObject