From b1e7736071ccddc6c3d652bb2071cad4549f8a08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Gorej?= Date: Thu, 2 Nov 2023 06:59:43 +0100 Subject: [PATCH] docs: make usage of Schema Object consistent (#143) Co-authored-by: Sergio Moya <1083296+smoya@users.noreply.github.com>%0ACo-authored-by: Lukasz Gornicki --- anypointmq/README.md | 2 +- anypointmq/json_schemas/message.json | 11 +++++++++-- http/README.md | 7 ++++--- http/json_schemas/message.json | 11 +++++++++-- http/json_schemas/operation.json | 11 +++++++++-- kafka/README.md | 9 +++++++-- kafka/json_schemas/message.json | 11 +++++++++-- websockets/README.md | 7 ++++--- websockets/json_schemas/channel.json | 20 +++++++++++++++++--- 9 files changed, 69 insertions(+), 20 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index a56540a4..1f0a43b5 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -89,7 +89,7 @@ The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/m Field Name | Type | Description ---|:---:|--- -`headers` | [Schema Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject) | **OPTIONAL**. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of Anypoint MQ protocol headers are `messageId` and `messageGroupId`. +`headers` | [Schema Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject) \| [Reference Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject) | **OPTIONAL**. A Schema object containing the definitions for Anypoint MQ-specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of Anypoint MQ protocol headers are `messageId` and `messageGroupId`. `bindingVersion` | string | **OPTIONAL**, defaults to `latest`. The version of this binding. Note that application headers must be specified in the [`headers` field of the standard Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObjectHeaders) and are transmitted in the [`properties` section of the Anypoint MQ message](https://anypoint.mulesoft.com/exchange/portals/anypoint-platform/f1e97bc6-315a-4490-82a7-23abe036327a.anypoint-platform/anypoint-mq-broker/). diff --git a/anypointmq/json_schemas/message.json b/anypointmq/json_schemas/message.json index fa63cb5d..5e8ac1aa 100644 --- a/anypointmq/json_schemas/message.json +++ b/anypointmq/json_schemas/message.json @@ -7,12 +7,19 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + "$ref": "https://asyncapi.com/definitions/2.4.0/specificationExtension.json" } }, "properties": { "headers": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "A Schema object containing the definitions for Anypoint MQ-specific headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of Anypoint MQ protocol headers are 'messageId' and 'messageGroupId'." }, "bindingVersion": { diff --git a/http/README.md b/http/README.md index fbdda833..deb3c7bd 100644 --- a/http/README.md +++ b/http/README.md @@ -35,7 +35,7 @@ Field Name | Type | Description ---|:---:|--- `type` | string | **REQUIRED**. Type of operation. Its value MUST be either `request` or `response`. `method` | string | When `type` is `request`, this is the HTTP method, otherwise it MUST be ignored. Its value MUST be one of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, `CONNECT`, and `TRACE`. -`query` | [Schema Object][schemaObject] | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. +`query` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. @@ -74,7 +74,7 @@ This object contains information about the message representation in HTTP. Field Name | Type | Description ---|:---:|--- -`headers` | [Schema Object][schemaObject] | A Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type `object` and have a `properties` key. +`headers` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type `object` and have a `properties` key. `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. @@ -96,4 +96,5 @@ channels: bindingVersion: '0.1.0' ``` -[schemaObject]: https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject \ No newline at end of file +[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject +[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject \ No newline at end of file diff --git a/http/json_schemas/message.json b/http/json_schemas/message.json index 2437d2cc..faeeb089 100644 --- a/http/json_schemas/message.json +++ b/http/json_schemas/message.json @@ -7,12 +7,19 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + "$ref": "https://asyncapi.com/definitions/2.4.0/specificationExtension.json" } }, "properties": { "headers": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "\tA Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type 'object' and have a 'properties' key." }, "bindingVersion": { diff --git a/http/json_schemas/operation.json b/http/json_schemas/operation.json index 67483a4c..76873f1c 100644 --- a/http/json_schemas/operation.json +++ b/http/json_schemas/operation.json @@ -7,7 +7,7 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + "$ref": "https://asyncapi.com/definitions/2.4.0/specificationExtension.json" } }, "properties": { @@ -35,7 +35,14 @@ "description": "When 'type' is 'request', this is the HTTP method, otherwise it MUST be ignored. Its value MUST be one of 'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', and 'TRACE'." }, "query": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "A Schema object containing the definitions for each query parameter. This schema MUST be of type 'object' and have a properties key." }, "bindingVersion": { diff --git a/kafka/README.md b/kafka/README.md index cc75c77c..b9c153df 100644 --- a/kafka/README.md +++ b/kafka/README.md @@ -111,8 +111,8 @@ This object contains information about the operation representation in Kafka (eg Field Name | Type | Description | Applicability [default] | Constraints ---|:---:|:---:|:---:|--- -`groupId` | [Schema Object][schemaObject] | Id of the consumer group. | OPTIONAL | - -`clientId` | [Schema Object][schemaObject] | Id of the consumer inside a consumer group. | OPTIONAL | - +`groupId` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | Id of the consumer group. | OPTIONAL | - +`clientId` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | Id of the consumer inside a consumer group. | OPTIONAL | - `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. | OPTIONAL [`latest`] | - This object MUST contain only the properties defined above. @@ -145,10 +145,14 @@ This object contains information about the message representation in Kafka. Field Name | Type | Description ---|:---:|--- +<<<<<<< HEAD +`key` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. +======= `key` | [Schema Object][schemaObject] \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. **NOTE**: You can also use the [reference object](https://asyncapi.io/docs/specifications/v2.4.0#referenceObject) way. `schemaIdLocation` | string | If a Schema Registry is used when performing this operation, tells where the id of schema is stored (e.g. `header` or `payload`). | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level `schemaIdPayloadEncoding` | string | Number of bytes or vendor specific values when schema id is encoded in payload (e.g `confluent`/ `apicurio-legacy` / `apicurio-new`). | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level `schemaLookupStrategy` | string | Freeform string for any naming strategy class to use. Clients should default to the vendor default if not supplied. | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level +>>>>>>> master `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. @@ -189,3 +193,4 @@ channels: ``` [schemaObject]: https://www.asyncapi.com/docs/specifications/2.4.0/#schemaObject +[referenceObject]: https://www.asyncapi.com/docs/specifications/2.4.0/#referenceObject diff --git a/kafka/json_schemas/message.json b/kafka/json_schemas/message.json index 04a58158..17358277 100644 --- a/kafka/json_schemas/message.json +++ b/kafka/json_schemas/message.json @@ -6,12 +6,19 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.14.0/schemas/2.4.0.json#/definitions/specificationExtension" + "$ref": "https://asyncapi.com/definitions/2.4.0/specificationExtension.json" } }, "properties": { "key": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.14.0/schemas/2.4.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "The message key." }, "schemaIdLocation": { diff --git a/websockets/README.md b/websockets/README.md index 47b18121..8d67e068 100644 --- a/websockets/README.md +++ b/websockets/README.md @@ -29,8 +29,8 @@ When using WebSockets, the channel represents the connection. Unlike other proto Field Name | Type | Description ---|:---:|--- `method` | string | The HTTP method to use when establishing the connection. Its value MUST be either `GET` or `POST`. -`query` | [Schema Object][schemaObject] | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. -`headers` | [Schema Object][schemaObject] | A Schema object containing the definitions of the HTTP headers to use when establishing the connection. This schema MUST be of type `object` and have a `properties` key. +`query` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions for each query parameter. This schema MUST be of type `object` and have a `properties` key. +`headers` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) | A Schema object containing the definitions of the HTTP headers to use when establishing the connection. This schema MUST be of type `object` and have a `properties` key. `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. @@ -49,4 +49,5 @@ This object MUST NOT contain any properties. Its name is reserved for future use This object MUST NOT contain any properties. Its name is reserved for future use. -[schemaObject]: https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject \ No newline at end of file +[schemaObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject +[referenceObject]: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#referenceObject \ No newline at end of file diff --git a/websockets/json_schemas/channel.json b/websockets/json_schemas/channel.json index ebb51eea..15b3da52 100644 --- a/websockets/json_schemas/channel.json +++ b/websockets/json_schemas/channel.json @@ -7,7 +7,7 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + "$ref": "https://asyncapi.com/definitions/2.4.0/specificationExtension.json" } }, "properties": { @@ -20,11 +20,25 @@ "description": "The HTTP method to use when establishing the connection. Its value MUST be either 'GET' or 'POST'." }, "query": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "A Schema object containing the definitions for each query parameter. This schema MUST be of type 'object' and have a 'properties' key." }, "headers": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "oneOf": [ + { + "$ref": "https://asyncapi.com/definitions/2.4.0/schema.json" + }, + { + "$ref": "https://asyncapi.com/definitions/2.4.0/Reference.json" + } + ], "description": "A Schema object containing the definitions of the HTTP headers to use when establishing the connection. This schema MUST be of type 'object' and have a 'properties' key." }, "bindingVersion": {