Change some 'can be's to 'MAY be'
MODIFY
versions/3.0.md
versions/3.0.md
@@ -148,7 +148,7 @@ Models are described using the [Schema Object](#schemaObject) which is an extend
<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
OAS uses several known formats to define in fine detail the data type being used.
However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
-Formats such as `"email"`, `"uuid"`, and so on, can be used even though undefined by this specification.
+Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
The formats defined by the OAS are:
@@ -191,7 +191,7 @@ This is the root document object of the [OpenAPI definition](#oasDefinition).
Field Name | Type | Description
---|:---:|---
<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition. 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 can be used by the clients if needed.
+<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="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
@@ -199,12 +199,12 @@ Field Name | Type | Description
<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="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
#### <a name="infoObject"></a>Info Object
The object provides metadata about the API.
-The metadata can be used by the clients if needed, and can be presented in editing or documentation generation tools for convenience.
+The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.
##### Fixed Fields
@@ -218,7 +218,7 @@ Field Name | Type | Description
<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Info Object Example:
@@ -266,7 +266,7 @@ Field Name | Type | Description
<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Contact Object Example:
@@ -295,7 +295,7 @@ Field Name | Type | Description
<a name="licenseName"></a>name | `string` | **REQUIRED**. The license name used for the API.
<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### License Object Example:
@@ -323,7 +323,7 @@ Field Name | Type | Description
<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Server Object Example
@@ -433,7 +433,7 @@ Field Name | Type | Description
<a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value to use for substitution, and to send, if an alternate value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
#### <a name="componentsObject"></a>Components Object
@@ -455,7 +455,7 @@ Field Name | Type | Description
<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).
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
@@ -636,7 +636,7 @@ Field Pattern | Type | Description
---|:---:|---
<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is **appended** (no relative URL resolution) to the expanded URL from the [`Server Object`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Path Templating Matching
@@ -728,7 +728,7 @@ Field Name | Type | Description
<a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Path Item Object Example
@@ -835,7 +835,7 @@ Field Name | Type | Description
<a name="operationSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. 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. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used.
<a name="operationServers"></a>servers | [[Server Object](#serverObject)] | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Operation Object Example
@@ -958,7 +958,7 @@ Field Name | Type | Description
<a name="externalDocDescription"></a>description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="externalDocUrl"></a>url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### External Documentation Object Example
@@ -1059,7 +1059,7 @@ spaceDelimited | false | n/a | n/a | blue%20black%20brown | R%20100%20G%20200%20
pipeDelimited | false | n/a | n/a | blue\|black\|brown | R\|100\|G\|200|G\|150
deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Parameter Object Examples
@@ -1230,7 +1230,7 @@ Field Name | Type | Description
<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `false`.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Request Body Examples
@@ -1350,7 +1350,7 @@ Field Name | Type | Description
<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` object is mutually exclusive of the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Media Type Examples
@@ -1559,7 +1559,7 @@ Field Name | Type | Description
<a name="encodingExplode"></a>explode | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Encoding Object Example
@@ -1626,7 +1626,7 @@ Field Pattern | Type | Description
<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Responses Object Example
@@ -1684,7 +1684,7 @@ Field Name | Type | Description
<a name="responseContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is the media type and the value is used to describe it.
<a name="responseLinks"></a>links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject).
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Response Object Examples
@@ -1820,7 +1820,7 @@ 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.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Key Expression
@@ -1894,7 +1894,7 @@ Field Name | Type | Description
<a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
<a name="exampleExternalValue"></a>externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
In all cases, the example value is expected to be compatible with the type schema
of its associated value. Tooling implementations MAY choose to
@@ -1982,7 +1982,7 @@ Field Name | Type | Description
<a name="linkDescription"></a>description | `string` | A description of the link. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="linkServer"></a>server | [Server Object](#serverObject) | A server object to be used by the target operation.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
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.
@@ -2164,7 +2164,7 @@ Field Name | Type | Description
<a name="tagDescription"></a>description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Tag Object Example
@@ -2348,7 +2348,7 @@ Field Name | Type | Description
<a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
###### <a name="schemaComposition"></a>Composition and Inheritance (Polymorphism)
@@ -2846,7 +2846,7 @@ Field Name | Type | Description
<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.
<a name="xmlWrapped"></a>wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `<books><book/><book/></books>`) or unwrapped (`<book/><book/>`). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`).
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### XML Object Examples
@@ -3200,7 +3200,7 @@ Field Name | Type | Applies To | Description
<a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported.
<a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### Security Scheme Object Example
@@ -3289,7 +3289,7 @@ Field Name | Type | Description
<a name="oauthFlowsClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenAPI 2.0.
<a name="oauthFlowsAuthorizationCode"></a>authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenAPI 2.0.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
#### <a name="oauthFlowObject"></a>OAuth Flow Object
@@ -3303,7 +3303,7 @@ Field Name | Type | Applies To | Description
<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.
-This object can be extended with [Specification Extensions](#specificationExtensions).
+This object MAY be extended with [Specification Extensions](#specificationExtensions).
##### OAuth Flow Object Examples

Change some 'can be's to 'MAY be'