Add webhooks property to the root document

src/Microsoft.OpenApi.Readers/ParsingContext.cs

@@ -63,12 +63,14 @@ internal OpenApiDocument Parse(YamlDocument yamlDocument)
                     VersionService = new OpenApiV2VersionService(Diagnostic);
                     doc = VersionService.LoadDocument(RootNode);
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi2_0;
+                    ValidateRequiredFields(doc, version);
                     break;
 
-                case string version when version.StartsWith("3.0"):
+                case string version when version.StartsWith("3.0") || version.StartsWith("3.1"):
                     VersionService = new OpenApiV3VersionService(Diagnostic);
                     doc = VersionService.LoadDocument(RootNode);
                     this.Diagnostic.SpecificationVersion = OpenApiSpecVersion.OpenApi3_0;
+                    ValidateRequiredFields(doc, version);
                     break;
 
                 default:
@@ -244,5 +246,21 @@ public void PopLoop(string loopid)
             }
         }
 
+        private void ValidateRequiredFields(OpenApiDocument doc, string version)
+        {
+            if ((version == "2.0" || version.StartsWith("3.0")) && (doc.Paths == null || !doc.Paths.Any()))
+            {
+                // paths is a required field in OpenAPI 3.0 but optional in 3.1
+                RootNode.Context.Diagnostic.Errors.Add(new OpenApiError("", $"Paths is a REQUIRED field at {RootNode.Context.GetLocation()}"));
+            }
+            else if (version.StartsWith("3.1"))
+            {
+                if ((doc.Paths == null || !doc.Paths.Any()) && (doc.Webhooks == null || !doc.Webhooks.Any()))
+                {
+                    RootNode.Context.Diagnostic.Errors.Add(new OpenApiError(
+                        "", $"The document MUST contain either a Paths or Webhooks field at {RootNode.Context.GetLocation()}"));
+                }
+            }
+        }
     }
 }

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

@@ -1,10 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license. 
 
-using System.Collections.Generic;
-using Microsoft.OpenApi.Any;
 using Microsoft.OpenApi.Extensions;
-using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Readers.ParseNodes;
 
@@ -26,6 +23,7 @@ internal static partial class OpenApiV3Deserializer
             {"info", (o, n) => o.Info = LoadInfo(n)},
             {"servers", (o, n) => o.Servers = n.CreateList(LoadServer)},
             {"paths", (o, n) => o.Paths = LoadPaths(n)},
