Serialize patternProperties for OpenAPI v3.0

Adds support for patternProperties when serializing OpenApiSchema for OpenAPI 3.0 by emitting an extension and a fallback additionalProperties value. Introduces a new constant x-jsonSchema-patternProperties in OpenApiConstants, updates OpenApiSchema.SerializeInternal to write the extension for v3.0 and to derive additionalProperties fallback: if all pattern property schemas are identical the common schema is emitted, otherwise additionalProperties: true is emitted. Implements helper methods to compare serialized schemas (SerializeSchemaToComparableJsonNode and TryGetPatternPropertiesFallbackSchema) and adds necessary usings. Adds unit tests covering v3.0 extension + schema fallback, v3.0 extension + true fallback when schemas differ, and that v3.1 still uses the standard patternProperties keyword.

Author: mdaneri

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

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

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -3,6 +3,8 @@
 
 using System;
 using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
 using System.Linq;
 using System.Text.Json;
 using System.Text.Json.Nodes;
@@ -493,6 +495,13 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // properties
             writer.WriteOptionalMap(OpenApiConstants.Properties, Properties, callback);
 
+            var hasPatternPropertiesForV30 = version == OpenApiSpecVersion.OpenApi3_0 && PatternProperties is { Count: > 0 };
+
+            if (hasPatternPropertiesForV30)
+            {
+                writer.WriteOptionalMap(OpenApiConstants.PatternPropertiesExtension, PatternProperties, callback);
+            }
+
             // additionalProperties
             if (AdditionalProperties is not null && version >= OpenApiSpecVersion.OpenApi3_0)
             {
@@ -501,6 +510,20 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
                     AdditionalProperties,
                     callback);
             }
+            else if (hasPatternPropertiesForV30)
+            {
+                if (TryGetPatternPropertiesFallbackSchema(out var fallbackSchema) && fallbackSchema is not null)
+                {
+                    writer.WriteOptionalObject(
+                        OpenApiConstants.AdditionalProperties,
+                        fallbackSchema,
+                        callback);
+                }
+                else
+                {
+                    writer.WriteProperty(OpenApiConstants.AdditionalProperties, true);
+                }
+            }
             // true is the default, no need to write it out
             else if (!AdditionalPropertiesAllowed)
             {
@@ -611,6 +634,54 @@ internal void WriteJsonSchemaKeywords(IOpenApiWriter writer)
             writer.WriteOptionalMap(OpenApiConstants.DependentRequired, DependentRequired, (w, s) => w.WriteValue(s));
         }
 
+        private bool TryGetPatternPropertiesFallbackSchema(out IOpenApiSchema? fallbackSchema)
+        {
+            fallbackSchema = null;
+            if (PatternProperties is not { Count: > 0 })
+            {
+                return false;
+            }
+
+            fallbackSchema = PatternProperties.First().Value;
+            if (PatternProperties.Count == 1)
+            {
+                return fallbackSchema is not null;
+            }
+
+            var baselineNode = SerializeSchemaToComparableJsonNode(fallbackSchema);
+            if (baselineNode is null)
+            {
+                fallbackSchema = null;
+                return false;
+            }
+
+            foreach (var schema in PatternProperties.Skip(1).Select(static x => x.Value))
+            {
+                var schemaNode = SerializeSchemaToComparableJsonNode(schema);
+                if (schemaNode is null || !JsonNode.DeepEquals(baselineNode, schemaNode))
+                {
+                    fallbackSchema = null;
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        private static JsonNode? SerializeSchemaToComparableJsonNode(IOpenApiSchema schema)
+        {
+            if (schema is not IOpenApiSerializable serializableSchema)
+            {
+                return null;
+            }
+
+            using var stringWriter = new StringWriter(CultureInfo.InvariantCulture);
+            var jsonWriter = new OpenApiJsonWriter(stringWriter, new OpenApiJsonWriterSettings { Terse = true });
+            serializableSchema.SerializeAsV31(jsonWriter);
+
+            return JsonNode.Parse(stringWriter.ToString());
+        }
+
         internal void WriteAsItemsProperties(IOpenApiWriter writer)
         {
             // type

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.cs

@@ -828,6 +828,128 @@ public async Task SerializeAdditionalPropertiesAsV3PlusEmits(OpenApiSpecVersion
             Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
         }
 
+        [Fact]
+        public async Task SerializePatternPropertiesAsV3EmitsExtensionAndSchemaFallback()
+        {
+            // Given
+            var schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.Object,
+                AdditionalPropertiesAllowed = false,
+                PatternProperties = new Dictionary<string, IOpenApiSchema>
+                {
+                    ["^[a-z][a-z0-9_]*$"] = new OpenApiSchema
+                    {
+                        Type = JsonSchemaType.Integer,
+                        Format = "int32"
+                    }
+                }
+            };
+
+            var expected =
+                """
+                {
+                  "type": "object",
+                  "x-jsonSchema-patternProperties": {
+                    "^[a-z][a-z0-9_]*$": {
+                      "type": "integer",
+                      "format": "int32"
+                    }
+                  },
+                  "additionalProperties": {
+                    "type": "integer",
+                    "format": "int32"
+                  }
+                }
+                """;
+
+            // When
+            var actual = await schema.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_0);
+
+            // Then
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
+        }
+
+        [Fact]
+        public async Task SerializePatternPropertiesAsV3EmitsExtensionAndTrueFallbackWhenSchemasDiffer()
+        {
+            // Given
+            var schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.Object,
+                PatternProperties = new Dictionary<string, IOpenApiSchema>
+                {
+                    ["^[a-z]+$"] = new OpenApiSchema
+                    {
+                        Type = JsonSchemaType.String
+                    },
+                    ["^[0-9]+$"] = new OpenApiSchema
+                    {
+                        Type = JsonSchemaType.Integer,
+                        Format = "int32"
+                    }
+                }
+            };
+
+            var expected =
+                """
+                {
+                  "type": "object",
+                  "x-jsonSchema-patternProperties": {
+                    "^[a-z]+$": {
+                      "type": "string"
+                    },
+                    "^[0-9]+$": {
+                      "type": "integer",
+                      "format": "int32"
+                    }
+                  },
+                  "additionalProperties": true
+                }
+                """;
+
+            // When
+            var actual = await schema.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_0);
+
+            // Then
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
+        }
+
+        [Fact]
+        public async Task SerializePatternPropertiesAsV31RemainsStandardKeyword()
+        {
+            // Given
+            var schema = new OpenApiSchema
+            {
+                Type = JsonSchemaType.Object,
+                PatternProperties = new Dictionary<string, IOpenApiSchema>
+                {
+                    ["^[a-z]+$"] = new OpenApiSchema
+                    {
+                        Type = JsonSchemaType.String
+                    }
+                }
+            };
+
+            var expected =
+                """
+                {
+                  "type": "object",
+                  "patternProperties": {
+                    "^[a-z]+$": {
+                      "type": "string"
+                    }
+                  }
+                }
+                """;
+
+            // When
+            var actual = await schema.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_1);
+
+            // Then
+            Assert.True(JsonNode.DeepEquals(JsonNode.Parse(expected), JsonNode.Parse(actual)));
+        }
+
         [Fact]
         public async Task SerializeOneOfWithNullAsV3ShouldUseNullableAsync()
         {