From 018c13bee48e90ed9fa5f7793c0052d5cf2ebdc8 Mon Sep 17 00:00:00 2001
From: Abdullah Alaqeel <abdullah.t.aqeel@gmail.com>
Date: Wed, 15 Jul 2026 23:38:55 +0300
Subject: [PATCH] docs(schema): document OpenApiSchemaReference getter
 semantics

---
 .../Models/References/OpenApiSchemaReference.cs             | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
index 7f206d686..6a9455775 100644
--- a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
+++ b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
@@ -9,7 +9,11 @@ namespace Microsoft.OpenApi
 {
 #pragma warning disable CS0618
     /// <summary>
-    /// Schema reference object
+    /// Schema reference object.
+    /// Convenience getters return <c>$ref</c>-sibling keyword values authored on
+    /// <see cref="IOpenApiReferenceHolder{V}.Reference"/> before falling back to resolved values from <see cref="Target"/>.
+    /// These getters are object-model conveniences and do not represent JSON Schema
+    /// evaluation semantics.
     /// </summary>
     public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema, IOpenApiSchema, JsonSchemaReference>, IOpenApiSchema, IOpenApiSchemaMissingProperties, IOpenApiSchemaWithUnevaluatedProperties, IOpenApiExtensible
     {