From dc3380f33e0f8ded94f0b2a7b9fe063c6dc8ffeb Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Mon, 17 Feb 2025 10:41:49 -0500
Subject: [PATCH 01/16] Documented how OpenAPI references are used

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 139 ++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 OpenAPI/OpenAPI.NET/references-openapi.md

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
new file mode 100644
index 0000000..7ff67d4
--- /dev/null
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -0,0 +1,139 @@
+---
+title: References in OpenAPI documents
+description: Learn the types of references that are supportined in the OpenAPI.NET library.
+author: darrmi
+ms.author: darrmi
+ms.topic: conceptual
+---
+
+# References in OpenAPI documents
+
+OpenAPI uses the keyword `$ref` to enable referencing and reusing existing objects defined in an OpenAPI description. However, there are many different ways to use this keyword and not all are supported by the OpenAPI.NET library.  Also, OpenAPI 3.1 formalized the distinction between the use of the `$ref` keyword in a Schema object vs elsewhere in an OpenAPI description. To best understand how to use `$ref` it is helpful to be aware of its capabilities and the current limitations of OpenAPI.Net.
+
+## Reference Objects
+
+Prior to OpenAPI v3.1, Reference Objects was the term for all usages of `$ref` within OpenAPI descriptions. However, when OpenAPI v3.1 introduced support for JSON Schema beyond the draft-4 version, it became necessary to allow the use of `$ref` within Schema Objects to follow the rules of JSON Schema and all other uses in OpenAPI descriptions would be considered Reference Objects. Therefore, this section only describes the rules for `$ref` keywords that are not in a Schema Object.
+
+### Where Reference Objects can be used
+
+Reference objects can appear in one of two places.  Either in place of an inline object, or a map value in the components section.
+
+This example below shows a common usage pattern of referencing a shared parameter object using a reference object.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object pointing to a parameter
+paths:
+  /item:
+    get:
+      parameters:
+        $ref: '#/components/parameters/size'
+components:
+  parameters:
+    size:
+     type: number
+```
+
+The following example shows a way to externalize security schemes using a reference object in a component.  This is necessary because security requirement objects do not allow referencing using an external URI.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object in a component object
+paths:
+  /item:
+    get:
+        security:
+            - customapikey: []
+components:
+  securitySchemes:
+    customapikey:
+        $ref: ./commonSecuritySchemes/customapikey.json#/components/securityschemes/customapikey
+```
+
+
+### Targeting Mechanisms used in Reference objects
+
+Reference objects can use a relative reference with just a fragment identifier to point to an OAS Component.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object pointing to a parameter
+paths:
+  /jobs/{id}:
+    $ref: '#/components/pathItems/job'
+components:
+  pathItems:
+    job:
+      get:
+      patch:
+      delete:
+```
+
+Reference objects can reference OAS components in another OpenAPI document.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object pointing to an example object in an OpenAPI document
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: Ok
+            application/json:
+              examples:
+                item-list:
+                  $ref: './examples.yaml#/components/item-list'
+
+```
+
+```yaml
+# file for examples (examples.yaml)
+openapi: 3.1.0
+info:
+  title: OpenAPI document containing examples for reuse
+components:
+  examples:
+    item-list:
+      value:
+        - name: thing
+          description: a thing
+```
+
+For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but not complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object pointing to a parameter
+paths:
+  /items:
+    get:
+      responses:
+        200:
+          description: Ok
+            application/json:
+              examples:
+                item-list:
+                  $ref: './examples.yaml#/item-list'
+
+```
+
+```yaml
+# file for example fragments (examples.yaml)
+item-list:
+    value:
+    - name: thing
+        description: a thing
+```
+
+
+### What types Reference objects can target
+
+Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem.  In OpenAPI 3.0, they also can reference schema objects.
+
+## JSON Schema $refs in OpenAPI descriptions
\ No newline at end of file

From f313a605c7ebba7f8060293546e539963b57c21d Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Mon, 17 Feb 2025 13:18:03 -0500
Subject: [PATCH 02/16] Added the reference sources

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 139 +++++++++++++++++++++-
 1 file changed, 138 insertions(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 7ff67d4..59e78f5 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -24,6 +24,7 @@ This example below shows a common usage pattern of referencing a shared paramete
 openapi: 3.1.0
 info:
   title: Example of reference object pointing to a parameter
+  version: 1.0.0
 paths:
   /item:
     get:
@@ -41,6 +42,7 @@ The following example shows a way to externalize security schemes using a refere
 openapi: 3.1.0
 info:
   title: Example of reference object in a component object
+  version: 1.0.0
 paths:
   /item:
     get:
@@ -61,6 +63,7 @@ Reference objects can use a relative reference with just a fragment identifier t
 openapi: 3.1.0
 info:
   title: Example of reference object pointing to a parameter
+  version: 1.0.0
 paths:
   /jobs/{id}:
     $ref: '#/components/pathItems/job'
@@ -78,6 +81,7 @@ Reference objects can reference OAS components in another OpenAPI document.
 openapi: 3.1.0
 info:
   title: Example of reference object pointing to an example object in an OpenAPI document
+  version: 1.0.0
 paths:
   /items:
     get:
@@ -96,6 +100,7 @@ paths:
 openapi: 3.1.0
 info:
   title: OpenAPI document containing examples for reuse
+  version: 1.0.0
 components:
   examples:
     item-list:
@@ -110,6 +115,7 @@ For completeness, Reference Objects can also point to targets in a JSON/YAML doc
 openapi: 3.1.0
 info:
   title: Example of reference object pointing to a parameter
+  version: 1.0.0
 paths:
   /items:
     get:
@@ -136,4 +142,135 @@ item-list:
 
 Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem.  In OpenAPI 3.0, they also can reference schema objects.
 
-## JSON Schema $refs in OpenAPI descriptions
\ No newline at end of file
+## JSON Schema $refs in OpenAPI descriptions
+
+From OpenAPI 3.1 onwards, a `$ref` inside a Schema object is not considered an OpenAPI Reference Object. It behaves like a JSON Schema reference, specifically a JSON Schema 2020-12 reference, unless the dialect is changed for the OpenAPI document.
+
+### Where can JSON Schema references be used
+
+JSON Schema references can be used in the following locations:
+
+- at the root of an inline schema
+- in a subschema of an inline schema
+- at the root of a component schema
+- in a subschema of a component schema
+
+#### Root of an inline schema
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference in at the root of an inline schema
+    version: 1.0.0
+paths:
+    /item:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/item'
+components:
+    schemas:
+      item:
+        type: object
+
+```
+
+#### In a subschema of an inline schema
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference in at the root of an inline schema
+    version: 1.0.0
+paths:
+    /items:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/item'
+components:
+    schemas:
+      item:
+        type: object
+```
+
+#### At the root of a component schema
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference at the root of a component schema
+    version: 1.0.0
+paths:
+    /items:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/specialitem'
+components:
+    schemas:
+      specialitem:  # Use the item type but provide a different title for the type
+        title: Special Item
+        $ref: "#/components/schemas/item"
+      item:
+        type: object
+```
+
+#### In a subschema of a component schema
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference in a subschema of an component schema
+    version: 1.0.0
+paths:
+    /items:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/items'
+components:
+    schemas:
+      items:
+        type: array
+        items:
+            $ref: '#/components/schemas/item'
+      item:
+        type: object
+```
+
+
+### What kinds of JSON Schema references exist
+
+JSON Schema references can use either a locator or an identifier. Locators indicate where to find the target schema based on the name and structure of documents.  However, identifiers are opaque URIs that match to the identifer of a JSON schema that has a $id either explicitly or implicitly by inheriting an identity from its parent.
+
+### What can a JSON Schema locator reference target
+
+- An internal component
+- An interal component subschema
+- An internal inline subschema  [Not supported]
+- An external OpenApi document component
+- An external inline subchema [Not supported]
+- An external fragment [Not supported]
+
+### What can a JSON Schema identifier reference target
\ No newline at end of file

From 69f97c4d08855011d5a570729c6b8a18dc42f131 Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Mon, 17 Feb 2025 17:38:48 -0500
Subject: [PATCH 03/16] Added more reference examples

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 306 +++++++++++++++++++++-
 1 file changed, 305 insertions(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 59e78f5..448716b 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -271,6 +271,310 @@ JSON Schema references can use either a locator or an identifier. Locators indic
 - An internal inline subschema  [Not supported]
 - An external OpenApi document component
 - An external inline subchema [Not supported]
+- An external inline subchema using anchor
 - An external fragment [Not supported]
 
-### What can a JSON Schema identifier reference target
\ No newline at end of file
+#### An internal component
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an internal component
+    version: 1.0.0
+paths:
+    /item:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/item'
+components:
+  schemas:
+      item:
+        type: object
+```
+
+#### An interal component subschema
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an internal component
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/person'
+    /person/{id}/address:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/person/address'
+components:
+  schemas:
+      person:
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+```
+#### An external OpenApi document component
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an external OpenApi document component
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'OAS-schemas.yaml#/components/schemas/person'
+```
+
+```yaml
+# OAS-schemas.yaml file
+openapi: 3.1.0
+info:
+    title: OpenAPI document containing reusable components
+    version: 1.0.0
+components:
+  schemas:
+      person:
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+```
+
+
+#### An external inline subchema [Not supported and not recommended]
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an external OpenApi document component
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'OAS-schemas.yaml#/components/schemas/person/properties/address'
+```
+
+```yaml
+# OAS-schemas.yaml file
+openapi: 3.1.0
+info:
+    title: OpenAPI document containing reusable components
+    version: 1.0.0
+components:
+  schemas:
+      person:
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+
+```
+
+
+#### An external inline subchema using an anchor [Not currently supported]
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an external OpenApi document component
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'OAS-schemas.yaml#address'
+```
+
+```yaml
+# OAS-schemas.yaml file
+openapi: 3.1.0
+info:
+    title: OpenAPI document containing reusable components
+    version: 1.0.0
+components:
+  schemas:
+      person:
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                $anchor: address
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+
+```
+
+
+#### An external fragment [Not supported]
+
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference to an external OpenApi document component
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'OAS-schemas.yaml#/person/properties/address'
+```
+
+```yaml
+# OAS-schemas.yaml file
+person:
+  type: object
+  properties:
+    name:
+        type: string
+    address:
+        type: object
+        properties:
+            street:
+                type: string
+            city:
+                type: string
+
+```
+
+
+### What can a JSON Schema identifier reference target
+
+- Reference an internal component using a $id
+- Reference an internal subschema using a $id
+
+#### Reference an internal component using a $id 
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference an internal component using id
+    version: 1.0.0
+paths:
+    /person/{id}:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'https://schemas.acme.org/person'
+components:
+      person:
+        $id: 'https://schemas.acme.org/person'
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+```
+
+#### Reference an internal subschema using a $id
+```yaml
+openapi: 3.1.0
+info:
+    title: Reference an internal subschema using id
+    version: 1.0.0
+paths:
+    /person/{id}/address:
+        get:
+          responses:
+            200:
+              description: ok
+              content:
+                application/json:
+                  schema:
+                    $ref: 'https://schemas.acme.org/address'
+components:
+      person:
+        $id: 'https://schemas.acme.org/person'
+        type: object
+        properties:
+            name:
+                type: string
+            address:
+                $id: 'address'
+                type: object
+                properties:
+                    street:
+                        type: string
+                    city:
+                        type: string
+```
+
+#### Reference an external components and subschemas using a $id
+
+External components and subschemas are referenced in the exact same way as internal components.
+

