From e3387fa8227a4246fe97b5626528c7cdb4159c8f Mon Sep 17 00:00:00 2001
From: Abdullah Alaqeel <abdullah.t.aqeel@gmail.com>
Date: Thu, 16 Jul 2026 16:35:45 +0300
Subject: [PATCH] Merge pull request #2921 from
 aqeelat/fix/schema-reference-sibling-semantics

docs(schema): apply additive JSON Schema semantics to $ref sibling getters
---
 .../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 fe55f974c..5ee20d786 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
     {