feat: add UnevaluatedPropertiesSchema support to IOpenApiSchema

- Create IOpenApiSchemaWithUnevaluatedProperties interface for binary compatibility
- Add UnevaluatedPropertiesSchema property to OpenApiSchema
- Update OpenApiSchemaReference to implement new interface
- Update serialization to handle both boolean and schema cases
- Update V31 deserialization to handle both boolean and schema cases
- Add comprehensive documentation with TODO markers for next major version

Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Author: Copilot

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs

@@ -258,8 +258,15 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     public IList<JsonNode>? Enum { get; }
 
     /// <summary>
-    /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-validation
-    /// </summary>
+    /// Indicates whether unevaluated properties are allowed. When false, no unevaluated properties are permitted.
+    /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-core#name-unevaluatedproperties
+    /// Only serialized when false and UnevaluatedPropertiesSchema (from IOpenApiSchemaWithUnevaluatedProperties) is null.
+    /// </summary>
+    /// <remarks>
+    /// NOTE: This property differs from the naming pattern of AdditionalPropertiesAllowed for binary compatibility reasons.
+    /// In the next major version, this will be renamed to UnevaluatedPropertiesAllowed.
+    /// TODO: Rename to UnevaluatedPropertiesAllowed in the next major version.
+    /// </remarks>
     public bool UnevaluatedProperties { get; } 
 
     /// <summary>

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchemaWithUnevaluatedProperties.cs

@@ -0,0 +1,32 @@
+namespace Microsoft.OpenApi;
+
+/// <summary>
+/// Compatibility interface for UnevaluatedProperties schema support.
+/// This interface provides access to the UnevaluatedPropertiesSchema property, which represents
+/// the schema for unevaluated properties as defined in JSON Schema draft 2020-12.
+/// 
+/// NOTE: This is a temporary compatibility solution. In the next major version:
+/// - This interface will be merged into IOpenApiSchema
+/// - The UnevaluatedPropertiesSchema property will be renamed to UnevaluatedProperties
+/// - The current UnevaluatedProperties boolean property will be renamed to UnevaluatedPropertiesAllowed
+/// </summary>
+/// <remarks>
+/// TODO: Remove this interface in the next major version and merge its content into IOpenApiSchema.
+/// </remarks>
+public interface IOpenApiSchemaWithUnevaluatedProperties
+{
+    /// <summary>
+    /// Follow JSON Schema definition: https://json-schema.org/draft/2020-12/json-schema-core#name-unevaluatedproperties
+    /// This is a schema that unevaluated properties must validate against.
+    /// When serialized, this takes precedence over the UnevaluatedProperties boolean property.
+    /// </summary>
+    /// <remarks>
+    /// NOTE: This property differs from the naming pattern of AdditionalProperties/AdditionalPropertiesAllowed 
+    /// for binary compatibility reasons. In the next major version:
+    /// - This property will be renamed to UnevaluatedProperties
+    /// - The current boolean UnevaluatedProperties property will be renamed to UnevaluatedPropertiesAllowed
+    /// 
+    /// TODO: Rename this property to UnevaluatedProperties in the next major version.
+    /// </remarks>
+    IOpenApiSchema? UnevaluatedPropertiesSchema { get; }
+}

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -12,7 +12,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// The Schema Object allows the definition of input and output data types.
     /// </summary>
