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..2a1b2823 --- /dev/null +++ b/googlepubsub/README.md @@ -0,0 +1,184 @@ +# Google Cloud Pub/Sub Bindings + +This document defines how to describe Google Cloud Pub/Sub specific information with AsyncAPI. + + + +## Version + +Current version is `0.1.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 `0.1.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}`.)_ + + + +### Example + +```yaml +# ... +channels: + projects/your-project/topics/topic-avro-schema: + bindings: + googlepubsub: + schemaSettings: + encoding: avro + name: projects/your-project/schemas/message-avro +# ... + projects/jaydub-testing/topics/messages-proto-schema: + bindings: + googlepubsub: + messageStoragePolicy: + allowedPersistenceRegions: + - us-central1 + - us-central2 + - us-east1 + - us-east4 + - us-east5 + - us-east7 + - us-south1 + - us-west1 + - us-west2 + - us-west3 + - us-west4 + schemaSettings: + encoding: protobuf + name: projects/your-project/schemas/message-proto +# ... +``` + + + +## 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 `0.1.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 + + + +### Example + +```yaml +# ... +components: + messages: + messageAvroAsJSON: + bindings: + googlepubsub: + schema: + definition: | + { + "type" : "record", + "name" : "Message", + "fields" : [ + { + "name" : "message", + "type" : "string" + } + ] + } + name: projects/your-project/schemas/message-avro + type: avro + contentType: application/json + name: projects/your-project/schemas/message-avro + payload: + fields: + - name: message + type: string + name: Message + type: record + schemaFormat: application/vnd.apache.avro+yaml;version=1.9.0 + messageProto: + bindings: + googlepubsub: + schema: + definition: | + syntax = "proto2"; + + message Message { + required string message = 1; + } + name: projects/your-project/schemas/message-proto + type: protobuf + contentType: application/octet-stream + name: projects/your-project/schemas/message-proto + payload: true +# ... +``` + + + +## 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..b3949edd --- /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": [ + "0.1.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..ad10c1e2 --- /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": [ + "0.1.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