Add OpenApiXmlNodeType enum and update OpenApiXml for OAI 3.2.0

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

Author: Copilot

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -245,6 +245,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string Wrapped = "wrapped";
 
+        /// <summary>
+        /// Field: NodeType
+        /// </summary>
+        public const string NodeType = "nodeType";
+
         /// <summary>
         /// Field: In
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiXml.cs

@@ -11,6 +11,10 @@ namespace Microsoft.OpenApi
     /// </summary>
     public class OpenApiXml : IOpenApiSerializable, IOpenApiExtensible
     {
+        private OpenApiXmlNodeType? _nodeType;
+        private bool _attribute;
+        private bool _wrapped;
+
         /// <summary>
         /// Replaces the name of the element/attribute used for the described schema property.
         /// </summary>
@@ -30,13 +34,56 @@ public class OpenApiXml : IOpenApiSerializable, IOpenApiExtensible
         /// Declares whether the property definition translates to an attribute instead of an element.
         /// Default value is false.
         /// </summary>
-        public bool Attribute { get; set; }
+        [Obsolete("Use NodeType property instead. This property will be removed in a future version.")]
+        public bool Attribute
+        {
+            get
+            {
+                // If NodeType is explicitly set, use it; otherwise use the backing field
+                if (_nodeType.HasValue)
+                {
+                    return _nodeType == OpenApiXmlNodeType.Attribute;
+                }
+                return _attribute;
+            }
+            set
+            {
+                _attribute = value;
+                _nodeType = value ? OpenApiXmlNodeType.Attribute : OpenApiXmlNodeType.None;
+            }
+        }
 
         /// <summary>
         /// Signifies whether the array is wrapped.
         /// Default value is false.
         /// </summary>
-        public bool Wrapped { get; set; }
+        [Obsolete("Use NodeType property instead. This property will be removed in a future version.")]
+        public bool Wrapped
+        {
+            get
+            {
+                // If NodeType is explicitly set, use it; otherwise use the backing field
+                if (_nodeType.HasValue)
+                {
+                    return _nodeType == OpenApiXmlNodeType.Element;
+                }
+                return _wrapped;
+            }
+            set
+            {
+                _wrapped = value;
+                _nodeType = value ? OpenApiXmlNodeType.Element : OpenApiXmlNodeType.None;
+            }
+        }
+
+        /// <summary>
+        /// The node type of the XML representation.
+        /// </summary>
+        public OpenApiXmlNodeType? NodeType
+        {
+            get => _nodeType;
+            set => _nodeType = value;
+        }
 
         /// <summary>
         /// Specification Extensions.
@@ -56,8 +103,9 @@ public OpenApiXml(OpenApiXml xml)
             Name = xml?.Name ?? Name;
             Namespace = xml?.Namespace ?? Namespace;
             Prefix = xml?.Prefix ?? Prefix;
-            Attribute = xml?.Attribute ?? Attribute;
-            Wrapped = xml?.Wrapped ?? Wrapped;
+            _nodeType = xml?._nodeType ?? _nodeType;
+            _attribute = xml?._attribute ?? _attribute;
+            _wrapped = xml?._wrapped ?? _wrapped;
             Extensions = xml?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(xml.Extensions) : null;
         }
 
@@ -108,11 +156,32 @@ private void Write(IOpenApiWriter writer, OpenApiSpecVersion specVersion)
             // prefix
             writer.WriteProperty(OpenApiConstants.Prefix, Prefix);
 
-            // attribute
-            writer.WriteProperty(OpenApiConstants.Attribute, Attribute, false);
-
-            // wrapped
-            writer.WriteProperty(OpenApiConstants.Wrapped, Wrapped, false);
+            // For OpenAPI 3.2.0 and above, serialize nodeType
+            if (specVersion >= OpenApiSpecVersion.OpenApi3_2)
+            {
+                if (_nodeType.HasValue)
+                {
+                    writer.WriteProperty(OpenApiConstants.NodeType, _nodeType.Value.GetDisplayName());
+                }
+            }
+            else
+            {
+                // For OpenAPI 3.1.0 and below, serialize attribute and wrapped
+                // Use backing fields if they were set via obsolete properties,
+                // otherwise derive from NodeType if set
+                bool attribute = _attribute;
+                bool wrapped = _wrapped;
+                
+                if (_nodeType.HasValue && !_attribute && !_wrapped)
+                {
+                    // NodeType was set directly, not via obsolete properties
+                    attribute = _nodeType == OpenApiXmlNodeType.Attribute;
+                    wrapped = _nodeType == OpenApiXmlNodeType.Element;
+                }
+                
+                writer.WriteProperty(OpenApiConstants.Attribute, attribute, false);
+                writer.WriteProperty(OpenApiConstants.Wrapped, wrapped, false);
+            }
 
             // extensions
             writer.WriteExtensions(Extensions, specVersion);