From b89b424105c77e9f6a7b40038f69ae811b16f8b9 Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Mon, 17 Feb 2025 17:42:11 -0500
Subject: [PATCH 04/16] Added new heading

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 448716b..97c5687 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -508,8 +508,9 @@ person:
 
 - Reference an internal component using a $id
 - Reference an internal subschema using a $id
+- Reference external components and subschemas using a $id
 
-#### Reference an internal component using a $id 
+#### Reference an internal component using a $id
 ```yaml
 openapi: 3.1.0
 info:
@@ -574,7 +575,7 @@ components:
                         type: string
 ```
 
-#### Reference an external components and subschemas using a $id
+#### Reference external components and subschemas using a $id
 
 External components and subschemas are referenced in the exact same way as internal components.
 

From c2b8bfcee7340f62efbe9bb87b9b68c3d0278afb Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Sat, 19 Apr 2025 15:10:04 -0400
Subject: [PATCH 05/16] Many updates to the references examples

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 122 ++++++++++++++++++----
 1 file changed, 103 insertions(+), 19 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 97c5687..d972881 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -62,17 +62,19 @@ Reference objects can use a relative reference with just a fragment identifier t
 ```yaml
 openapi: 3.1.0
 info:
-  title: Example of reference object pointing to a parameter
+  title: Example of reference object pointing to a pathitem
   version: 1.0.0
 paths:
   /jobs/{id}:
-    $ref: '#/components/pathItems/job'
+    post:
+      requestBody:
+        $ref: '#/components/requestBodies/job'
 components:
-  pathItems:
+  requestBodies:
     job:
-      get:
-      patch:
-      delete:
+      required: true
+      content:
+        application/json: {}
 ```
 
 Reference objects can reference OAS components in another OpenAPI document.
