Add $self property to OpenApiDocument with serialization/deserialization support

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

Author: Copilot

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -40,6 +40,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string JsonSchemaDialect = "jsonSchemaDialect";
 
+        /// <summary>
+        /// Field: $self
+        /// </summary>
+        public const string Self = "$self";
+
         /// <summary>
         /// Field: Webhooks
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -40,6 +40,11 @@ public void RegisterComponents()
         /// </summary>
         public Uri? JsonSchemaDialect { get; set; }
 
+        /// <summary>
+        /// The URI identifying this document. This MUST be in the form of a URI. (OAI 3.2.0+)
+        /// </summary>
+        public Uri? Self { get; set; }
+
         /// <summary>
         /// An array of Server Objects, which provide connectivity information to a target server.
         /// </summary>
@@ -126,6 +131,7 @@ public OpenApiDocument(OpenApiDocument? document)
             Workspace = document?.Workspace != null ? new(document.Workspace) : null;
             Info = document?.Info != null ? new(document.Info) : new OpenApiInfo();
             JsonSchemaDialect = document?.JsonSchemaDialect ?? JsonSchemaDialect;
+            Self = document?.Self ?? Self;
             Servers = document?.Servers != null ? [.. document.Servers] : null;
             Paths = document?.Paths != null ? new(document.Paths) : [];
             Webhooks = document?.Webhooks != null ? new Dictionary<string, IOpenApiPathItem>(document.Webhooks) : null;
@@ -200,6 +206,12 @@ private void SerializeAsV3X(IOpenApiWriter writer, string versionString, OpenApi
             // jsonSchemaDialect
             writer.WriteProperty(OpenApiConstants.JsonSchemaDialect, JsonSchemaDialect?.ToString());
 
+            // $self - only for v3.2+
+            if (version >= OpenApiSpecVersion.OpenApi3_2)
+            {
+                writer.WriteProperty(OpenApiConstants.Self, Self?.ToString());
+            }
+
             SerializeInternal(writer, version, callback);
 
             // webhooks
@@ -218,6 +230,12 @@ private void SerializeAsV3X(IOpenApiWriter writer, string versionString, OpenApi
                 }
             });
 
+            // $self as extension for v3.1 and earlier
+            if (version < OpenApiSpecVersion.OpenApi3_2 && Self is not null)
+            {
+                writer.WriteProperty(OpenApiConstants.ExtensionFieldNamePrefix + "oai-" + OpenApiConstants.Self, Self.ToString());
+            }
+
             writer.WriteEndObject();
         }
 

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

@@ -21,8 +21,29 @@ internal static partial class OpenApiV3Deserializer
                 } /* Version is valid field but we already parsed it */
             },
             {"info", (o, n, _) => o.Info = LoadInfo(n, o)},
+            {
+                "jsonSchemaDialect", (o, n, _) =>
+                {
+                    var value = n.GetScalarValue();
+                    if (value != null)
+                    {
+                        o.JsonSchemaDialect = new(value, UriKind.Absolute);
+                    }
+                }
+            },
+            {
+                "$self", (o, n, _) =>
+                {
+                    var value = n.GetScalarValue();
+                    if (value != null)
+                    {
+                        o.Self = new(value, UriKind.Absolute);
+                    }
+                }
+            },
             {"servers", (o, n, _) => o.Servers = n.CreateList(LoadServer, o)},
             {"paths", (o, n, _) => o.Paths = LoadPaths(n, o)},
+            {"webhooks", (o, n, _) => o.Webhooks = n.CreateMap(LoadPathItem, o)},
             {"components", (o, n, _) => o.Components = LoadComponents(n, o)},
             {"tags", (o, n, _) => { if (n.CreateList(LoadTag, o) is {Count:> 0} tags) {o.Tags = new HashSet<OpenApiTag>(tags, OpenApiTagComparer.Instance); } } },
             {"externalDocs", (o, n, _) => o.ExternalDocs = LoadExternalDocs(n, o)},
@@ -32,7 +53,21 @@ internal static partial class OpenApiV3Deserializer
         private static readonly PatternFieldMap<OpenApiDocument> _openApiPatternFields = new PatternFieldMap<OpenApiDocument>
         {
             // We have no semantics to verify X- nodes, therefore treat them as just values.
-            {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => o.AddExtension(p, LoadExtension(p, n))}
+            {s => s.StartsWith(OpenApiConstants.ExtensionFieldNamePrefix, StringComparison.OrdinalIgnoreCase), (o, p, n, _) => 
+            {
+                if (p.Equals("x-oai-$self", StringComparison.OrdinalIgnoreCase))
+                {
+                    var value = n.GetScalarValue();
+                    if (value != null)
+                    {
+                        o.Self = new(value, UriKind.Absolute);
+                    }
+                }
+                else
+                {
+                    o.AddExtension(p, LoadExtension(p, n));
+                }
+            }}
         };
 
         public static OpenApiDocument LoadOpenApi(RootNode rootNode, Uri location)

test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

@@ -539,6 +539,7 @@ namespace Microsoft.OpenApi
         public const string Security = "security";
         public const string SecurityDefinitions = "securityDefinitions";
         public const string SecuritySchemes = "securitySchemes";
+        public const string Self = "$self";
         public const string Server = "server";
         public const string Servers = "servers";
         public const string Style = "style";
@@ -615,6 +616,7 @@ namespace Microsoft.OpenApi
         public System.Collections.Generic.IDictionary<string, object>? Metadata { get; set; }
         public Microsoft.OpenApi.OpenApiPaths Paths { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiSecurityRequirement>? Security { get; set; }
+        public System.Uri? Self { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiServer>? Servers { get; set; }
         public System.Collections.Generic.ISet<Microsoft.OpenApi.OpenApiTag>? Tags { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.IOpenApiPathItem>? Webhooks { get; set; }