From 43316da33d51883da4c8d2744a0b1c4ce9feda45 Mon Sep 17 00:00:00 2001
From: Karen Etheridge <ether@cpan.org>
Date: Sat, 6 Sep 2025 20:37:59 -0700
Subject: [PATCH] notes on how each uri-reference should resolve

---
 src/schemas/validation/schema.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml
index 0717e2632f..9da49c478f 100644
--- a/src/schemas/validation/schema.yaml
+++ b/src/schemas/validation/schema.yaml
@@ -10,6 +10,7 @@ properties:
     pattern: '^3\.2\.\d+(-.+)?$'
   $self:
     type: string
+    $comment: resolved against the retrieval uri
     format: uri-reference
     $comment: MUST NOT contain a fragment
     pattern: '^[^#]*$'
@@ -17,9 +18,11 @@ properties:
     $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:
+    $comment: server urls are resolved against the HTTP request uri itself (template matching ideally happens first, because of url encoding, but matching the template parts separately may produce ambiguous results, so in my implementation I concatenate the server url template with the path template and then match that against the entire uri)
     type: array
     items:
       $ref: '#/$defs/server'
@@ -68,6 +71,7 @@ $defs:
       description:
         type: string
       termsOfService:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       contact:
@@ -89,6 +93,7 @@ $defs:
       name:
         type: string
       url:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       email:
@@ -106,6 +111,7 @@ $defs:
       identifier:
         type: string
       url:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
     required:
@@ -225,6 +231,7 @@ $defs:
     type: object
     properties:
       $ref:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       summary:
@@ -327,6 +334,7 @@ $defs:
       description:
         type: string
       url:
+        $comment: resolved against ???
         type: string
         format: uri-reference
     required:
@@ -682,6 +690,7 @@ $defs:
         type: string
       value: true
       externalValue:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
     allOf:
@@ -719,6 +728,7 @@ $defs:
     type: object
     properties:
       operationRef:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       operationId:
@@ -825,6 +835,7 @@ $defs:
     type: object
     properties:
       $ref:
+        $comment: resolved against the resolved version of $self
         type: string
         format: uri-reference
       summary:
@@ -929,6 +940,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 +956,7 @@ $defs:
         then:
           properties:
             openIdConnectUrl:
+              $comment: resolved against the matching and de-templated server url
               type: string
               format: uri-reference
           required:
@@ -977,6 +990,7 @@ $defs:
 
     $defs:
       implicit:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           authorizationUrl:
@@ -994,6 +1008,7 @@ $defs:
         unevaluatedProperties: false
 
       password:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           tokenUrl:
@@ -1011,6 +1026,7 @@ $defs:
         unevaluatedProperties: false
 
       client-credentials:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           tokenUrl:
@@ -1028,6 +1044,7 @@ $defs:
         unevaluatedProperties: false
 
       authorization-code:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           authorizationUrl:
@@ -1049,6 +1066,7 @@ $defs:
         unevaluatedProperties: false
 
       device-authorization:
+        $comment: references are resolved against the matching and de-templated server url
         type: object
         properties:
           deviceAuthorizationUrl: