Merge branch 'main' into pr/2706

Author: mdaneri

.github/copilot-instructions.md

@@ -0,0 +1,63 @@
+# Copilot Instructions
+
+## Commit Message Format
+
+Always use conventional commits format when creating commits. Follow this structure:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
+- **refactor**: A code change that neither fixes a bug nor adds a feature
+- **perf**: A code change that improves performance
+- **test**: Adding missing tests or correcting existing tests
+- **build**: Changes that affect the build system or external dependencies
+- **ci**: Changes to CI configuration files and scripts
+- **chore**: Other changes that don't modify src or test files
+
+### Scope
+
+The scope should indicate the package or area affected (e.g., `library`, `yaml-reader`, `hidi`).
+
+### Examples
+
+```
+feat(library): add support for pattern properties
+fix(yaml-reader): updates boolean serialization
+docs(README): update installation instructions
+ci(release): configure automated release workflow
+```
+
+### Breaking Changes
+
+If a commit introduces a breaking change, add `BREAKING CHANGE:` in the footer or append `!` after the type/scope:
+
+```
+feat(identity-emitter)!: change output format for models
+
+BREAKING CHANGE: The emitter now generates TypeScript interfaces instead of types
+```
+
+
+## Updating the benchmark information
+
+The user might request you update the benchmark information. You might do it on your own if a previous change added new properties to models under **src/Microsoft.OpenApi/Models**. Always use a separate commit for this change.
+
+To do so, run the following script:
+
+```shell
+cd performance/benchmark
+dotnet run -c Release
+```
+
+Then commit the report files using a "chore" commit.

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);
                 }
             }
         },