Correct comment on the link object

DEVELOPMENT.md

@@ -1,6 +1,6 @@
 ## Development Guidelines
 
-This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Contributor Board will initially follow these processes when merging changes from external contributors or from the TCB itself. This guideline document will be adjusted as practicality dictates.
+This document intends to establish guidelines which build a transparent, open mechanism for deciding how to evolve the OpenAPI Specification. The Open API Technical Developer Community will initially follow these processes when merging changes from external contributors or from the TDC itself. This guideline document will be adjusted as practicality dictates.
 
 ## OAI Specification Driving factors
 
@@ -21,14 +21,19 @@ The specification _will change_ from the original 2.0 version.  We should typica
 
  - Use GitHub for all spec designs, use cases, and so on.
  - As with 2.0, the **human readable** document is the source of truth.  If using a JSON Schema again to document the spec, it is secondary to the human documentation.  The documentation should live in a *.md file, in parallel to the 2.0 document (versions/3.0.0.md for example).
- - The `master` branch shall remain the current, released OpenAPI Specification (i.e., 2.0).  We will work in an OpenAPI.next branch, which shall be described and linked to on the **default** README.md on master.
+ - At any given time, there would be _at most_ 4 work branches. The branches would exist if work has started on them. Assuming a current version of 3.0.0:
+   - `master` - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted.
+   - `v3.0.1` - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications.
+   - `v3.1.0` - The next MINOR version.
+   - `v4.0.0` - The next MAJOR version.
+ - The `master` branch shall remain the current, released OpenAPI Specification.  We will describe and link the work branch(es) on the **default** README.md on master.
  - Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal.
- - New features should be done in feature branches which, upon approval, are merged into the OpenAPI.next branch.
+ - New features should be done in feature branches/forks which, upon approval, are merged into the proper work branch.
  - Use labels for the workflow of specification changes.  Examples of labels are `proposed`, `needs migration review`, `needs tooling review`, `needs documentation`, `rejected`, and `needs approval`.  These labels must be assigned by project committers.
  - An issue will be opened for each feature change.  Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change.
  - A PR will be used to describe the _proposed_ solution, and linked to the original issue.
  - Not all committers will contribute to every single proposed change.  There may be many open proposals at once, and multiple efforts may happen in parallel.
- - When the OpenApi.next spec is complete and approved for release, the branch will be merged to master.
+ - When the a work branch is ready and approved, the branch will be merged to master.
 
 ## Approving Changes
 

GOVERNANCE.MD