@@ -91,8 +93,7 @@ paths:
             application/json:
               examples:
                 item-list:
-                  $ref: './examples.yaml#/components/item-list'
-
+                  $ref: './examples.yaml#/components/examples/item-list'
 ```
 
 ```yaml
@@ -109,7 +110,7 @@ components:
           description: a thing
 ```
 
-For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but not complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments.
+For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but is not a complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments.
 
 ```yaml
 openapi: 3.1.0
@@ -132,15 +133,15 @@ paths:
 ```yaml
 # file for example fragments (examples.yaml)
 item-list:
-    value:
-    - name: thing
-        description: a thing
+  value:
+  - name: thing
+    description: a thing
 ```
 
 
 ### What types Reference objects can target
 
-Reference objects can be used to target the follow OAS types: parameter, response, example, header, securityScheme, link, callback and pathItem.  In OpenAPI 3.0, they also can reference schema objects.
+Reference objects can be used to target the follow OAS types: parameter, response, requestBody, example, header, securityScheme, link, callback and pathItem.  In OpenAPI 3.0, they also can reference schema objects.
 
 ## JSON Schema $refs in OpenAPI descriptions
 
@@ -229,6 +230,7 @@ components:
         title: Special Item
         $ref: "#/components/schemas/item"
       item:
+        title: Item
         type: object
 ```
 
@@ -259,6 +261,63 @@ components:
         type: object
 ```
 
+#### References local to a JSON Schema Resource defined by an OpenAPI Schema
+
+JSON Schema defines the concept of a JSON Schema Resource which is identified by a URI.  $ref values can be specified relative to the JSON Schema Resource.  Each OpenAPI schema object can be considered a JSON Schema Resource.
+
+In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a".  Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This should be resolved in OpenAPI 3.2 with the introduction of a new top level "self" property.
+
+```yaml
+components:
+schema:
+  a:
+    type:
+        - object
+        - 'null'
+    properties:
+        b:
+            type:
+                - object
+                - 'null'
+            properties:
+                c:
+                    type:
+                        - object
+                        - 'null'
+                    properties:
+                        b:
+                            $ref: '#/properties/b'
+```
+
+#### References local to a JSON Schema Resource defined by a $id
+
+```yaml
+components:
+schema:
+  a:
+    type:
+        - object
+        - 'null'
+    additionalProperties: false
+    properties:
+        b:
+            type:
+                - object
+                - 'null'
+            additionalProperties: false
+            properties:
+                c:
+                    $id: 'http://example.org/c'
+                    type:
+                        - object
+                        - 'null'
+                    additionalProperties: false
+                    properties:
+                        b:
+                            $ref: '#/properties/d'
+                        d:
+                            type: string
+```
 
 ### What kinds of JSON Schema references exist
 
