diff --git a/CODEOWNERS b/CODEOWNERS index a4eb1bc7..502a20b0 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -8,8 +8,9 @@ * @derberg @fmvilas @asyncapi-bot-eve -/anypointmq/ @GeraldLoeffler -/ibmmq/ @rcoppen -/kafka/ @lbroudoux @dalelane -/solace/ @damaru-inc @CameronRushton -*.json @KhudaDad414 +/anypointmq/ @GeraldLoeffler +/ibmmq/ @rcoppen +/kafka/ @lbroudoux @dalelane +/googlepubsub/ @whitlockjc +/solace/ @damaru-inc @CameronRushton +*.json @KhudaDad414 diff --git a/README.md b/README.md index 3891c577..849447a7 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ This repository contains the specifications for each AsyncAPI protocol binding. * [AMQP binding](./amqp) * [AMQP 1.0 binding](./amqp1) +* [Google Cloud Pub/Sub binding](./googlepubsub) * [HTTP binding](./http) * [IBM MQ binding](./ibmmq) * [JMS binding](./jms) diff --git a/googlepubsub/README.md b/googlepubsub/README.md new file mode 100644 index 00000000..27b362ae --- /dev/null +++ b/googlepubsub/README.md @@ -0,0 +1,96 @@ +# Google Cloud Pub/Sub Bindings + +This document defines how to describe Google Cloud Pub/Sub specific information with AsyncAPI. + + + +## Version + +Current version is `1.0.0`. + + + +## Channel Binding Object + +The `Channel Bindings Object` is used to describe the Google Cloud Pub/Sub specific +[Topic](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create) details with AsyncAPI. + +Field Name | Type | Description +---|---|--- +`bindingVersion`|String|The current version is `1.0.0` +`labels`|Object|An object of key-value pairs _(These are used to categorize Cloud Resources like Cloud Pub/Sub Topics.)_ +`messageRetentionDuration`|String|Indicates the minimum duration to retain a message after it is published to the topic _(Must be a valid [Duration](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Duration).)_ +`messageStoragePolicy`|[Message Storage Policy Object](#message-storage-policy-object)|Policy constraining the set of Google Cloud Platform regions where messages published to the topic may be stored +`schemaSettings`|[Schema Settings Object](#schema-settings-object)|Settings for validating messages published against a schema + + + +### Message Storage Policy Object + +The `Message Storage Policy Object` is used to describe the Google Cloud Pub/Sub +[MessageStoragePolicy](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#MessageStoragePolicy) +Object with AsyncAPI. + +Field Name | Type | Description +---|---|--- +`allowedPersistenceRegions`|String[]|A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage + + + +### Schema Settings Object + +The `Schema Settings Object` is used to describe the Google Cloud Pub/Sub +[SchemaSettings](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#SchemaSettings) Object with +AsyncAPI. + +Field Name | Type | Description +---|---|--- +`encoding`|String|The encoding of the message _(Must be one of the possible [Encoding](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics#encoding) values.)_ +`firstRevisionId`|String|The minimum _(inclusive)_ revision allowed for validating messages +`lastRevisionId`|String|The maximum _(inclusive)_ revision allowed for validating messages +`name`|String|The name of the schema that messages published should be validated against _(Format is `projects/{project}/schemas/{schema}`.)_ + + + +## Message Binding Object + +The `Message Binding Object` is used to describe the Google Cloud Pub/Sub specific +[PubsubMessage](https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage) details, alongside with pertintent +parts of the Google Cloud Pub/Sub +[Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema) +Object, with AsyncAPI. + +Field Name | Type | Description +---|---|--- +`bindingVersion`|String|The current version is `1.0.0` +`attributes`|Object|An object of key-value pairs _(Attributes for this message.)_ +`orderingKey`|String|if non-empty, identifies related messages for which publish order should be respected +`schema`|[Schema Definition Object](#schema-definition-object)|Describes the schema used to validate the payload of this message + + + +### Schema Definition Object + +The `Schema Definition Object` is used to describe the Google Cloud Pub/Sub +[Schema]([Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema)) Object with AsyncAPI. +While some of this information could be, or is, described using native AsyncAPI, for consistency it makes sense to +provide this information here at all times, especially for cases where AsyncAPI does not natively support describing +payloads using a supported Google Cloud Pub/Sub schema format like Protobuf. + +Field Name | Type | Description +---|---|--- +`definition`|String|The definition of the schema +`name`|String|The name of the schema +`type`|String|The type of the schema + + + +## Operation Binding Object + +This object MUST NOT contain any properties. Its name is reserved for future use. + + + +## Server Binding Object + +This object MUST NOT contain any properties. Its name is reserved for future use. diff --git a/googlepubsub/json_schemas/channel.json b/googlepubsub/json_schemas/channel.json new file mode 100644 index 00000000..03440ecb --- /dev/null +++ b/googlepubsub/json_schemas/channel.json @@ -0,0 +1,79 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/amqp/channel.json", + "title": "Cloud Pub/Sub Channel Schema", + "description": "This object contains information about the channel representation for Google Cloud Pub/Sub.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "bindingVersion": { + "type": "string", + "enum": [ + "1.0.0" + ], + "description": "The version of this binding." + }, + "labels": { + "type": "object" + }, + "messageRetentionDuration": { + "type": "string" + }, + "messageStoragePolicy": { + "type": "object", + "additionalProperties": false, + "properties": { + "allowedPersistenceRegions": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "schemaSettings": { + "type": "object", + "additionalItems": false, + "properties": { + "encoding": { + "type": "string" + }, + "firstRevisionId": { + "type": "string" + }, + "lastRevisionId": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": ["encoding", "name"] + } + }, + "required": ["schemaSettings"], + "examples": [ + { + "labels": { + "label1": "value1", + "label2": "value2" + }, + "messageRetentionDuration": "7d", + "messageStoragePolicy": { + "allowedPersistenceRegions": [ + "us-central1", + "us-east1" + ] + }, + "schemaSettings": { + "encoding": "avro", + "schema": "projects/your-project-id/schemas/your-schema" + } + } + ] +} \ No newline at end of file diff --git a/googlepubsub/json_schemas/message.json b/googlepubsub/json_schemas/message.json new file mode 100644 index 00000000..a864feb2 --- /dev/null +++ b/googlepubsub/json_schemas/message.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/amqp/channel.json", + "title": "Cloud Pub/Sub Channel Schema", + "description": "This object contains information about the message representation for Google Cloud Pub/Sub.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "bindingVersion": { + "type": "string", + "enum": [ + "1.0.0" + ], + "description": "The version of this binding." + }, + "attributes": { + "type": "object" + }, + "orderingKey": { + "type": "string" + }, + "schema": { + "type": "object", + "additionalItems": false, + "properties": { + "definition": { + "type": "string" + }, + "name": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "required": ["definition", "name", "type"] + } + }, + "examples": [ + { + "schema": { + "definition": "{\n \"type\" : \"record\",\n \"name\" : \"Message\",\n \"fields\" : [\n {\n \"name\" : \"message\",\n \"type\" : \"string\"\n }\n ]\n}\n", + "name": "projects/your-project-id/schemas/your-avro-schema-id", + "type": "avro" + } + }, + { + "schema": { + "definition": "syntax = \"proto2\";\n\nmessage Message {\n required string message = 1;\n}\n", + "name": "projects/your-project-id/schemas/your-protobuf-schema-id", + "type": "protobuf" + } + } + ] +} \ No newline at end of file