@@ -0,0 +1,31 @@
+# Governance
+
+The OpenAPI Specification is a project of the Open API Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance).
+
+# Processes and procedures of the Technical Steering Committee (TSC)
+
+The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines.
+
+## 1. The establishment of roles and the responsibilities for each role
+
+Roles:
+
+* [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the BGB at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC.
+
+* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible from approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. 
+
+* [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members.
+
+## 2. Adding members to the TSC
+
+At an open TDC meeting, the impending call-for-nominations period is communicated and subsequently tweeted, no more than once per quarter. Nominations for members happen at closed TSC meetings via a motion by a voting TSC member. A nominee must not receive negative votes from 25% or more of the TSC voting membership. in a confidential vote held electronically within a week of the nomination. Approved nominees are expected to comport themselves during the provisional period of four weeks as full members of the TSC, though nominees do not have voting rights until their membership is confirmed. TSC subsequently votes on those nominees in the subsequent TSC meeting. At most there are four voting periods per year, with a minimum of 1 per year.
+
+## 3. Removal of membership from the TSC
+
+In dire situations, it may be necessary to remove a TSC member, such as behavior that violates the code of conduct (whether non-participation merits removal is a decision left to the TSC voting members). 75% vote (confidential, electronic) of the other TSC. members is required to remove a member. Otherwise, TSC members are removed when they renounce their position.
+
+## 4. Criteria for decisions
+
+The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the TOB.
+
+The TSC will maintain a publicly available document specifying the process in the contributor guidelines for how proposed changes are merged into the specification. The TSC will document and publicize the schedule of merge parties and release parties for the benefit of the technical developer community.

IMPLEMENTATIONS.md

@@ -1,10 +1,6 @@
 ### Implementations
 
-Below is a list of known tooling that implements the 3.0.0 specification. Because
-the 3.0.0 specification has not yet been released, refer to the details of projects listed below for any notes about stability and roadmap.  The process 
-to create the best possible 3.0.0 specification includes feedback from end-users
-and tooling creators. We strongly encourage draft tooling be
-made available for early users of the OAS.
+Below is a list of known tooling that implements the 3.0.0 specification. While support for the 3.0.0 specification matures,  refer to the details of projects listed below for any notes about stability and roadmap.  The process to improve the 3.x 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 necessarily endorsed by the OAI.
 
@@ -18,6 +14,7 @@ These tools are not necessarily endorsed by the OAI.
 | openapi3-ts | [GitHub/metadevpro/openapi3-ts](https://github.com/metadevpro/openapi3-ts) | TypeScript | TS Model & utils for OpenAPI 3.0.x contracts |
 | swagger2openapi | [GitHub/mermade/swagger2openapi](https://github.com/mermade/swagger2openapi) | Node.js | An OpenAPI / Swagger 2.0 to OpenAPI 3.0.x converter and validator |
 | Tavis.OpenApi | [GitHub/tavis-sofware/Tavis.OpenApi](https://github.com/tavis-software/Tavis.OpenApi/) | dotnet | C# based parser with definition validation and migration support from V2 |
+| odata-openapi | [GitHub/oasis-tcs/odata-openapi](https://github.com/oasis-tcs/odata-openapi) | XSLT | OData 4.0 to OpenAPI 3.0.0 converter |
 
 
 #### Editors
@@ -35,6 +32,7 @@ These tools are not necessarily endorsed by the OAI.
 |----------------|--------------|----------|---------------------|
 | openapi-viewer | [GitHub/koumoul/openapi-viewer](https://github.com/koumoul-dev/openapi-viewer) | Vue.js | Browse and test a REST API described with the OpenAPI 3.0 Specification. |
 | swagger-ui | [GitHub/swagger-api](https://github.com/swagger-api/swagger-UI) | JavaScript | Web-Based interface for visualizing and testing OpenAPI\Swagger definitions |
+| lincoln | [GitHub/temando/open-api-renderer](https://github.com/temando/open-api-renderer)| React.js| A React renderer for Open API v3 |
 
 
 #### Server Implementations
@@ -46,3 +44,4 @@ These tools are not necessarily endorsed by the OAI.
 |----------------|--------------|----------|---------------------|
 | baucis-openapi3 | [Github/metadevpro/baucis-openapi3](https://github.com/metadevpro/baucis-openapi3) | Node.js | [Baucis.js](https://github.com/wprl/baucis) plugin for generating OpenAPI 3.0 compliant API contracts. |
 | Google Gnostic | [GitHub/googleapis/gnostic](https://github.com/googleapis/gnostic) | Go | Compile OpenAPI descriptions into equivalent Protocol Buffer representations. |
+| serverless-openapi-documentation | [GitHub/temando/serverless-openapi-documentation](https://github.com/temando/serverless-openapi-documentation) | Typescript | Serverless 1.0 plugin to generate OpenAPI V3 documentation from serverless configuration |

README.md

@@ -19,6 +19,10 @@ Here you will find the information you need about the OpenAPI Specification, sim
 
 The current version of the OpenAPI specification is [OpenAPI Specification 3.0](versions/3.0.0.md).
 
+### Future Versions
+
+[3.0.1](https://github.com/OAI/OpenAPI-Specification/tree/v3.0.1) - The next PATCH version. Patch-level fixes (typos, clarifications, etc.) should be submitted against this branch.
+
 ### Previous Versions
 
 This repository also contains the [OpenAPI Specification 2.0](versions/2.0.md), which is identical to the Swagger 2.0 specification before it was renamed to “OpenAPI Specification”, 

examples/v3.0/api-with-examples.yaml

@@ -8,7 +8,7 @@ paths:
       operationId: listVersionsv2
       summary: List API versions
       responses:
-        200:
+        '200':
           description: |-
             200 response
           content:
@@ -41,7 +41,7 @@ paths:
                         }
                     ]
                  }
-        300:
+        '300':
           description: |-
             300 response
           content:
@@ -80,7 +80,7 @@ paths:
       operationId: getVersionDetailsv2
       summary: Show API version details
       responses:
-        200:
+        '200':
           description: |-
             200 response
           content:
@@ -125,7 +125,7 @@ paths:
                       ]
                     }
                   }
-        203:
+        '203':
           description: |-
             203 response
           content:

examples/v3.0/petstore-expanded.yaml

@@ -2,7 +2,7 @@ openapi: "3.0.0"
 info:
   version: 1.0.0
   title: Swagger Petstore
-  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
+  description: A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification
   termsOfService: http://swagger.io/terms/
   contact:
     name: Swagger API Team
@@ -40,7 +40,7 @@ paths:
             type: integer
             format: int32
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -65,7 +65,7 @@ paths:
             schema:
               $ref: '#/components/schemas/NewPet'
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -90,7 +90,7 @@ paths:
             type: integer
             format: int64
       responses:
-        200:
+        '200':
           description: pet response
           content:
             application/json:
@@ -114,7 +114,7 @@ paths:
             type: integer
             format: int64
       responses:
-        204:
+        '204':
           description: pet deleted
         default:
           description: unexpected error

examples/v3.0/petstore.yaml

@@ -22,7 +22,7 @@ paths:
             type: integer
             format: int32
       responses:
-        200:
+        '200':
           description: An paged array of pets
           headers:
             x-next:
@@ -45,7 +45,7 @@ paths:
       tags:
         - pets
       responses:
-        201:
+        '201':
           description: Null response
         default:
           description: unexpected error
@@ -67,7 +67,7 @@ paths:
           schema:
             type: string
       responses:
-        200:
+        '200':
           description: Expected response to a valid request
           content:
             application/json:

examples/v3.0/uber.yaml

@@ -32,7 +32,7 @@ paths:
       tags: 
         - Products
       responses:  
-        200:
+        '200':
           description: An array of products
           content:
             application/json:
@@ -80,7 +80,7 @@ paths:
       tags: 
         - Estimates
       responses:  
-        200:
+        '200':
           description: An array of price estimates by product
           content:
             application/json:
@@ -127,7 +127,7 @@ paths:
       tags: 
         - Estimates
       responses:  
-        200:
+        '200':
           description: An array of products
           content:
             application/json:
@@ -148,7 +148,7 @@ paths:
       tags: 
         - User
       responses:
-        200:
+        '200':
           description: Profile information for a user
           content:
             application/json:
@@ -180,7 +180,7 @@ paths:
       tags: 
         - User
       responses:
-        200:
+        '200':
           description: History information for the given user
           content:
             application/json:

schemas/v2.0/schema.json

@@ -203,7 +203,7 @@
       "additionalProperties": {
         "$ref": "#/definitions/response"
       },
-      "description": "One or more JSON representations for parameters"
+      "description": "One or more JSON representations for responses"
     },
     "externalDocs": {
       "type": "object",

versions/3.0.0.md

@@ -2051,7 +2051,7 @@ links:
   address:
     operationId: getUserAddressByUUID
     parameters:
-      # get the `id` field from the request path parameter named `id`
+      # get the `uuid` field from the `uuid` field in the response body
       userUuid: $response.body#/uuid
 ```