@@ -268,7 +327,7 @@ JSON Schema references can use either a locator or an identifier. Locators indic
 
 - An internal component
 - An interal component subschema
-- An internal inline subschema  [Not supported]
+- An internal inline subschema
 - An external OpenApi document component
 - An external inline subchema [Not supported]
 - An external inline subchema using anchor
@@ -297,7 +356,7 @@ components:
         type: object
 ```
 
-#### An interal component subschema
+#### An internal component subschema
 
 ```yaml
 openapi: 3.1.0
@@ -322,7 +381,7 @@ paths:
               content:
                 application/json:
                   schema:
-                    $ref: '#/components/schemas/person/address'
+                    $ref: '#/components/schemas/person/properties/address'
 components:
   schemas:
       person:
@@ -338,6 +397,8 @@ components:
                     city:
                         type: string
 ```
+
+
 #### An external OpenApi document component
 
 ```yaml
@@ -380,7 +441,7 @@ components:
 ```
 
 
-#### An external inline subchema [Not supported and not recommended]
+#### An external inline subchema
 
 ```yaml
 openapi: 3.1.0
@@ -425,6 +486,8 @@ components:
 
 #### An external inline subchema using an anchor [Not currently supported]
 
+We accept pull requests.
+
 ```yaml
 openapi: 3.1.0
 info:
@@ -500,7 +563,6 @@ person:
                 type: string
             city:
                 type: string
-
 ```
 
 
@@ -542,12 +604,14 @@ components:
                         type: string
 ```
 
-#### Reference an internal subschema using a $id
+#### Reference an internal subschema using a $id  [Not supported yet]
+
 ```yaml
 openapi: 3.1.0
 info:
     title: Reference an internal subschema using id
     version: 1.0.0
+
 paths:
     /person/{id}/address:
         get:
@@ -579,3 +643,23 @@ components:
 
 External components and subschemas are referenced in the exact same way as internal components.
 
+## $ref in PathItem Objects
+
+This scenario is unsupported in OpenAPI.NET.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Example of reference object pointing to a pathitem
+  version: 1.0.0
+paths:
+  /jobs/{id}:
+    get:
+    $ref: '#/components/pathItems/job'
+components:
+  pathItems:
+    job:
+      get:
+      patch:
+      delete:
+```

From f505411076358b04475510aeaf308e9c90a11dad Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Fri, 26 Jun 2026 15:25:52 -0400
Subject: [PATCH 06/16] chore: typo fix

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index d972881..50197b4 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -326,7 +326,7 @@ JSON Schema references can use either a locator or an identifier. Locators indic
 ### What can a JSON Schema locator reference target
 
 - An internal component
-- An interal component subschema
+- An internal component subschema
 - An internal inline subschema
 - An external OpenApi document component
 - An external inline subchema [Not supported]

From 7a89cfd942bc4679d18ee0f7548c562d6764c5d7 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Fri, 26 Jun 2026 15:26:08 -0400
Subject: [PATCH 07/16] chore: indent fix in example

---
 OpenAPI/OpenAPI.NET/references-openapi.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 50197b4..58cc902 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -655,7 +655,7 @@ info:
 paths:
   /jobs/{id}:
     get:
-    $ref: '#/components/pathItems/job'
+  $ref: '#/components/pathItems/job'
 components:
   pathItems:
     job:

From a250ebdd6fa6675e9e47e53e820e0910880d4de4 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 13:23:55 -0400
Subject: [PATCH 08/16] chore: fixes docfx issues

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 58cc902..cb24153 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -1,9 +1,10 @@
 ---
 title: References in OpenAPI documents
 description: Learn the types of references that are supportined in the OpenAPI.NET library.
-author: darrmi
+author: darrelmiller
 ms.author: darrmi
-ms.topic: conceptual
+ms.topic: article
+ms.date: 02/17/2025
 ---
 
 # References in OpenAPI documents

From 1e2a79335e9b042c75d5d9ff8bda15756ed328b3 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 13:41:33 -0400
Subject: [PATCH 09/16] chore: formatting issues fix: invalid examples

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 586 +++++++++++-----------
 1 file changed, 290 insertions(+), 296 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index cb24153..a41332c 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -47,15 +47,14 @@ info:
 paths:
   /item:
     get:
-        security:
-            - customapikey: []
+      security:
+        - customapikey: []
 components:
   securitySchemes:
     customapikey:
-        $ref: ./commonSecuritySchemes/customapikey.json#/components/securityschemes/customapikey
+      $ref: ./commonSecuritySchemes/customapikey.json#/components/securityschemes/customapikey
 ```
 
-
 ### Targeting Mechanisms used in Reference objects
 
 Reference objects can use a relative reference with just a fragment identifier to point to an OAS Component.
