notes on how each uri-reference should resolve

Author: karenetheridge

src/schemas/validation/schema.yaml

@@ -10,13 +10,15 @@ properties:
     pattern: '^3\.2\.\d+(-.+)?$'
   $self:
     type: string
+    $comment: resolved against the retrieval uri
     format: uri-reference
     $comment: MUST NOT contain a fragment
     pattern: '^[^#]*$'
   info:
     $ref: '#/$defs/info'
   jsonSchemaDialect:
     type: string
+    $comment: resolved against the resolved version of $self
     format: uri-reference
     default: 'https://spec.openapis.org/oas/3.2/dialect/WORK-IN-PROGRESS'
   servers:
@@ -68,6 +70,7 @@ $defs:
       description:
         type: string
       termsOfService:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       contact:
@@ -89,6 +92,7 @@ $defs:
       name:
         type: string
       url:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       email:
@@ -106,6 +110,7 @@ $defs:
       identifier:
         type: string
       url:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
     required:
@@ -225,6 +230,7 @@ $defs:
     type: object
     properties:
       $ref:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       summary:
@@ -327,6 +333,7 @@ $defs:
       description:
         type: string
       url:
+        $comment: resolved against ???
         type: string
         format: uri-reference
     required:
@@ -682,6 +689,7 @@ $defs:
         type: string
       value: true
       externalValue:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
     allOf:
@@ -719,6 +727,7 @@ $defs:
     type: object
     properties:
       operationRef:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       operationId:
@@ -825,6 +834,7 @@ $defs:
     type: object
     properties:
       $ref:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       summary:
@@ -929,6 +939,7 @@ $defs:
             flows:
               $ref: '#/$defs/oauth-flows'
             oauth2MetadataUrl:
+              $comment: resolved against the matching and de-templated server url
               type: string
               format: uri-reference
           required:
@@ -944,6 +955,7 @@ $defs:
         then:
           properties:
             openIdConnectUrl:
+              $comment: resolved against the matching and de-templated server url
               type: string
               format: uri-reference
           required:
@@ -977,6 +989,7 @@ $defs:
 
     $defs:
       implicit:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           authorizationUrl:
@@ -994,6 +1007,7 @@ $defs:
         unevaluatedProperties: false
 
       password:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           tokenUrl:
@@ -1011,6 +1025,7 @@ $defs:
         unevaluatedProperties: false
 
       client-credentials:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           tokenUrl:
@@ -1028,6 +1043,7 @@ $defs:
         unevaluatedProperties: false
 
       authorization-code:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           authorizationUrl:
@@ -1049,6 +1065,7 @@ $defs:
         unevaluatedProperties: false
 
       device-authorization:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           deviceAuthorizationUrl: