Add support for dataValue and serializedValue in OpenApiExample

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiExample.cs

@@ -22,4 +22,20 @@ public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedE
     /// The value field and externalValue field are mutually exclusive.
     /// </summary>
     public string? ExternalValue { get; }
+
+    /// <summary>
+    /// Embedded literal example value. 
+    /// The dataValue property and the value property are mutually exclusive.
+    /// To represent examples of media types that cannot be naturally represented in JSON or YAML,
+    /// use a string value to contain the example with escaping where necessary.
+    /// Available in OpenAPI 3.2+, serialized as extension in 3.1 and earlier.
+    /// </summary>
+    public JsonNode? DataValue { get; }
+
+    /// <summary>
+    /// A string representation of the example.
+    /// This is mutually exclusive with the value and dataValue properties.
+    /// Available in OpenAPI 3.2+, serialized as extension in 3.1 and earlier.
+    /// </summary>
+    public string? SerializedValue { get; }
 }

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -340,6 +340,16 @@ public static class OpenApiConstants
         /// </summary>
         public const string ExternalValue = "externalValue";
 
+        /// <summary>
+        /// Field: DataValue
+        /// </summary>
+        public const string DataValue = "dataValue";
+
+        /// <summary>
+        /// Field: SerializedValue
+        /// </summary>
+        public const string SerializedValue = "serializedValue";
+
         /// <summary>
         /// Field: DollarRef
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiExample.cs

@@ -23,6 +23,12 @@ public class OpenApiExample : IOpenApiExtensible, IOpenApiExample
         /// <inheritdoc/>
         public JsonNode? Value { get; set; }
 
+        /// <inheritdoc/>
+        public JsonNode? DataValue { get; set; }
+
+        /// <inheritdoc/>
+        public string? SerializedValue { get; set; }
+
         /// <inheritdoc/>
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; }
 
@@ -42,6 +48,8 @@ internal OpenApiExample(IOpenApiExample example)
             Description = example.Description ?? Description;
             Value = example.Value != null ? JsonNodeCloneHelper.Clone(example.Value) : null;
             ExternalValue = example.ExternalValue ?? ExternalValue;
+            DataValue = example.DataValue != null ? JsonNodeCloneHelper.Clone(example.DataValue) : null;
+            SerializedValue = example.SerializedValue ?? SerializedValue;
             Extensions = example.Extensions != null ? new Dictionary<string, IOpenApiExtension>(example.Extensions) : null;
         }
 
@@ -84,6 +92,32 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // externalValue
             writer.WriteProperty(OpenApiConstants.ExternalValue, ExternalValue);
 
+            // dataValue - serialize as native field in v3.2+, as extension in earlier versions
+            if (DataValue is not null)
+            {
+                if (version >= OpenApiSpecVersion.OpenApi3_2)
+                {
+                    writer.WriteRequiredObject(OpenApiConstants.DataValue, DataValue, (w, v) => w.WriteAny(v));
+                }
+                else
+                {
+                    writer.WriteRequiredObject(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.DataValue, DataValue, (w, v) => w.WriteAny(v));
+                }
+            }
+
+            // serializedValue - serialize as native field in v3.2+, as extension in earlier versions
+            if (SerializedValue is not null)
+            {
+                if (version >= OpenApiSpecVersion.OpenApi3_2)
+                {
+                    writer.WriteProperty(OpenApiConstants.SerializedValue, SerializedValue);
+                }
+                else
+                {
+                    writer.WriteProperty(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.SerializedValue, SerializedValue);
+                }
+            }
+
             // extensions
             writer.WriteExtensions(Extensions, version);
 

src/Microsoft.OpenApi/Models/References/OpenApiExampleReference.cs

@@ -55,6 +55,12 @@ public string? Summary
         /// <inheritdoc/>
         public JsonNode? Value { get => Target?.Value; }
 
+        /// <inheritdoc/>
+        public JsonNode? DataValue { get => Target?.DataValue; }
+
+        /// <inheritdoc/>
+        public string? SerializedValue { get => Target?.SerializedValue; }
+
         /// <inheritdoc/>
         public override IOpenApiExample CopyReferenceAsTargetElementWithOverrides(IOpenApiExample source)
         {

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

@@ -34,6 +34,8 @@ internal static partial class OpenApiV3Deserializer
         private static readonly PatternFieldMap<OpenApiExample> _examplePatternFields =
             new()
             {
+                {s => s.Equals("x-oai-dataValue", StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.DataValue = n.CreateAny()},
+                {s => s.Equals("x-oai-serializedValue", StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.SerializedValue = n.GetScalarValue()},
                 {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p,n))}
             };
 

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

@@ -40,6 +40,8 @@ internal static partial class OpenApiV31Deserializer
         private static readonly PatternFieldMap<OpenApiExample> _examplePatternFields =
             new()
             {
+                {s => s.Equals("x-oai-dataValue", StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.DataValue = n.CreateAny()},
+                {s => s.Equals("x-oai-serializedValue", StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.SerializedValue = n.GetScalarValue()},
                 {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p,n))}
             };
 

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

@@ -34,6 +34,18 @@ internal static partial class OpenApiV32Deserializer
                     o.ExternalValue = n.GetScalarValue();
                 }
             },
+            {
+                "dataValue", (o, n, _) =>
+                {
+                    o.DataValue = n.CreateAny();
+                }
+            },
+            {
+                "serializedValue", (o, n, _) =>
+                {
+                    o.SerializedValue = n.GetScalarValue();
+                }
+            },
 
         };
 

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiExampleTests.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System.IO;
+using System.Text.Json.Nodes;
+using System.Threading.Tasks;
+using Microsoft.OpenApi.Reader;
+using Xunit;
+
+namespace Microsoft.OpenApi.Readers.Tests.V31Tests
+{
+    [Collection("DefaultSettings")]
+    public class OpenApiExampleTests
+    {
+        private const string SampleFolderPath = "V31Tests/Samples/OpenApiExample/";
+
+        [Fact]
+        public async Task ParseExampleWithDataValueExtensionShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithDataValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_1, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with dataValue (extension)", example.Summary);
+            Assert.NotNull(example.DataValue);
+            Assert.Equal("Jane Smith", example.DataValue["name"].GetValue<string>());
+            Assert.Equal(25, example.DataValue["age"].GetValue<decimal>());
+        }
+
+        [Fact]
+        public async Task ParseExampleWithSerializedValueExtensionShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithSerializedValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_1, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with serializedValue (extension)", example.Summary);
+            Assert.Equal("custom serialized string with extension", example.SerializedValue);
+        }
+    }
+}

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiExample/exampleWithDataValue.yaml

@@ -0,0 +1,4 @@
+summary: Example with dataValue (extension)
+x-oai-dataValue:
+  name: Jane Smith
+  age: 25

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiExample/exampleWithSerializedValue.yaml

@@ -0,0 +1,2 @@
+summary: Example with serializedValue (extension)
+x-oai-serializedValue: "custom serialized string with extension"

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

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System.IO;
+using System.Text.Json.Nodes;
+using System.Threading.Tasks;
+using Microsoft.OpenApi.Reader;
+using Xunit;
+
+namespace Microsoft.OpenApi.Readers.Tests.V32Tests
+{
+    [Collection("DefaultSettings")]
+    public class OpenApiExampleTests
+    {
+        private const string SampleFolderPath = "V32Tests/Samples/OpenApiExample/";
+
+        [Fact]
+        public async Task ParseExampleWithDataValueShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithDataValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_2, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with dataValue", example.Summary);
+            Assert.NotNull(example.DataValue);
+            Assert.Equal("John Doe", example.DataValue["name"].GetValue<string>());
+            Assert.Equal(30, example.DataValue["age"].GetValue<decimal>());
+        }
+
+        [Fact]
+        public async Task ParseExampleWithSerializedValueShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithSerializedValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_2, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with serializedValue", example.Summary);
+            Assert.Equal("custom serialized string", example.SerializedValue);
+        }
+    }
+}

test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiExample/exampleWithDataValue.yaml

@@ -0,0 +1,4 @@
+summary: Example with dataValue
+dataValue:
+  name: John Doe
+  age: 30

test/Microsoft.OpenApi.Readers.Tests/V32Tests/Samples/OpenApiExample/exampleWithSerializedValue.yaml

@@ -0,0 +1,2 @@
+summary: Example with serializedValue
+serializedValue: "custom serialized string"

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

@@ -73,5 +73,39 @@ public async Task ParseExampleForcedStringSucceed()
             var result = await OpenApiDocument.LoadAsync(Path.Combine(SampleFolderPath, "explicitString.yaml"), SettingsFixture.ReaderSettings);
             Assert.Empty(result.Diagnostic.Errors);
         }
+
+        [Fact]
+        public async Task ParseExampleWithDataValueExtensionShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithDataValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_0, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with dataValue (extension)", example.Summary);
+            Assert.NotNull(example.DataValue);
+            Assert.Equal("Alice Johnson", example.DataValue["name"].GetValue<string>());
+            Assert.Equal(28, example.DataValue["age"].GetValue<decimal>());
+        }
+
+        [Fact]
+        public async Task ParseExampleWithSerializedValueExtensionShouldSucceed()
+        {
+            // Arrange & Act
+            var example = await OpenApiModelFactory.LoadAsync<OpenApiExample>(
+                Path.Combine(SampleFolderPath, "exampleWithSerializedValue.yaml"), 
+                OpenApiSpecVersion.OpenApi3_0, 
+                new(), 
+                SettingsFixture.ReaderSettings);
+
+            // Assert
+            Assert.NotNull(example);
+            Assert.Equal("Example with serializedValue (extension)", example.Summary);
+            Assert.Equal("custom serialized string for V3", example.SerializedValue);
+        }
     }
 }

test/Microsoft.OpenApi.Readers.Tests/V3Tests/Samples/OpenApiExample/exampleWithDataValue.yaml

@@ -0,0 +1,4 @@
+summary: Example with dataValue (extension)
+x-oai-dataValue:
+  name: Alice Johnson
+  age: 28

test/Microsoft.OpenApi.Readers.Tests/V3Tests/Samples/OpenApiExample/exampleWithSerializedValue.yaml

@@ -0,0 +1,2 @@
+summary: Example with serializedValue (extension)
+x-oai-serializedValue: "custom serialized string for V3"

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithDataValueAsV31JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -0,0 +1,7 @@
+{
+  "summary": "Example with dataValue",
+  "x-oai-dataValue": {
+    "name": "John Doe",
+    "age": 30
+  }
+}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithDataValueAsV31JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -0,0 +1 @@
+{"summary":"Example with dataValue","x-oai-dataValue":{"name":"John Doe","age":30}}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithDataValueAsV32JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -0,0 +1,7 @@
+{
+  "summary": "Example with dataValue",
+  "dataValue": {
+    "name": "John Doe",
+    "age": 30
+  }
+}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithDataValueAsV32JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -0,0 +1 @@
+{"summary":"Example with dataValue","dataValue":{"name":"John Doe","age":30}}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithSerializedValueAsV31JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -0,0 +1,4 @@
+{
+  "summary": "Example with serializedValue",
+  "x-oai-serializedValue": "custom serialized string"
+}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithSerializedValueAsV31JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -0,0 +1 @@
+{"summary":"Example with serializedValue","x-oai-serializedValue":"custom serialized string"}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithSerializedValueAsV32JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -0,0 +1,4 @@
+{
+  "summary": "Example with serializedValue",
+  "serializedValue": "custom serialized string"
+}

test/Microsoft.OpenApi.Tests/Models/OpenApiExampleTests.SerializeExampleWithSerializedValueAsV32JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -0,0 +1 @@
+{"summary":"Example with serializedValue","serializedValue":"custom serialized string"}