Add itemEncoding and prefixEncoding fields with serialization/deserialization support

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

Author: Copilot

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -320,6 +320,16 @@ public static class OpenApiConstants
         /// </summary>
         public const string Encoding = "encoding";
 
+        /// <summary>
+        /// Field: ItemEncoding
+        /// </summary>
+        public const string ItemEncoding = "itemEncoding";
+
+        /// <summary>
+        /// Field: PrefixEncoding
+        /// </summary>
+        public const string PrefixEncoding = "prefixEncoding";
+
         /// <summary>
         /// Field: RequestBodies
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiMediaType.cs

@@ -38,6 +38,18 @@ public class OpenApiMediaType : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public IDictionary<string, OpenApiEncoding>? Encoding { get; set; }
 
+        /// <summary>
+        /// An encoding object for items in an array schema.
+        /// Only applies when the schema is of type array.
+        /// </summary>
+        public OpenApiEncoding? ItemEncoding { get; set; }
+
+        /// <summary>
+        /// An array of encoding objects for prefixItems in an array schema.
+        /// Each element corresponds to a prefixItem in the schema.
+        /// </summary>
+        public IList<OpenApiEncoding>? PrefixEncoding { get; set; }
+
         /// <summary>
         /// Serialize <see cref="OpenApiExternalDocs"/> to Open Api v3.0.
         /// </summary>
@@ -57,6 +69,8 @@ public OpenApiMediaType(OpenApiMediaType? mediaType)
             Example = mediaType?.Example != null ? JsonNodeCloneHelper.Clone(mediaType.Example) : null;
             Examples = mediaType?.Examples != null ? new Dictionary<string, IOpenApiExample>(mediaType.Examples) : null;
             Encoding = mediaType?.Encoding != null ? new Dictionary<string, OpenApiEncoding>(mediaType.Encoding) : null;
+            ItemEncoding = mediaType?.ItemEncoding != null ? new OpenApiEncoding(mediaType.ItemEncoding) : null;
+            PrefixEncoding = mediaType?.PrefixEncoding != null ? new List<OpenApiEncoding>(mediaType.PrefixEncoding.Select(e => new OpenApiEncoding(e))) : null;
             Extensions = mediaType?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(mediaType.Extensions) : null;
         }
 
@@ -108,6 +122,32 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // encoding
             writer.WriteOptionalMap(OpenApiConstants.Encoding, Encoding, callback);
 
+            // itemEncoding - serialize as native field in v3.2+, as extension in earlier versions
+            if (ItemEncoding != null)
+            {
+                if (version >= OpenApiSpecVersion.OpenApi3_2)
+                {
+                    writer.WriteOptionalObject(OpenApiConstants.ItemEncoding, ItemEncoding, callback);
+                }
+                else
+                {
+                    writer.WriteOptionalObject(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.ItemEncoding, ItemEncoding, callback);
+                }
+            }
+
+            // prefixEncoding - serialize as native field in v3.2+, as extension in earlier versions
+            if (PrefixEncoding != null)
+            {
+                if (version >= OpenApiSpecVersion.OpenApi3_2)
+                {
+                    writer.WriteOptionalCollection(OpenApiConstants.PrefixEncoding, PrefixEncoding, callback);
+                }
+                else
+                {
+                    writer.WriteOptionalCollection(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.PrefixEncoding, PrefixEncoding, callback);
+                }
+            }
+
             // extensions
             writer.WriteExtensions(Extensions, version);
 

src/Microsoft.OpenApi/Reader/V3/OpenApiMediaTypeDeserializer.cs

@@ -30,6 +30,14 @@ internal static partial class OpenApiV3Deserializer
                     OpenApiConstants.Encoding,
                     (o, n, t) => o.Encoding = n.CreateMap(LoadEncoding, t)
                 },
+                {
+                    OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.ItemEncoding,
+                    (o, n, t) => o.ItemEncoding = LoadEncoding(n, t)
+                },
+                {
+                    OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.PrefixEncoding,
+                    (o, n, t) => o.PrefixEncoding = n.CreateList(LoadEncoding, t)
+                },
             };
 
         private static readonly PatternFieldMap<OpenApiMediaType> _mediaTypePatternFields =

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

@@ -35,6 +35,18 @@ internal static partial class OpenApiV31Deserializer
                         o.Encoding = n.CreateMap(LoadEncoding, t);
                     }
                 },
+                {
+                    OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.ItemEncoding, (o, n, t) =>
+                    {
+                        o.ItemEncoding = LoadEncoding(n, t);
+                    }
+                },
+                {
+                    OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.PrefixEncoding, (o, n, t) =>
+                    {
+                        o.PrefixEncoding = n.CreateList(LoadEncoding, t);
+                    }
+                },
             };
 
         private static readonly PatternFieldMap<OpenApiMediaType> _mediaTypePatternFields =

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