-    public class OpenApiSchema : IOpenApiExtensible, IOpenApiSchema, IMetadataContainer
+    public class OpenApiSchema : IOpenApiExtensible, IOpenApiSchema, IOpenApiSchemaWithUnevaluatedProperties, IMetadataContainer
     {
         /// <inheritdoc />
         public string? Title { get; set; }
@@ -234,6 +234,9 @@ public string? Minimum
         /// <inheritdoc />
         public bool UnevaluatedProperties { get; set; }
 
+        /// <inheritdoc />
+        public IOpenApiSchema? UnevaluatedPropertiesSchema { get; set; }
+
         /// <inheritdoc />
         public OpenApiExternalDocs? ExternalDocs { get; set; }
 
@@ -277,6 +280,10 @@ internal OpenApiSchema(IOpenApiSchema schema)
             DynamicRef = schema.DynamicRef ?? DynamicRef;
             Definitions = schema.Definitions != null ? new Dictionary<string, IOpenApiSchema>(schema.Definitions) : null;
             UnevaluatedProperties = schema.UnevaluatedProperties;
+            if (schema is IOpenApiSchemaWithUnevaluatedProperties schemaWithUnevaluated)
+            {
+                UnevaluatedPropertiesSchema = schemaWithUnevaluated.UnevaluatedPropertiesSchema?.CreateShallowCopy();
+            }
             ExclusiveMaximum = schema.ExclusiveMaximum ?? ExclusiveMaximum;
             ExclusiveMinimum = schema.ExclusiveMinimum ?? ExclusiveMinimum;
             if (schema is OpenApiSchema eMSchema)
@@ -565,7 +572,20 @@ internal void WriteJsonSchemaKeywords(IOpenApiWriter writer)
             writer.WriteOptionalMap(OpenApiConstants.Defs, Definitions, (w, s) => s.SerializeAsV31(w));
             writer.WriteProperty(OpenApiConstants.DynamicRef, DynamicRef);
             writer.WriteProperty(OpenApiConstants.DynamicAnchor, DynamicAnchor);
-            writer.WriteProperty(OpenApiConstants.UnevaluatedProperties, UnevaluatedProperties, false);
+            
+            // UnevaluatedProperties: similar to AdditionalProperties, serialize as schema if present, else as boolean
+            if (UnevaluatedPropertiesSchema is not null)
+            {
+                writer.WriteOptionalObject(
+                    OpenApiConstants.UnevaluatedProperties,
+                    UnevaluatedPropertiesSchema,
+                    (w, s) => s.SerializeAsV31(w));
+            }
+            else if (!UnevaluatedProperties)
+            {
+                writer.WriteProperty(OpenApiConstants.UnevaluatedProperties, UnevaluatedProperties);
+            }
+            // true is the default, no need to write it out
             writer.WriteOptionalCollection(OpenApiConstants.Examples, Examples, (nodeWriter, s) => nodeWriter.WriteAny(s));
             writer.WriteOptionalMap(OpenApiConstants.PatternProperties, PatternProperties, (w, s) => s.SerializeAsV31(w));
             writer.WriteOptionalMap(OpenApiConstants.DependentRequired, DependentRequired, (w, s) => w.WriteValue(s));

src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs

@@ -10,7 +10,7 @@ namespace Microsoft.OpenApi
     /// <summary>
     /// Schema reference object
     /// </summary>
-    public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema, IOpenApiSchema, JsonSchemaReference>, IOpenApiSchema
+    public class OpenApiSchemaReference : BaseOpenApiReferenceHolder<OpenApiSchema, IOpenApiSchema, JsonSchemaReference>, IOpenApiSchema, IOpenApiSchemaWithUnevaluatedProperties
     {
 
         /// <summary>
@@ -146,6 +146,8 @@ public IList<JsonNode>? Examples
         /// <inheritdoc/>
         public bool UnevaluatedProperties { get => Target?.UnevaluatedProperties ?? false; }
         /// <inheritdoc/>
+        public IOpenApiSchema? UnevaluatedPropertiesSchema { get => (Target as IOpenApiSchemaWithUnevaluatedProperties)?.UnevaluatedPropertiesSchema; }
+        /// <inheritdoc/>
         public OpenApiExternalDocs? ExternalDocs { get => Target?.ExternalDocs; }
         /// <inheritdoc/>
         public bool Deprecated

src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs

@@ -146,12 +146,22 @@ internal static partial class OpenApiV31Deserializer
         },
         {
             "unevaluatedProperties",
-            (o, n, _) =>
+            (o, n, t) =>
             {
-                var unevaluatedProps = n.GetScalarValue();
-                if (unevaluatedProps != null)
+                // Handle both boolean (false/true) and schema object cases
+                var scalarValue = n.GetScalarValue();
+                if (scalarValue != null)
+                {
+                    // Boolean case: false means no unevaluated properties, true is default (ignore)
+                    if (bool.TryParse(scalarValue, out var boolValue))
+                    {
+                        o.UnevaluatedProperties = boolValue;
+                    }
+                }
+                else
                 {
-                    o.UnevaluatedProperties = bool.Parse(unevaluatedProps);
+                    // Schema object case: deserialize as schema
+                    o.UnevaluatedPropertiesSchema = LoadSchema(n, t);
                 }
             }
         },