Enhanced Operation Deprecation and versioning

Currently, OpenAPI allows us to identify the version of the API being described and deprecate operations using a Boolean value.

I would like to propose some additional metadata that makes it easier to track changes to APIs.
In addition to the existing deprecated flag, there is now a deprecatedVersion and replacementOperationId property.

Consider the following API and two of its operations:

{
 "openapi" : "3.0.0",
 "info" :  {
      "title" : "My API",
      "version" : "1.0.313"
  }
{
    "/foo" : {
        "get" : {
             "operationId" : "getFoo",
             "description" : "Return a foo",
             "deprecated" : true,
             "deprecatedVersion" : "1.0.312",
             "replacementOperationId" : "getFoo2"
             "responses" : {
                 "200" : {
                        "description" : "A foo representation"
                 }
             } 

        },
   "/foo2" : {
        "get" : {
             "operationId" : "getFoo2",
             "description" : "Return a foo",
             "responses" : {
                 "200" : {
                     "description" : "A completely different breaking foo representation"   
                 }
             } 
        }
    }
}
}

The deprecatedVersion property indicates the API version in which this operation was deprecated. The replacementOperationId provides a pointer to a new operation that replaces the functionality of the deprecated operation.

These new properties enable a variety of useful capabilities:

• Display documentation that is relevant to a particular API version. Operations that were deprecated prior to that version can be hidden by default to prevent accidently usage of operations that have been replaced.
• Help developers migrate to new operations by allowing documentation of deprecated operations to point to replacement operations.
• Generate client code that only supports operations available in a particular API version.
• Makes it possible to manage APIs to that are changing incrementally instead of doing big bang updates that completely replace a prior API.
• Help developers identify what has changed in a new API release.

No files, tests, or entry points are named. Start by reviewing the repository's existing OpenAPI operation schema and the 18-comment discussion to understand the intended metadata model and compatibility concerns. Done means the proposal has an agreed implementation scope for deprecatedVersion and replacementOperationId, with corresponding validation, documentation, and tests identified.