@@ -35,6 +35,18 @@ internal static partial class OpenApiV32Deserializer
                         o.Encoding = n.CreateMap(LoadEncoding, t);
                     }
                 },
+                {
+                    OpenApiConstants.ItemEncoding, (o, n, t) =>
+                    {
+                        o.ItemEncoding = LoadEncoding(n, t);
+                    }
+                },
+                {
+                    OpenApiConstants.PrefixEncoding, (o, n, t) =>
+                    {
+                        o.PrefixEncoding = n.CreateList(LoadEncoding, t);
+                    }
+                },
             };
 
         private static readonly PatternFieldMap<OpenApiMediaType> _mediaTypePatternFields =

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

@@ -73,6 +73,24 @@ public class OpenApiMediaTypeTests
             }
         };
 
+        public static OpenApiMediaType MediaTypeWithItemEncoding = new()
+        {
+            ItemEncoding = OpenApiEncodingTests.AdvanceEncoding
+        };
+
+        public static OpenApiMediaType MediaTypeWithPrefixEncoding = new()
+        {
+            PrefixEncoding = new List<OpenApiEncoding>
+            {
+                OpenApiEncodingTests.AdvanceEncoding,
+                new OpenApiEncoding
+                {
+                    ContentType = "application/json",
+                    Style = ParameterStyle.Simple
+                }
+            }
+        };
+
         public static OpenApiMediaType MediaTypeWithObjectExamples = new()
         {
             Examples = new Dictionary<string, IOpenApiExample>
@@ -443,5 +461,117 @@ public void MediaTypeCopyConstructorWorks()
             Assert.Empty(clone.Extensions);
             Assert.Null(MediaTypeWithObjectExamples.Example);
         }
+
+        [Fact]
+        public async Task SerializeMediaTypeWithItemEncodingAsV32JsonWorks()
+        {
+            // Arrange
+            var expected =
+                """
+                {
+                  "itemEncoding": {
+                    "contentType": "image/png, image/jpeg",
+                    "style": "simple",
+                    "explode": true,
+                    "allowReserved": true
+                  }
+                }
+                """;
+
+            // Act
+            var actual = await MediaTypeWithItemEncoding.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_2);
+
+            // Assert
+            actual = actual.MakeLineBreaksEnvironmentNeutral();
+            expected = expected.MakeLineBreaksEnvironmentNeutral();
+            Assert.Equal(expected, actual);
+        }
+
+        [Fact]
+        public async Task SerializeMediaTypeWithItemEncodingAsV31JsonWorks()
+        {
+            // Arrange
+            var expected =
+                """
+                {
+                  "x-oai-itemEncoding": {
+                    "contentType": "image/png, image/jpeg",
+                    "style": "simple",
+                    "explode": true,
+                    "allowReserved": true
+                  }
+                }
+                """;
+
+            // Act
+            var actual = await MediaTypeWithItemEncoding.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_1);
+
+            // Assert
+            actual = actual.MakeLineBreaksEnvironmentNeutral();
+            expected = expected.MakeLineBreaksEnvironmentNeutral();
+            Assert.Equal(expected, actual);
+        }
+
+        [Fact]
+        public async Task SerializeMediaTypeWithPrefixEncodingAsV32JsonWorks()
+        {
+            // Arrange
+            var expected =
+                """
+                {
+                  "prefixEncoding": [
+                    {
+                      "contentType": "image/png, image/jpeg",
+                      "style": "simple",
+                      "explode": true,
+                      "allowReserved": true
+                    },
+                    {
+                      "contentType": "application/json",
+                      "style": "simple"
+                    }
+                  ]
+                }
+                """;
+
+            // Act
+            var actual = await MediaTypeWithPrefixEncoding.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_2);
+
+            // Assert
+            actual = actual.MakeLineBreaksEnvironmentNeutral();
+            expected = expected.MakeLineBreaksEnvironmentNeutral();
+            Assert.Equal(expected, actual);
+        }
+
+        [Fact]
+        public async Task SerializeMediaTypeWithPrefixEncodingAsV31JsonWorks()
+        {
+            // Arrange
+            var expected =
+                """
+                {
+                  "x-oai-prefixEncoding": [
+                    {
+                      "contentType": "image/png, image/jpeg",
+                      "style": "simple",
+                      "explode": true,
+                      "allowReserved": true
+                    },
+                    {
+                      "contentType": "application/json",
+                      "style": "simple"
+                    }
+                  ]
+                }
+                """;
+
+            // Act
+            var actual = await MediaTypeWithPrefixEncoding.SerializeAsJsonAsync(OpenApiSpecVersion.OpenApi3_1);
+
+            // Assert
+            actual = actual.MakeLineBreaksEnvironmentNeutral();
+            expected = expected.MakeLineBreaksEnvironmentNeutral();
+            Assert.Equal(expected, actual);
+        }
     }
 }