From 7ba02806729aa937fbf6fdd5388dd1689394c7a6 Mon Sep 17 00:00:00 2001 From: fmvilas Date: Sun, 10 Mar 2019 19:44:34 +0100 Subject: [PATCH 1/6] Add examples of RPC clients and servers --- examples/next/rpc-client.yml | 73 ++++++++++++++++++++++++++++++++++++ examples/next/rpc-server.yml | 72 +++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 examples/next/rpc-client.yml create mode 100644 examples/next/rpc-server.yml diff --git a/examples/next/rpc-client.yml b/examples/next/rpc-client.yml new file mode 100644 index 000000000..ff0d00eeb --- /dev/null +++ b/examples/next/rpc-client.yml @@ -0,0 +1,73 @@ +asyncapi: '2.0.0' +id: 'urn:rpc:example:client' +defaultContentType: application/json + +info: + title: RPC Client Example + description: This example demonstrates how to define an RPC client. + version: '1.0.0' + +servers: + - url: rabbitmq.example.org + scheme: amqp + +channels: + '{queue}': + parameters: + - name: queue + schema: + type: string + pattern: '^amq\\.gen\\-.+$' + protocolObjects: + amqp-0-9-1: + channelIsQueue: true + queue: + randomName: true + exclusive: true + subscribe: + operationId: receiveSumResult + correlationId: + location: $message.header#/correlation_id + protocolObjects: + amqp-0-9-1: + noAck: true + properties: + correlation_id: + type: string + message: + payload: + type: object + properties: + result: + type: number + examples: + - 7 + + rpc_queue: + protocolObjects: + amqp-0-9-1: + channelIsQueue: true + queue: + durable: false + publish: + operationId: requestSum + correlationId: + location: $message.header#/correlation_id + protocolObjects: + amqp-0-9-1: + ack: true + properties: + reply_to: + type: string + correlation_id: + type: string + message: + payload: + type: object + properties: + numbers: + type: array + items: + type: number + examples: + - [4,3] diff --git a/examples/next/rpc-server.yml b/examples/next/rpc-server.yml new file mode 100644 index 000000000..55c44c94c --- /dev/null +++ b/examples/next/rpc-server.yml @@ -0,0 +1,72 @@ +asyncapi: '2.0.0' +id: 'urn:rpc:example:server' +defaultContentType: application/json + +info: + title: RPC Server Example + description: This example demonstrates how to define an RPC server. + version: '1.0.0' + +servers: + - url: rabbitmq.example.org + scheme: amqp + +channels: + '{queue}': + parameters: + - name: queue + schema: + type: string + pattern: '^amq\\.gen\\-.+$' + protocolObjects: + amqp-0-9-1: + channelIsQueue: true + queue: + randomName: true + exclusive: true + publish: + operationId: sendSumResult + correlationId: + location: $message.header#/correlation_id + protocolObjects: + amqp-0-9-1: + ack: true + properties: + correlation_id: + type: string + message: + payload: + type: object + properties: + result: + type: number + examples: + - 7 + + rpc_queue: + protocolObjects: + amqp-0-9-1: + channelIsQueue: true + queue: + durable: false + subscribe: + operationId: sum + correlationId: + location: $message.header#/correlation_id + protocolObjects: + amqp-0-9-1: + properties: + reply_to: + type: string + correlation_id: + type: string + message: + payload: + type: object + properties: + numbers: + type: array + items: + type: number + examples: + - [4,3] From e3e6a8f2ca97f80a83c32d77541148f4e62dadc2 Mon Sep 17 00:00:00 2001 From: fmvilas Date: Mon, 11 Mar 2019 19:04:23 +0100 Subject: [PATCH 2/6] Adding to markdown and json-schema specs --- versions/next/asyncapi.md | 63 ++++++++++++++++++++++++++++++++++++++- versions/next/schema.json | 16 ++++++++-- 2 files changed, 76 insertions(+), 3 deletions(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index 1ee1a00ca..003ce49e0 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -61,6 +61,7 @@ Means that the [application](#definitionsApplication) is a [consumer](#definitio - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [Parameter Object](#parameterObject) + - [Protocol Object](#protocolObject) - [Correlation ID Object](#correlationIdObject) - [Specification Extensions](#specificationExtensions) @@ -516,6 +517,7 @@ Field Name | Type | Description subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation. publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation. parameters | [[Parameter Object](#parameterObject) | [Reference Object](#referenceObject)] | A list 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)). +protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form 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). @@ -539,6 +541,12 @@ This object can be extended with [Specification Extensions](#specificationExtens } } } + }, + "amqp-0-9-1": { + "channelIsQueue": true, + "queue": { + "exclusive": true + } } } ``` @@ -554,7 +562,10 @@ subscribe: user: $ref: "#/components/schemas/user" signup: - $ref: "#/components/schemas/signup" +amqp-0-9-1: + channelIsQueue: true + queue: + exclusive: true ``` Using `oneOf` to specify multiple messages per operation: @@ -599,6 +610,7 @@ Field Name | Type | Description description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. +protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. message | [Message Object](#messageObject) | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.** This object can be extended with [Specification Extensions](#specificationExtensions). @@ -633,6 +645,14 @@ This object can be extended with [Specification Extensions](#specificationExtens } } } + }, + "amqp-0-9-1": { + "noAck": true, + "properties": { + "correlation_id": { + "type": "string" + } + } } } ``` @@ -657,6 +677,11 @@ message: $ref: "#/components/schemas/userCreate" signup: $ref: "#/components/schemas/signup" +amqp-0-9-1: + noAck: true + properties: + correlation_id: + type: string ``` @@ -712,6 +737,42 @@ user.{userId}.signup: +#### Protocol Object + +Free-form key-value object describing protocol-specific definitions for a given channel or operation. + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{protocol} | `Map` | Protocol-specific information. This map is free-form and MUST not be validated by parsers. + +##### Protocol Object Example + +```json +{ + "amqp-0-9-1": { + "channelIsQueue": true, + "queue": { + "randomName": true, + "exclusive": true + } + } +} +``` + +```yaml +amqp-0-9-1: + channelIsQueue: true + queue: + randomName: true + exclusive: true +``` + + + + + #### Stream Object Holds the framing configuration and the read/write operations for the streaming API. diff --git a/versions/next/schema.json b/versions/next/schema.json index 573001dae..87f71e10f 100644 --- a/versions/next/schema.json +++ b/versions/next/schema.json @@ -550,6 +550,12 @@ "deprecated": { "type": "boolean", "default": false + }, + "protocolObjects": { + "type": "object", + "additionalProperties": { + "type": "object" + } } } }, @@ -573,8 +579,8 @@ "$ref": "#/definitions/schema" }, "$ref": { - "type": "string" - } + "type": "string" + } } }, "operation": { @@ -605,6 +611,12 @@ "operationId": { "type": "string" }, + "protocolObjects": { + "type": "object", + "additionalProperties": { + "type": "object" + } + }, "message": { "oneOf": [ { From 785325d474206a0dc1cbe20b99a639af40094774 Mon Sep 17 00:00:00 2001 From: fmvilas Date: Mon, 11 Mar 2019 19:20:56 +0100 Subject: [PATCH 3/6] Add it to message object too and fix examples --- examples/next/rpc-client.yml | 21 +++--- examples/next/rpc-server.yml | 23 +++--- versions/next/asyncapi.md | 19 ++--- versions/next/schema.json | 131 +++++++++++++++++------------------ 4 files changed, 90 insertions(+), 104 deletions(-) diff --git a/examples/next/rpc-client.yml b/examples/next/rpc-client.yml index ff0d00eeb..a983dec65 100644 --- a/examples/next/rpc-client.yml +++ b/examples/next/rpc-client.yml @@ -26,15 +26,12 @@ channels: exclusive: true subscribe: operationId: receiveSumResult - correlationId: - location: $message.header#/correlation_id protocolObjects: amqp-0-9-1: noAck: true - properties: - correlation_id: - type: string message: + correlationId: + location: $message.header#/correlation_id payload: type: object properties: @@ -51,17 +48,17 @@ channels: durable: false publish: operationId: requestSum - correlationId: - location: $message.header#/correlation_id protocolObjects: amqp-0-9-1: ack: true - properties: - reply_to: - type: string - correlation_id: - type: string message: + protocolObjects: + amqp-0-9-1: + properties: + reply_to: + type: string + correlationId: + location: $message.header#/correlation_id payload: type: object properties: diff --git a/examples/next/rpc-server.yml b/examples/next/rpc-server.yml index 55c44c94c..ad7093e4c 100644 --- a/examples/next/rpc-server.yml +++ b/examples/next/rpc-server.yml @@ -26,15 +26,12 @@ channels: exclusive: true publish: operationId: sendSumResult - correlationId: - location: $message.header#/correlation_id protocolObjects: amqp-0-9-1: ack: true - properties: - correlation_id: - type: string message: + correlationId: + location: $message.header#/correlation_id payload: type: object properties: @@ -51,16 +48,14 @@ channels: durable: false subscribe: operationId: sum - correlationId: - location: $message.header#/correlation_id - protocolObjects: - amqp-0-9-1: - properties: - reply_to: - type: string - correlation_id: - type: string message: + protocolObjects: + amqp-0-9-1: + properties: + reply_to: + type: string + correlationId: + location: $message.header#/correlation_id payload: type: object properties: diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index 003ce49e0..c692d1661 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -647,12 +647,7 @@ This object can be extended with [Specification Extensions](#specificationExtens } }, "amqp-0-9-1": { - "noAck": true, - "properties": { - "correlation_id": { - "type": "string" - } - } + "noAck": true } } ``` @@ -679,9 +674,6 @@ message: $ref: "#/components/schemas/signup" amqp-0-9-1: noAck: true - properties: - correlation_id: - type: string ``` @@ -877,6 +869,7 @@ Field Name | Type | Description description | `string` | A verbose explanation of the message. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. +protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -918,6 +911,11 @@ This object can be extended with [Specification Extensions](#specificationExtens "correlationId": { "description": "Default Correlation ID", "location": "$message.header#/correlationId" + }, + "amqp-0-9-1": { + "properties": { + "delivery_mode": 2 + } } } ``` @@ -949,6 +947,9 @@ payload: correlationId: description: Default Correlation ID location: $message.header#/correlationId +amqp-0-9-1: + properties: + delivery_mode: 2 ``` Example using Google's protobuf to define the payload: diff --git a/versions/next/schema.json b/versions/next/schema.json index 87f71e10f..bd5b1776b 100644 --- a/versions/next/schema.json +++ b/versions/next/schema.json @@ -728,81 +728,74 @@ } }, "message": { - "anyOf": [ - { + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-": { + "$ref": "#/definitions/vendorExtension" + } + }, + "properties": { + "schemaFormat": { + "type": "string" + }, + "contentType": { + "type": "string" + }, + "headers": { "type": "object", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/vendorExtension" - } + "additionalProperties": { + "oneOf": [ + { "$ref": "#/definitions/Reference" }, + {"$ref": "#/definitions/schema" } + ] } }, - { - "type": "object", - "additionalProperties": false, - "patternProperties": { - "^x-": { - "$ref": "#/definitions/vendorExtension" - } + "payload": {}, + "correlationId": { + "oneOf": [ + { "$ref": "#/definitions/Reference" }, + { "$ref": "#/definitions/correlationId" } + ] + }, + "tags": { + "type": "array", + "items": { + "$ref": "#/definitions/tag" }, - "properties": { - "schemaFormat": { - "type": "string" - }, - "contentType": { - "type": "string" - }, - "headers": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { "$ref": "#/definitions/Reference" }, - {"$ref": "#/definitions/schema" } - ] - } - }, - "payload": {}, - "correlationId": { - "oneOf": [ - { "$ref": "#/definitions/Reference" }, - { "$ref": "#/definitions/correlationId" } - ] - }, - "tags": { - "type": "array", - "items": { - "$ref": "#/definitions/tag" - }, - "uniqueItems": true - }, - "summary": { - "type": "string", - "description": "A brief summary of the message." - }, - "name": { - "type": "string", - "description": "Name of the message." - }, - "title": { - "type": "string", - "description": "A human-friendly title for the message." - }, - "description": { - "type": "string", - "description": "A longer description of the message. CommonMark is allowed." - }, - "externalDocs": { - "$ref": "#/definitions/externalDocs" - }, - "deprecated": { - "type": "boolean", - "default": false - }, - "example": {} + "uniqueItems": true + }, + "summary": { + "type": "string", + "description": "A brief summary of the message." + }, + "name": { + "type": "string", + "description": "Name of the message." + }, + "title": { + "type": "string", + "description": "A human-friendly title for the message." + }, + "description": { + "type": "string", + "description": "A longer description of the message. CommonMark is allowed." + }, + "externalDocs": { + "$ref": "#/definitions/externalDocs" + }, + "deprecated": { + "type": "boolean", + "default": false + }, + "example": {}, + "protocolObjects": { + "type": "object", + "additionalProperties": { + "type": "object" } } - ] + } }, "correlationId": { "type": "object", From e3866bf0f9ae68fbc4f83bf406b0a40f0880eb3c Mon Sep 17 00:00:00 2001 From: fmvilas Date: Mon, 11 Mar 2019 19:28:29 +0100 Subject: [PATCH 4/6] Fix broken link --- versions/next/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index c692d1661..f64982557 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -61,7 +61,7 @@ Means that the [application](#definitionsApplication) is a [consumer](#definitio - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [Parameter Object](#parameterObject) - - [Protocol Object](#protocolObject) + - [Protocol Object](#protocolObjectObject) - [Correlation ID Object](#correlationIdObject) - [Specification Extensions](#specificationExtensions) From ed391c245b24e9375cb9f05e1b41991d594c9832 Mon Sep 17 00:00:00 2001 From: fmvilas Date: Tue, 12 Mar 2019 11:13:38 +0100 Subject: [PATCH 5/6] Rename protocolObjects to protocolInfo --- versions/next/asyncapi.md | 16 ++++++++-------- versions/next/schema.json | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/versions/next/asyncapi.md b/versions/next/asyncapi.md index f64982557..55e4a06cf 100644 --- a/versions/next/asyncapi.md +++ b/versions/next/asyncapi.md @@ -61,7 +61,7 @@ Means that the [application](#definitionsApplication) is a [consumer](#definitio - [XML Object](#xmlObject) - [Security Scheme Object](#securitySchemeObject) - [Parameter Object](#parameterObject) - - [Protocol Object](#protocolObjectObject) + - [Protocol Info Object](#protocolInfoObject) - [Correlation ID Object](#correlationIdObject) - [Specification Extensions](#specificationExtensions) @@ -517,7 +517,7 @@ Field Name | Type | Description subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation. publish | [Operation Object](#operationObject) | A definition of the PUBLISH operation. parameters | [[Parameter Object](#parameterObject) | [Reference Object](#referenceObject)] | A list 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)). -protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. +protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form 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). @@ -610,7 +610,7 @@ Field Name | Type | Description description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of operations. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. -protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. +protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. message | [Message Object](#messageObject) | A definition of the message that will be published or received on this channel. `oneOf` is allowed here to specify multiple messages, however, **a message MUST be valid only against one of the referenced message objects.** This object can be extended with [Specification Extensions](#specificationExtensions). @@ -729,17 +729,17 @@ user.{userId}.signup: -#### Protocol Object +#### Protocol Info Object -Free-form key-value object describing protocol-specific definitions for a given channel or operation. +Free-form key-value object describing protocol-specific definitions for channels, operations, and messages. ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{protocol} | `Map` | Protocol-specific information. This map is free-form and MUST not be validated by parsers. +{protocol} | `Map` | Protocol-specific information. This map is free-form and MUST not be validated by parsers. -##### Protocol Object Example +##### Protocol Info Object Example ```json { @@ -869,7 +869,7 @@ Field Name | Type | Description description | `string` | A verbose explanation of the message. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. tags | [[Tag Object](#tagObject)] | A list of tags for API documentation control. Tags can be used for logical grouping of messages. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this message. -protocolObjects | Map[`string`, [Protocol Object](#protocolObjectObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. +protocolInfo | Map[`string`, [Protocol Info Object](#protocolInfoObject)] | A free-form map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. This object can be extended with [Specification Extensions](#specificationExtensions). diff --git a/versions/next/schema.json b/versions/next/schema.json index 397c19edf..d73773998 100644 --- a/versions/next/schema.json +++ b/versions/next/schema.json @@ -554,7 +554,7 @@ "type": "boolean", "default": false }, - "protocolObjects": { + "protocolInfo": { "type": "object", "additionalProperties": { "type": "object" @@ -614,7 +614,7 @@ "operationId": { "type": "string" }, - "protocolObjects": { + "protocolInfo": { "type": "object", "additionalProperties": { "type": "object" @@ -792,7 +792,7 @@ "default": false }, "example": {}, - "protocolObjects": { + "protocolInfo": { "type": "object", "additionalProperties": { "type": "object" From 43d5819332f738d40f21acca3d3259277bef859c Mon Sep 17 00:00:00 2001 From: fmvilas Date: Tue, 12 Mar 2019 11:14:55 +0100 Subject: [PATCH 6/6] Rename protocolObjects to protocolInfo in examples --- examples/next/rpc-client.yml | 10 +++++----- examples/next/rpc-server.yml | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/examples/next/rpc-client.yml b/examples/next/rpc-client.yml index a983dec65..c610931b5 100644 --- a/examples/next/rpc-client.yml +++ b/examples/next/rpc-client.yml @@ -18,7 +18,7 @@ channels: schema: type: string pattern: '^amq\\.gen\\-.+$' - protocolObjects: + protocolInfo: amqp-0-9-1: channelIsQueue: true queue: @@ -26,7 +26,7 @@ channels: exclusive: true subscribe: operationId: receiveSumResult - protocolObjects: + protocolInfo: amqp-0-9-1: noAck: true message: @@ -41,18 +41,18 @@ channels: - 7 rpc_queue: - protocolObjects: + protocolInfo: amqp-0-9-1: channelIsQueue: true queue: durable: false publish: operationId: requestSum - protocolObjects: + protocolInfo: amqp-0-9-1: ack: true message: - protocolObjects: + protocolInfo: amqp-0-9-1: properties: reply_to: diff --git a/examples/next/rpc-server.yml b/examples/next/rpc-server.yml index ad7093e4c..3f35d2c23 100644 --- a/examples/next/rpc-server.yml +++ b/examples/next/rpc-server.yml @@ -18,7 +18,7 @@ channels: schema: type: string pattern: '^amq\\.gen\\-.+$' - protocolObjects: + protocolInfo: amqp-0-9-1: channelIsQueue: true queue: @@ -26,7 +26,7 @@ channels: exclusive: true publish: operationId: sendSumResult - protocolObjects: + protocolInfo: amqp-0-9-1: ack: true message: @@ -41,7 +41,7 @@ channels: - 7 rpc_queue: - protocolObjects: + protocolInfo: amqp-0-9-1: channelIsQueue: true queue: @@ -49,7 +49,7 @@ channels: subscribe: operationId: sum message: - protocolObjects: + protocolInfo: amqp-0-9-1: properties: reply_to: