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/OpenApiConstants.cs

@@ -130,6 +130,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string UnevaluatedProperties = "unevaluatedProperties";
 
+        /// <summary>
+        /// Extension: x-jsonschema-unevaluatedProperties
+        /// </summary>
+        public const string UnevaluatedPropertiesExtension = "x-jsonschema-unevaluatedProperties";
+
         /// <summary>
         /// Field: Version
         /// </summary>

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 { UnevaluatedPropertiesSchema: { } unevaluatedSchema })
+            {
+                UnevaluatedPropertiesSchema = unevaluatedSchema.CreateShallowCopy();
+            }
             ExclusiveMaximum = schema.ExclusiveMaximum ?? ExclusiveMaximum;
             ExclusiveMinimum = schema.ExclusiveMinimum ?? ExclusiveMinimum;
             if (schema is OpenApiSchema eMSchema)
@@ -537,9 +544,29 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // deprecated
             writer.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
 
+            // For versions < 3.1, write unevaluatedProperties as an extension
+            if (version < OpenApiSpecVersion.OpenApi3_1)
+            {
+                // Write UnevaluatedPropertiesSchema as extension if present
+                if (UnevaluatedPropertiesSchema is not null)
+                {
+                    writer.WriteOptionalObject(
+                        OpenApiConstants.UnevaluatedPropertiesExtension,
+                        UnevaluatedPropertiesSchema,
+                        callback);
+                }
+                // Write boolean false as extension if explicitly set to false
+                else if (!UnevaluatedProperties)
+                {
+                    writer.WritePropertyName(OpenApiConstants.UnevaluatedPropertiesExtension);
+                    writer.WriteValue(false);
+                }
+            }
+
             // extensions
             writer.WriteExtensions(Extensions, version);
 
+
             // Unrecognized keywords
             if (UnrecognizedKeywords is not null && UnrecognizedKeywords.Any())
             {
@@ -565,7 +592,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));
@@ -780,6 +820,21 @@ private void SerializeAsV2(
             // x-nullable extension
             SerializeNullable(writer, OpenApiSpecVersion.OpenApi2_0);
 
+            // Write UnevaluatedPropertiesSchema as extension if present
+            if (UnevaluatedPropertiesSchema is not null)
+            {
+                writer.WriteOptionalObject(
+                    OpenApiConstants.UnevaluatedPropertiesExtension,
+                    UnevaluatedPropertiesSchema,
+                    (w, s) => s.SerializeAsV2(w));
+            }
+            // Write boolean false as extension if explicitly set to false
+            else if (!UnevaluatedProperties)
+            {
+                writer.WritePropertyName(OpenApiConstants.UnevaluatedPropertiesExtension);
+                writer.WriteValue(false);
+            }
+
             // extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
 

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,7 @@
 #nullable enable
+const Microsoft.OpenApi.OpenApiConstants.UnevaluatedPropertiesExtension = "x-jsonschema-unevaluatedProperties" -> string!
+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);
                 }
             }
         },

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

@@ -146,12 +146,21 @@ internal static partial class OpenApiV32Deserializer
         },
         {
             "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,142 @@ 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);
+        }
+
+        [Fact]
+        public void ParseSchemaWithoutUnevaluatedPropertiesDefaultsToTrue()
+        {
+            // Arrange - no unevaluatedProperties property should default to true (allow all)
+            var schema = @"{
+  ""type"": ""object"",
+  ""properties"": {
+    ""name"": { ""type"": ""string"" }
+  }
+}";
+
+            var expected = new OpenApiSchema()
+            {
+                Type = JsonSchemaType.Object,
+                Properties = new Dictionary<string, IOpenApiSchema>
+                {
+                    ["name"] = new OpenApiSchema { Type = JsonSchemaType.String }
+                },
+                UnevaluatedProperties = true // Default value
+            };
+
+            // Act
+            var actual = OpenApiModelFactory.Parse<OpenApiSchema>(schema, OpenApiSpecVersion.OpenApi3_1, new(), out _);
+
+            // Assert
+            Assert.Equivalent(expected, actual);
+            Assert.True(actual.UnevaluatedProperties); // Explicitly verify the default
+        }
     }
 }