src/Microsoft.OpenApi/Models/OpenApiXmlNodeType.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+namespace Microsoft.OpenApi
+{
+    /// <summary>
+    /// The type of the XML node
+    /// </summary>
+    public enum OpenApiXmlNodeType
+    {
+        /// <summary>
+        /// Element node type
+        /// </summary>
+        [Display("element")] Element,
+
+        /// <summary>
+        /// Attribute node type
+        /// </summary>
+        [Display("attribute")] Attribute,
+
+        /// <summary>
+        /// Text node type
+        /// </summary>
+        [Display("text")] Text,
+
+        /// <summary>
+        /// CDATA node type
+        /// </summary>
+        [Display("cdata")] Cdata,
+
+        /// <summary>
+        /// None node type
+        /// </summary>
+        [Display("none")] None
+    }
+}

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

@@ -42,7 +42,9 @@ internal static partial class OpenApiV2Deserializer
                     var attribute = n.GetScalarValue();
                     if (attribute is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Attribute = bool.Parse(attribute);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },
@@ -53,7 +55,9 @@ internal static partial class OpenApiV2Deserializer
                     var wrapped = n.GetScalarValue();
                     if (wrapped is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Wrapped = bool.Parse(wrapped);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },

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

@@ -39,7 +39,9 @@ internal static partial class OpenApiV3Deserializer
                     var attribute = n.GetScalarValue();
                     if (attribute is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Attribute = bool.Parse(attribute);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },
@@ -50,7 +52,9 @@ internal static partial class OpenApiV3Deserializer
                     var wrapped = n.GetScalarValue();
                     if (wrapped is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Wrapped = bool.Parse(wrapped);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },

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

@@ -41,7 +41,9 @@ internal static partial class OpenApiV31Deserializer
                     var attribute = n.GetScalarValue();
                     if (attribute is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Attribute = bool.Parse(attribute);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },
@@ -52,7 +54,9 @@ internal static partial class OpenApiV31Deserializer
                     var wrapped = n.GetScalarValue();
                     if (wrapped is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Wrapped = bool.Parse(wrapped);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             }

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

@@ -41,7 +41,9 @@ internal static partial class OpenApiV32Deserializer
                     var attribute = n.GetScalarValue();
                     if (attribute is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Attribute = bool.Parse(attribute);
+#pragma warning restore CS0618 // Type or member is obsolete
                     }
                 }
             },
@@ -52,7 +54,28 @@ internal static partial class OpenApiV32Deserializer
                     var wrapped = n.GetScalarValue();
                     if (wrapped is not null)
                     {
+#pragma warning disable CS0618 // Type or member is obsolete
                         o.Wrapped = bool.Parse(wrapped);
+#pragma warning restore CS0618 // Type or member is obsolete
+                    }
+                }
+            },
+            {
+                "nodeType",
+                (o, n, _) =>
+                {
+                    var nodeType = n.GetScalarValue();
+                    if (nodeType is not null)
+                    {
+                        o.NodeType = nodeType.ToLowerInvariant() switch
+                        {
+                            "element" => OpenApiXmlNodeType.Element,
+                            "attribute" => OpenApiXmlNodeType.Attribute,
+                            "text" => OpenApiXmlNodeType.Text,
+                            "cdata" => OpenApiXmlNodeType.Cdata,
+                            "none" => OpenApiXmlNodeType.None,
+                            _ => null
+                        };
                     }
                 }
             }

test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiXmlTests.cs

@@ -21,6 +21,7 @@ public async Task ParseBasicXmlShouldSucceed()
             var xml = await OpenApiModelFactory.LoadAsync<OpenApiXml>(Resources.GetStream(Path.Combine(SampleFolderPath, "basicXml.yaml")), OpenApiSpecVersion.OpenApi3_0, new(), settings: SettingsFixture.ReaderSettings);
 
             // Assert
+#pragma warning disable CS0618 // Type or member is obsolete
             Assert.Equivalent(
                 new OpenApiXml
                 {
@@ -29,6 +30,7 @@ public async Task ParseBasicXmlShouldSucceed()
                     Prefix = "samplePrefix",
                     Wrapped = true
                 }, xml);
+#pragma warning restore CS0618 // Type or member is obsolete
         }
     }
 }