+            {"webhooks", (o, n) => o.Webhooks = LoadPaths(n)},
             {"components", (o, n) => o.Components = LoadComponents(n)},
             {"tags", (o, n) => {o.Tags = n.CreateList(LoadTag);
                 foreach (var tag in o.Tags)
@@ -50,7 +48,7 @@ internal static partial class OpenApiV3Deserializer
         public static OpenApiDocument LoadOpenApi(RootNode rootNode)
         {
             var openApidoc = new OpenApiDocument();
-
+            
             var openApiNode = rootNode.GetMap();
 
             ParseMap(openApiNode, openApidoc, _openApiFixedFields, _openApiPatternFields);

src/Microsoft.OpenApi/Models/OpenApiConstants.cs

@@ -20,6 +20,11 @@ public static class OpenApiConstants
         /// </summary>
         public const string Info = "info";
 
+        /// <summary>
+        /// Field: Webhooks
+        /// </summary>
+        public const string Webhooks = "webhooks";
+
         /// <summary>
         /// Field: Title
         /// </summary>

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -39,6 +39,13 @@ public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible
         /// </summary>
         public OpenApiPaths Paths { get; set; }
 
+        /// <summary>
+        /// The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement.
+        /// A map of requests initiated other than by an API call, for example by an out of band registration. 
+        /// The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses
+        /// </summary>
+        public IDictionary<string, OpenApiPathItem> Webhooks { get; set; } = new Dictionary<string, OpenApiPathItem>();
+
         /// <summary>
         /// An element to hold various schemas for the specification.
         /// </summary>
@@ -84,6 +91,7 @@ public OpenApiDocument(OpenApiDocument document)
             Info = document?.Info != null ? new(document?.Info) : null;
             Servers = document?.Servers != null ? new List<OpenApiServer>(document.Servers) : null;
             Paths = document?.Paths != null ? new(document?.Paths) : null;
+            Webhooks = document?.Webhooks != null ? new Dictionary<string, OpenApiPathItem>(document.Webhooks) : null;
             Components = document?.Components != null ? new(document?.Components) : null;
             SecurityRequirements = document?.SecurityRequirements != null ? new List<OpenApiSecurityRequirement>(document.SecurityRequirements) : null;
             Tags = document?.Tags != null ? new List<OpenApiTag>(document.Tags) : null;
@@ -115,6 +123,24 @@ public void SerializeAsV3(IOpenApiWriter writer)
             // paths
             writer.WriteRequiredObject(OpenApiConstants.Paths, Paths, (w, p) => p.SerializeAsV3(w));
 
+            // webhooks
+            writer.WriteOptionalMap(
+                OpenApiConstants.Webhooks,
+                Webhooks,
+                (w, key, component) =>
+                {
+                    if (component.Reference != null &&
+                        component.Reference.Type == ReferenceType.PathItem &&
+                        component.Reference.Id == key)
+                    {
+                        component.SerializeAsV3WithoutReference(w);
+                    }
+                    else
+                    {
+                        component.SerializeAsV3(w);
+                    }
+                });
+
             // components
             writer.WriteOptionalObject(OpenApiConstants.Components, Components, (w, c) => c.SerializeAsV3(w));
 

src/Microsoft.OpenApi/Models/ReferenceType.cs

@@ -58,6 +58,11 @@ public enum ReferenceType
         /// <summary>
         /// Tags item.
         /// </summary>
-        [Display("tags")] Tag
+        [Display("tags")] Tag,
+
+        /// <summary>
+        /// Path item.
+        /// </summary>
+        [Display("pathItem")] PathItem,
     }
 }

src/Microsoft.OpenApi/Services/OpenApiVisitorBase.cs

@@ -99,6 +99,13 @@ public virtual void Visit(OpenApiPaths paths)
         {
         }
 
+        /// <summary>
+        /// Visits Webhooks>
+        /// </summary>
+        public virtual void Visit(IDictionary<string, OpenApiPathItem> webhooks)
+        {
+        }
+
         /// <summary>
         /// Visits <see cref="OpenApiPathItem"/>
         /// </summary>

src/Microsoft.OpenApi/Services/OpenApiWalker.cs

@@ -46,6 +46,7 @@ public void Walk(OpenApiDocument doc)
             Walk(OpenApiConstants.Info, () => Walk(doc.Info));
             Walk(OpenApiConstants.Servers, () => Walk(doc.Servers));
             Walk(OpenApiConstants.Paths, () => Walk(doc.Paths));
+            Walk(OpenApiConstants.Webhooks, () => Walk(doc.Webhooks));
             Walk(OpenApiConstants.Components, () => Walk(doc.Components));
             Walk(OpenApiConstants.Security, () => Walk(doc.SecurityRequirements));
             Walk(OpenApiConstants.ExternalDocs, () => Walk(doc.ExternalDocs));
@@ -221,6 +222,28 @@ internal void Walk(OpenApiPaths paths)
             }
         }
 
+        /// <summary>
+        /// Visits Webhooks and child objects
+        /// </summary>
+        internal void Walk(IDictionary<string, OpenApiPathItem> webhooks)
+        {
+            if (webhooks == null)
+            {
+                return;
+            }
+
+            _visitor.Visit(webhooks);
+
+            // Visit Webhooks
+            if (webhooks != null)
+            {
+                foreach (var pathItem in webhooks)
+                {
+                    Walk(pathItem.Key, () => Walk(pathItem.Value));
+                }
+            }
+        }
+
         /// <summary>
         /// Visits list of  <see cref="OpenApiServer"/> and child objects
         /// </summary>

src/Microsoft.OpenApi/Validations/Rules/OpenApiDocumentRules.cs

@@ -28,15 +28,6 @@ public static class OpenApiDocumentRules
                             String.Format(SRResource.Validation_FieldIsRequired, "info", "document"));
                     }
                     context.Exit();
-
-                    // paths
-                    context.Enter("paths");
-                    if (item.Paths == null)
-                    {
-                        context.CreateError(nameof(OpenApiDocumentFieldIsMissing),
-                            String.Format(SRResource.Validation_FieldIsRequired, "paths", "document"));
-                    }
-                    context.Exit();
                 });
     }
 }

test/Microsoft.OpenApi.Readers.Tests/Microsoft.OpenApi.Readers.Tests.csproj

@@ -137,6 +137,9 @@
       <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\minimalDocument.yaml">
         <CopyToOutputDirectory>Never</CopyToOutputDirectory>
       </EmbeddedResource>
+      <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\documentWithWebhooks.yaml">
+        <CopyToOutputDirectory>Never</CopyToOutputDirectory>
+      </EmbeddedResource>
       <EmbeddedResource Include="V3Tests\Samples\OpenApiDocument\apiWithFullHeaderComponent.yaml">
         <CopyToOutputDirectory>Never</CopyToOutputDirectory>
       </EmbeddedResource>