Handle binary formats for pre-3.1

Author: Youssef1313

global.json

@@ -1,5 +1,5 @@
 {
   "sdk": {
-    "version": "10.0.302"
+    "version": "10.0.301"
   }
 }

src/Microsoft.OpenApi/Models/OpenApiRequestBody.cs

@@ -130,26 +130,7 @@ public IEnumerable<IOpenApiParameter> ConvertToFormDataParameters(IOpenApiWriter
             {
                 foreach (var property in properties)
                 {
-                    var paramSchema = property.Value.CreateShallowCopy();
-                    if ((paramSchema.Type & JsonSchemaType.String) == JsonSchemaType.String
-                        && ("binary".Equals(paramSchema.Format, StringComparison.OrdinalIgnoreCase)
-                        || "base64".Equals(paramSchema.Format, StringComparison.OrdinalIgnoreCase)))
-                    {
-                        var updatedSchema = paramSchema switch
-                        {
-                            OpenApiSchema s => s, // we already have a copy
-                                                  // we have a copy of a reference but don't want to mutate the source schema
-                                                  // TODO might need recursive resolution of references here
-                            OpenApiSchemaReference r when r.Target is not null => (OpenApiSchema)r.Target.CreateShallowCopy(),
-                            OpenApiSchemaReference => throw new InvalidOperationException("Unresolved reference target"),
-                            _ => throw new InvalidOperationException("Unexpected schema type")
-                        };
-                        
-                        updatedSchema.Type = "file".ToJsonSchemaType();
-                        updatedSchema.Format = null;
-                        paramSchema = updatedSchema;
-                        
-                    }
+                    var paramSchema = property.Value;
                     yield return new OpenApiFormDataParameter()
                     {
                         Description = paramSchema.Description,

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -589,7 +589,13 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             writer.WriteProperty(OpenApiConstants.Description, Description);
 
             // format
-            writer.WriteProperty(OpenApiConstants.Format, Format);
+            var format = Format;
+            if (version < OpenApiSpecVersion.OpenApi3_1)
+            {
+                format ??= GetKnownTypeAndFormatPreOpenApi31()?.Format;
+            }
+
+            writer.WriteProperty(OpenApiConstants.Format, format);
 
             // default
             writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
@@ -844,7 +850,14 @@ private void SerializeAsV2(
             writer.WriteProperty(OpenApiConstants.Description, Description);
 
             // format
-            WriteFormatProperty(writer);
+            if (Format is null && GetKnownTypeAndFormatPreOpenApi31() is { } typeAndFormat)
+            {
+                writer.WriteProperty(OpenApiConstants.Format, typeAndFormat.Format);
+            }
+            else
+            {
+                WriteFormatProperty(writer);
+            }
 
             // title
             writer.WriteProperty(OpenApiConstants.Title, Title);
@@ -1008,7 +1021,15 @@ private void SerializeAsV2(
 
         private void SerializeTypePropertyForVersion2(IOpenApiWriter writer)
         {
-            if (Type is not { } type || type == JsonSchemaType.Null)
+            // TODO: Handle "file" type for 2.0.
+            // Spec https://spec.openapis.org/oas/v2.0.html#data-types
+            var typeToUse = Type;
+            if (version < OpenApiSpecVersion.OpenApi3_1)
+            {
+                typeToUse ??= GetKnownTypeAndFormatPreOpenApi31()?.Type;
+            }
+
+            if (typeToUse is not { } type || type == JsonSchemaType.Null)
             {
                 return;
             }
@@ -1157,6 +1178,22 @@ private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version
             }
         }
 
+        private (JsonSchemaType Type, string Format)? GetKnownTypeAndFormatPreOpenApi31()
+        {
+            // https://spec.openapis.org/oas/v3.2.0.html#migrating-binary-descriptions-from-oas-3-0
+            if (Type is not null && Type.Value.HasFlag(JsonSchemaType.String) && ContentEncoding == "base64")
+            {
+                return (Type.Value, "byte");
+            }
+
+            if (Type is null && !string.IsNullOrEmpty(ContentMediaType))
+            {
+                return (JsonSchemaType.String, "binary");
+            }
+
+            return null;
+        }
+
 #if NET5_0_OR_GREATER
         private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues<JsonSchemaType>();
 #else

src/Microsoft.OpenApi/Reader/V2/OpenApiParameterDeserializer.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System.Text.Json.Nodes;
@@ -74,6 +74,16 @@ internal static partial class OpenApiV2Deserializer
                         {                            
                             var schema = GetOrCreateSchema(o);
                             schema.Type = type.ToJsonSchemaType();
+                            // TODO: This should be represented using the 3.2 approach.
+                            // The object model must reflect the "latest" version of the spec.
+                            // Note that for parameters in 2.0, the "file" type is specified directly
+                            // on the parameter object. But for responses, the "file" type is an
+                            // extension of the Json Schema object, as in, it's not allowed by
+                            // Json Schema Draft 4, but is allowed as an OpenAPI 2.0 extension.
+                            // All that should be handled correctly.
+                            // The deserialization logic should try to map everything to the "3.2" way
+                            // of doing things.
+                            // And serialization should assume that the object model is in the "3.2" way of doing things.
                             if ("file".Equals(type, StringComparison.OrdinalIgnoreCase))
                             {
                                 schema.Format = "binary";

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

@@ -277,6 +277,18 @@ internal static partial class OpenApiV2Deserializer
                 OpenApiConstants.PatternPropertiesExtension,
                 (o, n, t, c) => o.PatternProperties = n.CreateMap(LoadSchema, t, c)
             },
+            {
+                OpenApiConstants.ContentEncodingExtension,
+                (o, n, _, _) => o.ContentEncoding = n.GetScalarValue()
+            },
+            {
+                OpenApiConstants.ContentMediaTypeExtension,
+                (o, n, _, _) => o.ContentMediaType = n.GetScalarValue()
+            },
+            {
+                OpenApiConstants.ContentSchemaExtension,
+                (o, n, doc, c) => o.ContentSchema = LoadSchema(n, doc, c)
+            },
         };
 
         private static readonly PatternFieldMap<OpenApiSchema> _openApiSchemaPatternFields = new PatternFieldMap<OpenApiSchema>
@@ -308,6 +320,26 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
                 }
             }
 
+            // The object model represents the latest version of the spec.
+            // https://spec.openapis.org/oas/v3.2.0.html#migrating-binary-descriptions-from-oas-3-0
+            // When we deserialize from V2, we detect the "old way" of specifying binary descriptions, and
+            // transform it in the object model to the latest thing.
+            if (schema.Type.HasValue && schema.Type.Value.HasFlag(JsonSchemaType.String) &&
+                schema.Format == "byte" &&
+                schema.ContentEncoding is null)
+            {
+                schema.ContentEncoding = "base64";
+                schema.Format = null;
+            }
+
+            if (schema.Type.HasValue && schema.Type.Value == JsonSchemaType.String &&
+                schema.Format == "binary")
+            {
+                schema.ContentMediaType ??= "application/octet-stream";
+                schema.Format = null;
+                schema.Type = null;
+            }
+
             return schema;
         }
     }

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

@@ -438,6 +438,26 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
                 }
             }
 
