fix: implement unevaluatedProperties as schema per JSON Schema 2020-12

global.json

@@ -1,5 +1,5 @@
 {
   "sdk": {
-    "version": "8.0.418"
+    "version": "8.0.417"
   }
 }

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; }
@@ -232,7 +232,10 @@ public string? Minimum
         public IList<JsonNode>? Enum { get; set; }
 
         /// <inheritdoc />
-        public bool UnevaluatedProperties { get; set; }
+        public bool UnevaluatedProperties { get; set; } = true;
+
+        /// <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>
@@ -144,7 +144,9 @@ public IList<JsonNode>? Examples
         /// <inheritdoc/>
         public IList<JsonNode>? Enum { get => Target?.Enum; }
         /// <inheritdoc/>
-        public bool UnevaluatedProperties { get => Target?.UnevaluatedProperties ?? false; }
+        public bool UnevaluatedProperties { get => Target?.UnevaluatedProperties ?? true; }
+        /// <inheritdoc/>
+        public IOpenApiSchema? UnevaluatedPropertiesSchema { get => (Target as IOpenApiSchemaWithUnevaluatedProperties)?.UnevaluatedPropertiesSchema; }
         /// <inheritdoc/>
         public OpenApiExternalDocs? ExternalDocs { get => Target?.ExternalDocs; }
         /// <inheritdoc/>

src/Microsoft.OpenApi/PublicAPI.Unshipped.txt

@@ -1 +1,6 @@
 #nullable enable
+Microsoft.OpenApi.IOpenApiSchemaWithUnevaluatedProperties
+Microsoft.OpenApi.IOpenApiSchemaWithUnevaluatedProperties.UnevaluatedPropertiesSchema.get -> Microsoft.OpenApi.IOpenApiSchema?
+Microsoft.OpenApi.OpenApiSchema.UnevaluatedPropertiesSchema.get -> Microsoft.OpenApi.IOpenApiSchema?
+Microsoft.OpenApi.OpenApiSchema.UnevaluatedPropertiesSchema.set -> void
+Microsoft.OpenApi.OpenApiSchemaReference.UnevaluatedPropertiesSchema.get -> Microsoft.OpenApi.IOpenApiSchema?

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

@@ -146,12 +146,21 @@ 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
+                if (n is ValueNode)
+                {
+                    var value = n.GetScalarValue();
+                    if (value is not null)
+                    {
+                        o.UnevaluatedProperties = bool.Parse(value);
+                    }
+                }
+                else
                 {
-                    o.UnevaluatedProperties = bool.Parse(unevaluatedProps);
+                    // Schema object case: deserialize as schema
+                    o.UnevaluatedPropertiesSchema = LoadSchema(n, t);
                 }
             }
         },

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSchemaTests.cs

@@ -707,5 +707,113 @@ public void ReturnSingleIdentifierWorks()
             Assert.Equal("integer", type.ToSingleIdentifier());
             Assert.Throws<InvalidOperationException>(() => types.ToSingleIdentifier());
         }
+
+        // UnevaluatedProperties deserialization tests
+        [Fact]
+        public void ParseSchemaWithUnevaluatedPropertiesBooleanFalse()
+        {
+            // Arrange
+            var schema = @"{
+  ""type"": ""object"",
+  ""unevaluatedProperties"": false
+}";
+
+            var expected = new OpenApiSchema()
+            {
+                Type = JsonSchemaType.Object,
+                UnevaluatedProperties = false
+            };
+
+            // Act
+            var actual = OpenApiModelFactory.Parse<OpenApiSchema>(schema, OpenApiSpecVersion.OpenApi3_1, new(), out _);
+
+            // Assert
+            Assert.Equivalent(expected, actual);
+        }
+
+        [Fact]
+        public void ParseSchemaWithUnevaluatedPropertiesBooleanTrue()
+        {
+            // Arrange - true should be parsed but is the default, effectively a no-op
+            var schema = @"{
+  ""type"": ""object"",
+  ""unevaluatedProperties"": true
+}";
+
+            var expected = new OpenApiSchema()
+            {
+                Type = JsonSchemaType.Object,
+                UnevaluatedProperties = true
+            };
+
+            // Act
+            var actual = OpenApiModelFactory.Parse<OpenApiSchema>(schema, OpenApiSpecVersion.OpenApi3_1, new(), out _);
+
+            // Assert
+            Assert.Equivalent(expected, actual);
+        }
+
+        [Fact]
+        public void ParseSchemaWithUnevaluatedPropertiesSchema()
+        {
+            // Arrange
+            var schema = @"{
+  ""type"": ""object"",
+  ""unevaluatedProperties"": {
+    ""type"": ""string""
+  }
+}";
+
+            var expected = new OpenApiSchema()
+            {
+                Type = JsonSchemaType.Object,
+                UnevaluatedPropertiesSchema = new OpenApiSchema
+                {
+                    Type = JsonSchemaType.String
+                }
+            };
+
+            // Act
+            var actual = OpenApiModelFactory.Parse<OpenApiSchema>(schema, OpenApiSpecVersion.OpenApi3_1, new(), out _);
+
+            // Assert
+            Assert.Equivalent(expected, actual);
+        }
+
+        [Fact]
+        public void ParseSchemaWithUnevaluatedPropertiesComplexSchema()
+        {
+            // Arrange
+            var schema = @"{
+  ""type"": ""object"",
+  ""properties"": {
+    ""name"": { ""type"": ""string"" }
+  },
+  ""unevaluatedProperties"": {
+    ""type"": ""number"",
+    ""minimum"": ""0""
+  }
+}";
+
+            var expected = new OpenApiSchema()
+            {
+                Type = JsonSchemaType.Object,
+                Properties = new Dictionary<string, IOpenApiSchema>
+                {
+                    ["name"] = new OpenApiSchema { Type = JsonSchemaType.String }
+                },
+                UnevaluatedPropertiesSchema = new OpenApiSchema
+                {
+                    Type = JsonSchemaType.Number,
+                    Minimum = "0"
+                }
+            };
+
+            // Act
+            var actual = OpenApiModelFactory.Parse<OpenApiSchema>(schema, OpenApiSpecVersion.OpenApi3_1, new(), out _);
+
+            // Assert
+            Assert.Equivalent(expected, actual);
+        }
     }
 }