Make paths object optional (#1781)

* Make paths object optional

* Adding reusable Path Item Objects

Under `components`

* Adopt DM's suggested change to OpenAPI doc definition

* Cleanup use of specification and definition where we mean document

* multipartite>composite, define ACL

* Add ' | Reference Object' to callbacks/webhooks

Co-authored-by: Ron <[email protected]>

Author: MikeRalphson

versions/3.1.0.md

@@ -68,7 +68,7 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 ## Definitions
 
 ##### <a name="oasDocument"></a>OpenAPI Document
-A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
+A self-contained or composite resource which defines or describes an API or elements of an API. The OpenAPI document MUST contain at least one [paths](#pathsObject) field, a [components](#oasComponents) field or a [webhooks](#oasWebhooks) field. An OpenAPI document uses and conforms to the OpenAPI Specification.
 
 ##### <a name="pathTemplating"></a>Path Templating
 Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
@@ -183,7 +183,7 @@ In the following description, if a field is not explicitly **REQUIRED** or descr
 
 #### <a name="oasObject"></a>OpenAPI Object
 
-This is the root document object of the [OpenAPI document](#oasDocument).
+This is the root object of the [OpenAPI document](#oasDocument).
 
 ##### Fixed Fields
 
@@ -192,11 +192,11 @@ Field Name | Type | Description
 <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
 <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
-<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
-<a name="oasWebhooks"></a>webhooks | Map[`string`, [Path Item Object](#pathItemObject)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes 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 Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](../examples/v3.1/webhook-example.yaml) is available.
-<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
+<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | The available paths and operations for the API.
+<a name="oasWebhooks"></a>webhooks | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] ] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes 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. An [example](../examples/v3.1/webhook-example.yaml) is available.
+<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the document.
 <a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
-<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
+<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
 <a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
 
 
@@ -459,6 +459,8 @@ Field Name | Type | Description
 <a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
 <a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
 <a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).
+<a name="componentsPathItems"></a> pathItems | Map[`string`, [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Path Item Object](#pathItemObject).
+
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -652,7 +654,7 @@ components:
 #### <a name="pathsObject"></a>Paths Object
 
 Holds the relative paths to the individual endpoints and their operations.
-The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL.  The Paths MAY be empty, due to [ACL constraints](#securityFiltering).
+The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL.  The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering). Paths MAY be omitted in some classes of OAS documents, including referenced sub-documents and overlays.
 
 ##### Patterned Fields
 
@@ -1642,10 +1644,11 @@ The documentation is not necessarily expected to cover all possible HTTP respons
 However, documentation is expected to cover a successful operation response and any known errors.
 
 The `default` MAY be used as a default response object for all HTTP codes 
-that are not covered individually by the specification.
+that are not covered individually by the `Responses Object`.
 
-The `Responses Object` MUST contain at least one response code, and it 
-SHOULD be the response for a successful operation call.
+The `Responses Object` MUST contain at least one response code, and if only one
+response code is provided it SHOULD be the response for a successful operation
+call.
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -1852,7 +1855,7 @@ To describe incoming requests from the API provider independent from another API
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.  A [complete example](../examples/v3.0/callback-example.yaml) is available.
+<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) \| [Reference Object](#referenceObject) | A Path Item Object, or a reference to one, used to define a callback request and expected responses.  A [complete example](../examples/v3.0/callback-example.yaml) is available.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -2046,7 +2049,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
 A linked operation MUST be identified using either an `operationRef` or `operationId`.
 In the case of an `operationId`, it MUST be unique and resolved in the scope of the OAS document.
 Because of the potential for name clashes, the `operationRef` syntax is preferred 
-for specifications with external references.
+for OpenAPI documents with external references.
 
 ##### Examples
 
@@ -2242,7 +2245,7 @@ description: Pets operations
 
 #### <a name="referenceObject"></a>Reference Object
 
-A simple object to allow referencing other components in the specification, internally and externally.
+A simple object to allow referencing other components in the OpenAPI document, internally and externally.
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -2670,7 +2673,7 @@ components:
 
 #### <a name="discriminatorObject"></a>Discriminator Object
 
-When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the specification of an alternative schema based on the value associated with it.
+When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.
 
 When using the discriminator, _inline_ schemas will not be considered.
 
@@ -3389,7 +3392,7 @@ While not part of the specification itself, certain libraries MAY choose to allo
 
 Two examples of this:
 
-1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
+1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication.
 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
 
 ## <a name="revisionHistory"></a>Appendix A: Revision History