From 0a285ce18510c1fdd688cbed825cf3fc1f707f7e Mon Sep 17 00:00:00 2001
From: Mike Kistler <mikekistler@microsoft.com>
Date: Mon, 8 May 2023 07:28:55 -0700
Subject: [PATCH] Add link support from urls

---
 versions/3.2.0.md | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/versions/3.2.0.md b/versions/3.2.0.md
index 01503ef160..24e1d6d25a 100644
--- a/versions/3.2.0.md
+++ b/versions/3.2.0.md
@@ -2031,6 +2031,10 @@ Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OA
 
 For computing links, and providing instructions to execute them, a [runtime expression](#runtimeExpression) is used for accessing values in an operation and using them as parameters while invoking the linked operation.  
 
+Clients follow all links at their discretion.
+Neither permissions, nor the capability to make a successful call to that link, is guaranteed
+solely by the existence of a relationship.
+
 ##### Fixed Fields
 
 Field Name  |  Type  | Description
@@ -2039,6 +2043,7 @@ Field Name  |  Type  | Description
 <a name="linkOperationId"></a>operationId  | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive of the `operationRef` field.  
 <a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the [parameter location](#parameterIn) `[{in}.]{name}` for operations that use the same parameter name in different locations (e.g. path.id).
 <a name="linkRequestBody"></a>requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation.
+<a name="linkUrl"></a>url | Any \| {expression} | A constant or an expression to be evaluated and passed to the linked operation. The value should be a URL for the linked operation. Applications may extract values for path or query parameters present in this URL to use as values for these parameters in the linked operation.
 <a name="linkDescription"></a>description  | `string` | A description of the link. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="linkServer"></a>server       | [Server Object](#serverObject) | A server object to be used by the target operation.
 
@@ -2112,11 +2117,6 @@ links:
       userUuid: $response.body#/uuid
 ```
 
-Clients follow all links at their discretion. 
-Neither permissions, nor the capability to make a successful call to that link, is guaranteed 
-solely by the existence of a relationship.
-
-
 ##### OperationRef Examples
 
 As references to `operationId` MAY NOT be possible (the `operationId` is an optional 
@@ -2145,6 +2145,19 @@ links:
 Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when 
 using JSON references.
 
+##### URL Examples
+
+The `url` field can be used to specify a literal value or an expression containing a relative or absolute
+URL to use for the target operation. A common example of this scenario is the "Location" header returned in a 201 response from POST.
+
+```yaml
+links:
+  ResourceLocation:
+    operationId: getUser
+    url: $response.header.location
+```
+
+Clients may use the evaluated value directly or as the source of path or query parameter values for the linked operation.
 
 ##### <a name="runtimeExpression"></a>Runtime Expressions