@@ -139,7 +138,6 @@ item-list:
     description: a thing
 ```
 
-
 ### What types Reference objects can target
 
 Reference objects can be used to target the follow OAS types: parameter, response, requestBody, example, header, securityScheme, link, callback and pathItem.  In OpenAPI 3.0, they also can reference schema objects.
@@ -162,23 +160,22 @@ JSON Schema references can be used in the following locations:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference in at the root of an inline schema
-    version: 1.0.0
+  title: Reference in at the root of an inline schema
+  version: 1.0.0
 paths:
-    /item:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/item'
+  /item:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/item'
 components:
-    schemas:
-      item:
-        type: object
-
+  schemas:
+    item:
+      type: object
 ```
 
 #### In a subschema of an inline schema
@@ -186,24 +183,24 @@ components:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference in at the root of an inline schema
-    version: 1.0.0
+  title: Reference in at the root of an inline schema
+  version: 1.0.0
 paths:
-    /items:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/item'
+  /items:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/item'
 components:
-    schemas:
-      item:
-        type: object
+  schemas:
+    item:
+      type: object
 ```
 
 #### At the root of a component schema
@@ -211,28 +208,28 @@ components:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference at the root of a component schema
-    version: 1.0.0
+  title: Reference at the root of a component schema
+  version: 1.0.0
 paths:
-    /items:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/specialitem'
+  /items:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/specialitem'
 components:
-    schemas:
-      specialitem:  # Use the item type but provide a different title for the type
-        title: Special Item
-        $ref: "#/components/schemas/item"
-      item:
-        title: Item
-        type: object
+  schemas:
+    specialitem:  # Use the item type but provide a different title for the type
+      title: Special Item
+      $ref: "#/components/schemas/item"
+    item:
+      title: Item
+      type: object
 ```
 
 #### In a subschema of a component schema
@@ -240,26 +237,26 @@ components:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference in a subschema of an component schema
-    version: 1.0.0
+  title: Reference in a subschema of an component schema
+  version: 1.0.0
 paths:
-    /items:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/items'
+  /items:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/items'
 components:
-    schemas:
+  schemas:
+    items:
+      type: array
       items:
-        type: array
-        items:
-            $ref: '#/components/schemas/item'
-      item:
-        type: object
+        $ref: '#/components/schemas/item'
+    item:
+      type: object
 ```
 
 #### References local to a JSON Schema Resource defined by an OpenAPI Schema
@@ -270,24 +267,24 @@ In this example schema "a" is a JSON Schema resource and the reference in the "b
 
 ```yaml
 components:
-schema:
-  a:
-    type:
+  schemas:
+    a:
+      type:
         - object
         - 'null'
-    properties:
+      properties:
         b:
-            type:
+          type:
+            - object
+            - 'null'
+          properties:
+            c:
+              type:
                 - object
                 - 'null'
-            properties:
-                c:
-                    type:
-                        - object
-                        - 'null'
-                    properties:
-                        b:
-                            $ref: '#/properties/b'
+              properties:
+                b:
+                  $ref: '#/properties/b'
 ```
 
 #### References local to a JSON Schema Resource defined by a $id
@@ -297,27 +294,27 @@ components:
 schema:
   a:
     type:
-        - object
-        - 'null'
+      - object
+      - 'null'
     additionalProperties: false
     properties:
-        b:
+      b:
+        type:
+          - object
+          - 'null'
+        additionalProperties: false
+        properties:
+          c:
+            $id: 'http://example.org/c'
             type:
-                - object
-                - 'null'
+              - object
+              - 'null'
             additionalProperties: false
             properties:
-                c:
-                    $id: 'http://example.org/c'
-                    type:
-                        - object
-                        - 'null'
-                    additionalProperties: false
-                    properties:
-                        b:
-                            $ref: '#/properties/d'
-                        d:
-                            type: string
+              b:
+                $ref: '#/properties/d'
+              d:
+                type: string
 ```
 
 ### What kinds of JSON Schema references exist
@@ -339,22 +336,22 @@ JSON Schema references can use either a locator or an identifier. Locators indic
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an internal component
-    version: 1.0.0
+  title: Reference to an internal component
+  version: 1.0.0
 paths:
-    /item:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/item'
+  /item:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/item'
 components:
   schemas:
-      item:
-        type: object
+    item:
+      type: object
 ```
 
 #### An internal component subschema
@@ -362,129 +359,125 @@ components:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an internal component
-    version: 1.0.0
+  title: Reference to an internal component
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/person'
-    /person/{id}/address:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: '#/components/schemas/person/properties/address'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/person'
+  /person/{id}/address:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/person/properties/address'
 components:
   schemas:
-      person:
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
+    person:
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 ```
 
-
 #### An external OpenApi document component
 
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an external OpenApi document component
-    version: 1.0.0
+  title: Reference to an external OpenApi document component
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'OAS-schemas.yaml#/components/schemas/person'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'OAS-schemas.yaml#/components/schemas/person'
 ```
 
 ```yaml
 # OAS-schemas.yaml file
 openapi: 3.1.0
 info:
-    title: OpenAPI document containing reusable components
-    version: 1.0.0
+  title: OpenAPI document containing reusable components
+  version: 1.0.0
 components:
   schemas:
