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

Add XML documentation clarifying that convenience getters on
OpenApiSchemaReference return authored sibling keyword values from
Reference before falling back to resolved Target values. These getters
are object-model conveniences and do not represent JSON Schema
evaluation semantics.

Per #2919 discussion: keep existing reference-first getter behavior for
consistency and document it explicitly rather than changing behavior per
keyword type.

Fixes #2919
---
 .../Models/References/OpenApiSchemaReference.cs              | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
index 51187591c..6fb52b663 100644
--- a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
+++ b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
@@ -9,7 +9,10 @@ namespace Microsoft.OpenApi
 {
 #pragma warning disable CS0618
     /// <summary>
-    /// Schema reference object
+    /// Schema reference object.
+    /// Convenience getters return authored sibling keyword values from <see cref="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
     {