+            // The object model represents the latest version of the spec.
+            // https://spec.openapis.org/oas/v3.2.0.html#migrating-binary-descriptions-from-oas-3-0
+            // When we deserialize from V3, we detect the "old way" of specifying binary descriptions, and
+            // transform it in the object model to the latest thing.
+            if (schema.Type.HasValue && schema.Type.Value.HasFlag(JsonSchemaType.String) &&
+                schema.Format == "byte" &&
+                schema.ContentEncoding is null)
+            {
+                schema.ContentEncoding = "base64";
+                schema.Format = null;
+            }
+
+            if (schema.Type.HasValue && schema.Type.Value == JsonSchemaType.String &&
+                schema.Format == "binary")
+            {
+                schema.ContentMediaType ??= "application/octet-stream";
+                schema.Format = null;
+                schema.Type = null;
+            }
+
             return schema;
         }
 

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

@@ -1554,6 +1554,8 @@ public async Task SerializeMissingPropertiesEmitsOaiExtensionsInV3()
         {
             var expected = JsonNode.Parse("""
                 {
+                  "type": "string",
+                  "format": "binary",
                   "x-jsonschema-$anchor": "root",
                   "x-jsonschema-contentEncoding": "base64",
                   "x-jsonschema-contentMediaType": "application/jwt",