-      person:
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
+    person:
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 ```
 
-
 #### An external inline subchema
 
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an external OpenApi document component
-    version: 1.0.0
+  title: Reference to an external OpenApi document component
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'OAS-schemas.yaml#/components/schemas/person/properties/address'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'OAS-schemas.yaml#/components/schemas/person/properties/address'
 ```
 
 ```yaml
 # OAS-schemas.yaml file
 openapi: 3.1.0
 info:
-    title: OpenAPI document containing reusable components
-    version: 1.0.0
+  title: OpenAPI document containing reusable components
+  version: 1.0.0
 components:
   schemas:
-      person:
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
-
+    person:
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 ```
 
-
 #### An external inline subchema using an anchor [Not currently supported]
 
 We accept pull requests.
@@ -492,62 +485,61 @@ We accept pull requests.
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an external OpenApi document component
-    version: 1.0.0
+  title: Reference to an external OpenApi document component
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'OAS-schemas.yaml#address'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'OAS-schemas.yaml#address'
 ```
 
 ```yaml
 # OAS-schemas.yaml file
 openapi: 3.1.0
 info:
-    title: OpenAPI document containing reusable components
-    version: 1.0.0
+  title: OpenAPI document containing reusable components
+  version: 1.0.0
 components:
   schemas:
-      person:
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                $anchor: address
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
+    person:
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          $anchor: address
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 
 ```
 
-
 #### An external fragment [Not supported]
 
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference to an external OpenApi document component
-    version: 1.0.0
+  title: Reference to an external OpenApi document component
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'OAS-schemas.yaml#/person/properties/address'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'OAS-schemas.yaml#/person/properties/address'
 ```
 
 ```yaml
@@ -556,17 +548,16 @@ person:
   type: object
   properties:
     name:
-        type: string
+      type: string
     address:
-        type: object
-        properties:
-            street:
-                type: string
-            city:
-                type: string
+      type: object
+      properties:
+        street:
+          type: string
+        city:
+          type: string
 ```
 
-
 ### What can a JSON Schema identifier reference target
 
 - Reference an internal component using a $id
@@ -574,35 +565,37 @@ person:
 - Reference external components and subschemas using a $id
 
 #### Reference an internal component using a $id
+
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference an internal component using id
-    version: 1.0.0
+  title: Reference an internal component using id
+  version: 1.0.0
 paths:
-    /person/{id}:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'https://schemas.acme.org/person'
+  /person/{id}:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'https://schemas.acme.org/person'
 components:
-      person:
-        $id: 'https://schemas.acme.org/person'
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
+  schemas:
+    person:
+      $id: 'https://schemas.acme.org/person'
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 ```
 
 #### Reference an internal subschema using a $id  [Not supported yet]
@@ -610,34 +603,35 @@ components:
 ```yaml
 openapi: 3.1.0
 info:
-    title: Reference an internal subschema using id
-    version: 1.0.0
+  title: Reference an internal subschema using id
+  version: 1.0.0
 
 paths:
-    /person/{id}/address:
-        get:
-          responses:
-            200:
-              description: ok
-              content:
-                application/json:
-                  schema:
-                    $ref: 'https://schemas.acme.org/address'
+  /person/{id}/address:
+    get:
+      responses:
+        200:
+          description: ok
+          content:
+            application/json:
+              schema:
+                $ref: 'https://schemas.acme.org/address'
 components:
-      person:
-        $id: 'https://schemas.acme.org/person'
-        type: object
-        properties:
-            name:
-                type: string
-            address:
-                $id: 'address'
-                type: object
-                properties:
-                    street:
-                        type: string
-                    city:
-                        type: string
+  schemas:
+    person:
+      $id: 'https://schemas.acme.org/person'
+      type: object
+      properties:
+        name:
+          type: string
+        address:
+          $id: 'address'
+          type: object
+          properties:
+            street:
+              type: string
+            city:
+              type: string
 ```
 
 #### Reference external components and subschemas using a $id

From d54567103ec3a85bda7fc824d1510cc2d7b3f414 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 13:46:51 -0400
Subject: [PATCH 10/16] chore: more formatting

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 26 +++++++++++++----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index a41332c..e511565 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -1,6 +1,6 @@
 ---
 title: References in OpenAPI documents
-description: Learn the types of references that are supportined in the OpenAPI.NET library.
+description: Learn the types of references that are supported in the OpenAPI.NET library.
 author: darrelmiller
 ms.author: darrmi
 ms.topic: article
@@ -34,7 +34,10 @@ paths:
 components:
   parameters:
     size:
-     type: number
+      name: size
+      in: query
+      schema:
+        type: number
 ```
 
 The following example shows a way to externalize security schemes using a reference object in a component.  This is necessary because security requirement objects do not allow referencing using an external URI.
@@ -52,7 +55,7 @@ paths:
 components:
   securitySchemes:
     customapikey:
-      $ref: ./commonSecuritySchemes/customapikey.json#/components/securityschemes/customapikey
+      $ref: ./commonSecuritySchemes/customapikey.json#/components/securitySchemes/customapikey
 ```
 
 ### Targeting Mechanisms used in Reference objects
@@ -90,6 +93,7 @@ paths:
       responses:
         200:
           description: Ok
+          content:
             application/json:
               examples:
                 item-list:
@@ -123,6 +127,7 @@ paths:
       responses:
         200:
           description: Ok
+          content:
             application/json:
               examples:
                 item-list:
@@ -134,8 +139,8 @@ paths:
 # file for example fragments (examples.yaml)
 item-list:
   value:
-  - name: thing
-    description: a thing
+    - name: thing
+      description: a thing
 ```
 
 ### What types Reference objects can target
