From 5580a9c5fbef55e925e7514b986c95a0e4c85821 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Fri, 9 Sep 2022 18:55:45 +0200 Subject: [PATCH] docs: align wording with RFC 2119 (#818) --- spec/asyncapi.md | 58 ++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 386e694c..8601d468 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -160,18 +160,18 @@ It combines resource listing and API declaration together into one document. Field Name | Type | Description ---|:---:|--- -asyncapi | [AsyncAPI Version String](#A2SVersionString) | **Required.** Specifies the AsyncAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (1.0.*). Patch versions will correspond to patches of this document. +asyncapi | [AsyncAPI Version String](#A2SVersionString) | **REQUIRED.** Specifies the AsyncAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (1.0.*). Patch versions will correspond to patches of this document. id | [Identifier](#A2SIdString) | Identifier of the [application](#definitionsApplication) the AsyncAPI document is defining. -info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. +info | [Info Object](#infoObject) | **REQUIRED.** Provides metadata about the API. The metadata can be used by the clients if needed. servers | [Servers Object](#serversObject) | Provides connection details of servers. defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. -channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API. +channels | [Channels Object](#channelsObject) | **REQUIRED** The available channels and messages for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. 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). #### AsyncAPI Version String @@ -220,14 +220,14 @@ The metadata can be used by the clients if needed. Field Name | Type | Description ---|:---:|--- -title | `string` | **Required.** The title of the application. -version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). +title | `string` | **REQUIRED.** The title of the application. +version | `string` | **REQUIRED** Provides the version of the application API (not to be confused with the specification version). description | `string` | A short description of the application. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example: @@ -275,7 +275,7 @@ Field Name | Type | Description url | `string` | The URL pointing to the contact information. This MUST be in the form of an absolute URL. 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: @@ -301,10 +301,10 @@ License information for the exposed API. Field Name | Type | Description ---|:---:|--- -name | `string` | **Required.** The license name used for the API. +name | `string` | **REQUIRED.** The license name used for the API. url | `string` | A URL to the license used for the API. This MUST be in the form of an absolute URL. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example: @@ -582,7 +582,7 @@ Field Name | Type | Description parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Channel Item Object Example @@ -720,7 +720,7 @@ Field Name | Type | Description traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example @@ -829,7 +829,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Trait Object Example @@ -914,7 +914,7 @@ Field Name | Type | Description schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Example @@ -981,7 +981,7 @@ Field Name | Type | Description `mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#server) | Protocol-specific information for a Mercure server. `ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#server-binding-object) | Protocol-specific information for an IBM MQ server. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1011,7 +1011,7 @@ Field Name | Type | Description `mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#channel) | Protocol-specific information for a Mercure channel. `ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#channel-binding-object) | Protocol-specific information for an IBM MQ channel. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1040,7 +1040,7 @@ Field Name | Type | Description `redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#operation) | Protocol-specific information for a Redis operation. `mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#operation) | Protocol-specific information for a Mercure operation. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1071,7 +1071,7 @@ Field Name | Type | Description `mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#message) | Protocol-specific information for a Mercure message. `ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#message-binding-object) | Protocol-specific information for an IBM MQ message. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1103,7 +1103,7 @@ Field Name | Type | Description examples | [[Message Example Object](#messageExampleObject)] | List of examples. traits | [[Message Trait Object](#messageTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Schema formats table @@ -1301,7 +1301,7 @@ Field Name | Type | Description bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Message Trait Object Example @@ -1330,7 +1330,7 @@ Field Name | Type | Description name | `string` | A machine-friendly name. summary | `string` | A short summary of what the example is about. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Message Example Object Example @@ -1377,11 +1377,11 @@ Allows adding meta data to a single tag. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **Required.** The name of the tag. +name | `string` | **REQUIRED.** The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. 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 @@ -1412,9 +1412,9 @@ Allows referencing an external resource for extended documentation. Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -url | `string` | **Required.** The URL for the target documentation. This MUST be in the form of an absolute URL. +url | `string` | **REQUIRED.** The URL for the target documentation. This MUST be in the form of an absolute URL. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example @@ -1441,7 +1441,7 @@ For this specification, reference resolution is done as defined by the JSON Refe ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -$ref | `string` | **Required.** The reference string. +$ref | `string` | **REQUIRED.** The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. @@ -1481,7 +1481,7 @@ Field Name | Type | Description operationBindings | Map[`string`, [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operationBindingsObject). messageBindings | Map[`string`, [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Bindings Objects](#messageBindingsObject). -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\.\-_]+$`. @@ -1774,7 +1774,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 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). ###### Composition and Inheritance (Polymorphism) @@ -2482,7 +2482,7 @@ Field Name | Type | Description description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) that specifies the location of the correlation ID. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Examples