Implement media type component deserialization for OAS 3.2

Co-authored-by: baywet <[email protected]>

Author: Copilot

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -617,16 +617,14 @@ private static string ConvertByteArrayToString(byte[] hash)
 
             string uriLocation;
             var id = reference.Id;
-            if (!string.IsNullOrEmpty(id) && id!.Contains('/')) // this means its a URL reference
-            {
-                uriLocation = id!;
-            }
-            else
+            var referenceV3 = !string.IsNullOrEmpty(reference.ReferenceV3) ? reference.ReferenceV3! : string.Empty;
+            
+            // Check if we have a full reference path first
+            if (!string.IsNullOrEmpty(referenceV3))
             {
                 string relativePath;
-                var referenceV3 = !string.IsNullOrEmpty(reference.ReferenceV3) ? reference.ReferenceV3! : string.Empty;
-
-                if (!string.IsNullOrEmpty(referenceV3) && IsSubComponent(referenceV3))
+                
+                if (IsSubComponent(referenceV3))
                 {
                     // Enables setting the complete JSON path for nested subschemas e.g. #/components/schemas/person/properties/address
                     if (useExternal)
@@ -641,7 +639,8 @@ private static string ConvertByteArrayToString(byte[] hash)
                 }
                 else
                 {
-                    relativePath = $"#{OpenApiConstants.ComponentsSegment}{reference.Type.GetDisplayName()}/{id}";
+                    // Use the full reference path as-is (e.g., #/components/mediaTypes/application~1json)
+                    relativePath = referenceV3;
                 }
 
                 Uri? externalResourceUri = useExternal ? Workspace?.GetDocumentId(reference.ExternalResource) : null;
@@ -650,6 +649,21 @@ private static string ConvertByteArrayToString(byte[] hash)
                     ? externalResourceUri.AbsoluteUri + relativePath
                     : BaseUri + relativePath;
             }
+            else if (!string.IsNullOrEmpty(id) && id!.Contains('/')) // this means its a URL reference
+            {
+                uriLocation = id!;
+            }
+            else
+            {
+                // Fallback: construct path from type and id
+                string relativePath = $"#{OpenApiConstants.ComponentsSegment}{reference.Type.GetDisplayName()}/{id}";
+
+                Uri? externalResourceUri = useExternal ? Workspace?.GetDocumentId(reference.ExternalResource) : null;
+
+                uriLocation = useExternal && externalResourceUri is not null
+                    ? externalResourceUri.AbsoluteUri + relativePath
+                    : BaseUri + relativePath;
+            }
 
             var absoluteUri =
 #if NETSTANDARD2_1 || NETCOREAPP || NET5_0_OR_GREATER

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

@@ -22,7 +22,8 @@ internal static partial class OpenApiV32Deserializer
         {"securitySchemes", (o, n, t) => o.SecuritySchemes = n.CreateMap(LoadSecurityScheme, t)},
         {"links", (o, n, t) => o.Links = n.CreateMap(LoadLink, t)},
         {"callbacks", (o, n, t) => o.Callbacks = n.CreateMap(LoadCallback, t)},
-        {"pathItems", (o, n, t) => o.PathItems = n.CreateMap(LoadPathItem, t)}
+        {"pathItems", (o, n, t) => o.PathItems = n.CreateMap(LoadPathItem, t)},
+        {"mediaTypes", (o, n, t) => o.MediaTypes = n.CreateMap(LoadMediaType, t)}
     };
 
         private static readonly PatternFieldMap<OpenApiComponents> _componentsPatternFields =

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

@@ -90,6 +90,16 @@ public static IOpenApiMediaType LoadMediaType(ParseNode node, OpenApiDocument ho
         {
             var mapNode = node.CheckMapNode(OpenApiConstants.Content);
 
+            var pointer = mapNode.GetReferencePointer();
+            if (pointer != null)
+            {
+                var reference = GetReferenceIdAndExternalResource(pointer);
+                var mediaTypeReference = new OpenApiMediaTypeReference(reference.Item1, hostDocument, reference.Item2);
+                mediaTypeReference.Reference.SetMetadataFromMapNode(mapNode);
+                mediaTypeReference.Reference.SetJsonPointerPath(pointer, node.Context.GetLocation());
+                return mediaTypeReference;
+            }
+
             var mediaType = new OpenApiMediaType();
 
             ParseMap(mapNode, mediaType, _mediaTypeFixedFields, _mediaTypePatternFields, hostDocument);

src/Microsoft.OpenApi/Services/OpenApiWalker.cs

@@ -800,7 +800,7 @@ internal void Walk(IDictionary<string, IOpenApiMediaType>? content)
                 }
 
                 _visitor.CurrentKeys.Content = mediaType.Key;
-                WalkItem(mediaType.Key, mediaType.Value, static (self, item) => self.Walk(item));
+                WalkItem(mediaType.Key, mediaType.Value, static (self, item, isComponent) => self.Walk(item, isComponent), isComponent: false);
                 _visitor.CurrentKeys.Content = null;
             }
         }

src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

@@ -193,7 +193,9 @@ public void RegisterComponents(OpenApiDocument document)
             {
                 foreach (var item in document.Components.MediaTypes)
                 {
-                    location = baseUri + ReferenceType.MediaType.GetDisplayName() + ComponentSegmentSeparator + item.Key;
+                    // Encode the key to match JSON Pointer encoding used in references
+                    var encodedKey = item.Key.Replace("~", "~0").Replace("/", "~1");
+                    location = baseUri + ReferenceType.MediaType.GetDisplayName() + ComponentSegmentSeparator + encodedKey;
                     RegisterComponent(location, item.Value);
                 }
             }
@@ -235,7 +237,7 @@ public bool RegisterComponentForDocument<T>(OpenApiDocument openApiDocument, T c
                 IOpenApiExample => baseUri + ReferenceType.Example.GetDisplayName() + ComponentSegmentSeparator + id,
                 IOpenApiHeader => baseUri + ReferenceType.Header.GetDisplayName() + ComponentSegmentSeparator + id,
                 IOpenApiSecurityScheme => baseUri + ReferenceType.SecurityScheme.GetDisplayName() + ComponentSegmentSeparator + id,
-                IOpenApiMediaType => baseUri + ReferenceType.MediaType.GetDisplayName() + ComponentSegmentSeparator + id,
+                IOpenApiMediaType => baseUri + ReferenceType.MediaType.GetDisplayName() + ComponentSegmentSeparator + id.Replace("~", "~0").Replace("/", "~1"),
                 _ => throw new ArgumentException($"Invalid component type {componentToRegister!.GetType().Name}"),
             };
 

test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiMediaTypeReferenceDeserializerTests.cs

@@ -7,12 +7,8 @@
 
 namespace Microsoft.OpenApi.Readers.Tests.V32Tests;
 
-// NOTE: These tests are currently disabled because media type reference deserialization 
-// support needs to be implemented in the parser. The tests are kept here as a specification
-// of the expected behavior once parser support is added.
 public class OpenApiMediaTypeReferenceDeserializerTests
 {
-    /*
     [Fact]
     public void ShouldDeserializeMediaTypeReferenceInRequestBodyContent()
     {
@@ -280,5 +276,4 @@ public void ShouldDeserializeMediaTypeReferenceInHeaderContent()
         Assert.NotNull(mediaTypeRef.Schema);
         Assert.Equal(JsonSchemaType.Array, mediaTypeRef.Schema.Type);
     }
-    */
 }