@@ -291,7 +296,7 @@ components:
 
 ```yaml
 components:
-schema:
+  schemas:
   a:
     type:
       - object
@@ -649,12 +654,11 @@ info:
   version: 1.0.0
 paths:
   /jobs/{id}:
-    get:
-  $ref: '#/components/pathItems/job'
+    $ref: '#/components/pathItems/job'
 components:
   pathItems:
     job:
-      get:
-      patch:
-      delete:
+      get: {}
+      patch: {}
+      delete: {}
 ```

From b6e1d73801149937b9884057516cb86f00b7f958 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:01:09 -0400
Subject: [PATCH 11/16] docs: adds clarifications about $id and resources
 behaviour

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index e511565..82e2e2a 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -268,11 +268,14 @@ components:
 
 JSON Schema defines the concept of a JSON Schema Resource which is identified by a URI.  $ref values can be specified relative to the JSON Schema Resource.  Each OpenAPI schema object can be considered a JSON Schema Resource.
 
-In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a".  Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This should be resolved in OpenAPI 3.2 with the introduction of a new top level "self" property.
+In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a".  Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This is resolved in OpenAPI 3.2 with the introduction of a new top level "self" property.
 
 ```yaml
 components:
   schemas:
+  # this component schema is ALSO a JSON schema resource
+  # therefore, the ref is relative to this schema.
+  # this would also work if the whole tree is a schema inside a media type schema, etc...
     a:
       type:
         - object
@@ -292,7 +295,7 @@ components:
                   $ref: '#/properties/b'
 ```
 
-#### References local to a JSON Schema Resource defined by a $id
+#### References local to a JSON Schema Resource defined by a $id [Not currently supported]
 
 ```yaml
 components:
@@ -310,6 +313,8 @@ components:
         additionalProperties: false
         properties:
           c:
+          # this is similar to the prior example, but the $id here turns this specific schema in a resource
+          # it effectively defines a "new root" for relative lookups.
             $id: 'http://example.org/c'
             type:
               - object
@@ -324,7 +329,7 @@ components:
 
 ### What kinds of JSON Schema references exist
 
-JSON Schema references can use either a locator or an identifier. Locators indicate where to find the target schema based on the name and structure of documents.  However, identifiers are opaque URIs that match to the identifer of a JSON schema that has a $id either explicitly or implicitly by inheriting an identity from its parent.
+JSON Schema references can use either a locator or an identifier. Locators indicate where to find the target schema based on the name and structure of documents.  However, identifiers are opaque URIs that match to the identifier of a JSON schema that has a $id either explicitly or implicitly by inheriting an identity from its parent.
 
 ### What can a JSON Schema locator reference target
 
@@ -417,6 +422,7 @@ paths:
           content:
             application/json:
               schema:
+                # the URI is assumed to be relative according to RFC 3986
                 $ref: 'OAS-schemas.yaml#/components/schemas/person'
 ```
 
@@ -630,6 +636,8 @@ components:
         name:
           type: string
         address:
+          # this is equivalent to https://schemas.acme.org/address because
+          # https://schemas.acme.org/person does NOT end up with / (RFC 3986)
           $id: 'address'
           type: object
           properties:

From 6f9ad82f63c5cbed7b1d7a695188a4a9a64d0b76 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:02:19 -0400
Subject: [PATCH 12/16] fix: property name

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 82e2e2a..fae8df6 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -268,7 +268,7 @@ components:
 
 JSON Schema defines the concept of a JSON Schema Resource which is identified by a URI.  $ref values can be specified relative to the JSON Schema Resource.  Each OpenAPI schema object can be considered a JSON Schema Resource.
 
