Referencing issue OAI#513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all.

Author: tedepstein

versions/3.0.3.md

@@ -3286,12 +3286,14 @@ Field Name | Type | Applies To | Description
 <a name="oauthFlowAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL.
 <a name="oauthFlowTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL.
 <a name="oauthFlowRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
-<a name="oauthFlowScopes"></a>scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+<a name="oauthFlowScopes"></a>scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. If scope is optional, the map MAY include an entry with an empty string as its key to represent the default scope. If scope is not used in the authorization scheme, the map MAY be empty.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
 ##### OAuth Flow Object Examples
 
+###### OAuth Flows with Required Scope
+
 ```JSON
 {
   "type": "oauth2",
@@ -3331,6 +3333,41 @@ flows:
       read:pets: read your pets 
 ```
 
+###### OAuth Flows with Unspecified and Optional Scope
+
+```JSON
+{
+  "type": "oauth2",
+  "flows": {
+    "implicit": {
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "scopes": {}
+    },
+    "authorizationCode": {
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "tokenUrl": "https://example.com/api/oauth/token",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "": "default scope provides read-only access"
+      }
+    }
+  }
+}
+```
+
+```yaml
+type: oauth2
+flows:
+  implicit:
+    authorizationUrl: https://example.com/api/oauth/dialog
+    scopes: {}
+  authorizationCode:
+    authorizationUrl: https://example.com/api/oauth/dialog
+    tokenUrl: https://example.com/api/oauth/token
+    scopes:
+      write:pets: modify pets in your account
+      "" : default scope provides read-only access
+```
 
 #### <a name="securityRequirementObject"></a>Security Requirement Object
 
@@ -3346,7 +3383,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](#
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="securityRequirementsName"></a>{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty.
+<a name="securityRequirementsName"></a>{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty.
 
 ##### Security Requirement Object Examples