-In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a".  Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This is resolved in OpenAPI 3.2 with the introduction of a new top level "self" property.
+In this example schema "a" is a JSON Schema resource and the reference in the "b" property of the "c" object is relative to the JSON Schema resource "a".  Unfortunately, OpenAPI 3.1 has no well defined URIs for OpenAPI Schemas. This is resolved in OpenAPI 3.2 with the introduction of a new top level "$self" property.
 
 ```yaml
 components:

From ff0a715e857e8c4c7c4c75f5e17d0ea91532b82d Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:05:06 -0400
Subject: [PATCH 13/16] docs: adds the page to the TOC

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/openapi.net/toc.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/OpenAPI/openapi.net/toc.yml b/OpenAPI/openapi.net/toc.yml
index 5d15639..1c0a9f0 100644
--- a/OpenAPI/openapi.net/toc.yml
+++ b/OpenAPI/openapi.net/toc.yml
@@ -7,3 +7,5 @@ items:
   href: modify-openapi.md
 - name: Convert an OpenAPI document
   href: convert-openapi.md
+- name: References in OpenAPI documents
+  href: references-openapi.md
\ No newline at end of file

From 0929f7d24659b78aac6e0eeb8c57183f94be1dd1 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:39:09 -0400
Subject: [PATCH 14/16] docs: adds dynamic reference resolution example

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 50 +++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index fae8df6..3ae078a 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -651,6 +651,56 @@ components:
 
 External components and subschemas are referenced in the exact same way as internal components.
 
+## $dynamicAnchor and $dynamicRef [Not currently supported]
+
+JSON Schema 2020-12, which is the basis for OpenAPI 3.1 schemas, introduces `$dynamicAnchor` and `$dynamicRef` as a mechanism for building extensible, generic schemas. They work together as overridable extension hooks:
+
+- `$dynamicAnchor` declares a named placeholder anchor in a schema. Any parent schema that references it can redefine the anchor to specialize behavior.
+- `$dynamicRef` references a dynamic anchor. Unlike `$ref`, it does not resolve statically. Instead, evaluation looks back through the stack of schema resources traversed so far, and jumps to the **first** encountered definition of that anchor. This allows a specializing schema to override the referenced subschema.
+
+This is analogous to generic type parameters in programming languages such as C++ templates or Java generics.
+
+OpenAPI.NET exposes `$dynamicAnchor` and `$dynamicRef` as properties on the schema model, but dynamic reference resolution is not currently implemented.
+
+The following example defines a generic `collection` schema whose item type can be overridden by a more specialized schema.
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Generic collection schema using $dynamicAnchor and $dynamicRef
+  version: 1.0.0
+components:
+  schemas:
+    # A generic, reusable collection schema.
+    # The item type is left open and can be overridden by a specializing
+    # schema that redefines the "collection-item" dynamic anchor.
+    collection:
+      $id: 'https://schemas.acme.org/collection'
+      type: array
+      items:
+        $dynamicRef: '#collection-item'
+      $defs:
+        default:
+          $comment: Default declaration to satisfy the bookending requirement
+          $dynamicAnchor: collection-item
+
+    # A specialized collection schema that constrains items to strings.
+    # It references the generic schema and overrides the dynamic anchor.
+    string-collection:
+      $ref: 'https://schemas.acme.org/collection'
+      $defs:
+        collection-item:
+          $dynamicAnchor: collection-item
+          type: string
+```
+
+In this example:
+
+- `collection` uses `$dynamicRef: '#collection-item'` to declare that each array item should validate against whatever `collection-item` resolves to at runtime.
+- The `$defs/default` subschema in `collection` declares the `$dynamicAnchor: collection-item` placeholder. This satisfies the *bookending requirement*: the base schema that uses `$dynamicRef` must itself provide a `$dynamicAnchor` with the same name, even if it imposes no constraints.
+- `string-collection` uses `$ref` to extend `collection` and redefines `collection-item` in its own `$defs` with `type: string`.
+- When `string-collection` is evaluated, the `$dynamicRef` in `collection` resolves to the `collection-item` anchor defined in `string-collection`, effectively constraining all array items to be strings.
+
 ## $ref in PathItem Objects
 
 This scenario is unsupported in OpenAPI.NET.

From d99c64aa940357e4e7a3f00d5ce0098a96ef49ef Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:39:35 -0400
Subject: [PATCH 15/16] fix: path items references

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index 3ae078a..e6c209e 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -703,7 +703,7 @@ In this example:
 
 ## $ref in PathItem Objects
 
-This scenario is unsupported in OpenAPI.NET.
+This scenario is supported in OpenAPI.NET.
 
 ```yaml
 openapi: 3.1.0

From aa34f1a747dc0e263bd344c85baeeede095cd2b6 Mon Sep 17 00:00:00 2001
From: Vincent Biret <vibiret@microsoft.com>
Date: Mon, 29 Jun 2026 14:49:10 -0400
Subject: [PATCH 16/16] docs: updates which patterns are supported or not

Signed-off-by: Vincent Biret <vibiret@microsoft.com>
---
 OpenAPI/OpenAPI.NET/references-openapi.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/OpenAPI/OpenAPI.NET/references-openapi.md b/OpenAPI/OpenAPI.NET/references-openapi.md
index e6c209e..646430d 100644
--- a/OpenAPI/OpenAPI.NET/references-openapi.md
+++ b/OpenAPI/OpenAPI.NET/references-openapi.md
@@ -337,8 +337,8 @@ JSON Schema references can use either a locator or an identifier. Locators indic
 - An internal component subschema
 - An internal inline subschema
 - An external OpenApi document component
-- An external inline subchema [Not supported]
-- An external inline subchema using anchor
+- An external inline subchema
+- An external inline subchema using anchor [Not currently supported]
 - An external fragment [Not supported]
 
 #### An internal component
@@ -572,8 +572,8 @@ person:
 ### What can a JSON Schema identifier reference target
 
 - Reference an internal component using a $id
-- Reference an internal subschema using a $id
-- Reference external components and subschemas using a $id
+- Reference an internal subschema using a $id [Not supported yet]
+- Reference an external component schema using a $id
 
 #### Reference an internal component using a $id
 
@@ -647,9 +647,9 @@ components:
               type: string
 ```
 
-#### Reference external components and subschemas using a $id
+#### Reference external component schemas using a $id
 
-External components and subschemas are referenced in the exact same way as internal components.
+External component schemas are referenced in the exact same way as internal component schemas. External subschemas that rely on their own `$id` are not currently supported.
 
 ## $dynamicAnchor and $dynamicRef [Not currently supported]