diff --git a/extensions/pubsub/examples/yaml/asyncapi.yaml b/extensions/pubsub/examples/yaml/asyncapi.yaml index 6ea80498e..a19482e19 100644 --- a/extensions/pubsub/examples/yaml/asyncapi.yaml +++ b/extensions/pubsub/examples/yaml/asyncapi.yaml @@ -1,4 +1,4 @@ -asyncapi: '2.5.0' +asyncapi: '3.0.0' info: title: AsyncAPI demo version: '0.0.1' @@ -10,34 +10,57 @@ info: servers: mqtt_prod: - url: example.org + host: example.org protocol: mqtt description: MQTT endpoint security: - user-password: [] + defaultContentType: application/json channels: - collections: - subscribe: - message: - $ref: '#/components/messages/collection_msg' - collections/wthr_stn: - subscribe: - message: - $ref: '#/components/messages/collection_msg' - collections/stream_gage: - subscribe: - message: - $ref: '#/components/messages/collection_msg' - collections/wthr_stn/items: - subscribe: - message: - $ref: '#/components/messages/wthr_stn_msg' - collections/stream_gage/items: - subscribe: - message: - $ref: '#/components/messages/stream_gage_msg' + notify-collections: + address: collections + messages: + $ref: '#/components/messages/collection_msg' + notify-collections-wthr-stn: + address: collections/wthr_st: + messages: + $ref: '#/components/messages/collection_msg' + notify-collections-stream-gage: + address: collections/stream_gage: + messages: + $ref: '#/components/messages/collection_msg' + notify-collections-wthr_stn-items: + address: collections/wthr_stn/items: + messages: + $ref: '#/components/messages/wthr_stn_msg' + notify-collections-stream_gage-items: + address: collections/stream_gage/items: + messages: + $ref: '#/components/messages/stream_gage_msg' + +operations: + notify-collections: + action: receive + channel: + $ref: '#/channels/notify-collections' + notify-collections-wthr-stn: + action: receive + channel: + $ref: '#/channels/notify-collections-wthr-stn' + notify-collections-stream-gage: + action: receive + channel: + $ref: '#/channels/notify-collections-stream_gage' + notify-collections-wthr_stn-items: + action: receive + channel: + $ref: '#/channels/notify-collections-wthr_stn-items' + notify-collections-stream_gage-items: + action: receive + channel: + $ref: '#/channels/notify-collections-stream_gage-items' components: messages: diff --git a/extensions/pubsub/standard/sections/annex-pubsub.adoc b/extensions/pubsub/standard/sections/annex-pubsub.adoc index f27f03a53..373e91731 100644 --- a/extensions/pubsub/standard/sections/annex-pubsub.adoc +++ b/extensions/pubsub/standard/sections/annex-pubsub.adoc @@ -10,7 +10,7 @@ The API is described using the https://www.asyncapi.com/[AysncAPI 2.5.0 specific ==== [source,yaml] ---- -include::../examples/yaml/asyncapi.yaml[] +include::../../examples/yaml/asyncapi.yaml[] ---- ==== @@ -19,7 +19,7 @@ Breaking down into the components: ==== [source,yaml] ---- - asyncapi: '2.5.0' + asyncapi: '3.0.0' info: title: AsyncAPI demo version: '0.0.1' @@ -30,7 +30,7 @@ Breaking down into the components: email: you@example.org ---- ==== -* The `asyncapi` field indicates you use the AsyncAPI version 2.5.0. +* The `asyncapi` field indicates you use the AsyncAPI version 3.0.0. * The `info` field holds information about the API, such as its name, version, description, and license. ==== @@ -38,7 +38,7 @@ Breaking down into the components: ---- servers: mqtt_prod: - url: example.org + host: example.org protocol: mqtt protocolVersion: 3.1.1 description: MQTT endpoint @@ -48,7 +48,7 @@ Breaking down into the components: ---- ==== * Each `server` object provides the following fields: - ** `url`: URL of the target broker (this may be relative to the API document) + ** `host`: the server hostname and port ** `protocol`: Pub/Sub protocol supported by the server ** `protocolVersion`: version of the Pub/Sub protocol supported by the server ** `description`: string describing the host @@ -58,7 +58,7 @@ Breaking down into the components: ---- servers: mqtt: - url: example.org + host: example.org protocol: mqtt protocolVersion: 3.1.1 description: MQTT endpoint @@ -68,7 +68,7 @@ servers: - 1883 default: 1883 amqp: - url: example.org + host: example.org protocol: amqp protocolVersion: 1.0.0 description: AMQP endpoint @@ -86,45 +86,45 @@ Different Pub/Sub protocols are supported as additional server objects, and can [source,yaml] ---- channels: - collections: - x-ogc-api-link: - rel: data - type: application/json - href: https://example.org/collections - subscribe: + notify-collections: + address: collections + x-ogc-api-link: + rel: data + type: application/json + href: https://example.org/collections message: $ref: '#/components/messages/collection_msg' - collections/wthr_stn: - x-ogc-api-link: - rel: collection - type: application/json - href: https://example.org/collections/wthr_stn - subscribe: - message: + notify-collections/wthr_stn: + address: collections/wthr_stn + x-ogc-api-link: + rel: collection + type: application/json + href: https://example.org/collections/wthr_stn + messages: $ref: '#/components/messages/collection_msg' - collections/stream_gage: - x-ogc-api-link: - rel: collection - type: application/json - href: https://example.org/collections/stream_gage - subscribe: - message: + notify-collections-stream_gage: + address: collections/stream_gage + x-ogc-api-link: + rel: collection + type: application/json + href: https://example.org/collections/stream_gage + messages: $ref: '#/components/messages/collection_msg' - collections/wthr_stn/items: - x-ogc-api-link: - rel: items - type: application/json - href: https://example.org/collections/stream_gage/items - subscribe: - message: + notify-collections-wthr_stn-items: + address: collections/wthr_stn/items + x-ogc-api-link: + rel: items + type: application/json + href: https://example.org/collections/stream_gage/items + messages: $ref: '#/components/messages/wthr_stn_msg' - collections/stream_gage/items: - x-ogc-api-link: - rel: items - type: application/json - href: https://example.org/collections/stream_gage/items - subscribe: - message: + collections-stream_gage-items: + address: collections/stream_gage/items + x-ogc-api-link: + rel: items + type: application/json + href: https://example.org/collections/stream_gage/items + messages: $ref: '#/components/messages/stream_gage_msg' ---- ==== @@ -139,6 +139,35 @@ Different Pub/Sub protocols are supported as additional server objects, and can ** `collections/wthr_stn/items` ** `collections/stream_gage/items` +==== +---- +[source,yaml] + operations: + notify-collections: + action: receive + channel: + $ref: '#/channels/notify-collections' + notify-collections-wthr-stn: + action: receive + channel: + $ref: '#/channels/notify-collections-wthr-stn' + notify-collections-stream-gage: + action: receive + channel: + $ref: '#/channels/notify-collections-stream_gage' + notify-collections-wthr_stn-items: + action: receive + channel: + $ref: '#/channels/notify-collections-wthr_stn-items' + notify-collections-stream_gage-items: + action: receive + channel: + $ref: '#/channels/notify-collections-stream_gage-items' +---- +==== + +* The `operations` section lists the required operations and their send and receive capabiliites. + ==== [source,yaml] ---- diff --git a/extensions/pubsub/standard/sections/clause_7_pubsub.adoc b/extensions/pubsub/standard/sections/clause_7_pubsub.adoc index beb8a0edc..68355a379 100644 --- a/extensions/pubsub/standard/sections/clause_7_pubsub.adoc +++ b/extensions/pubsub/standard/sections/clause_7_pubsub.adoc @@ -23,12 +23,6 @@ The OGC API building block approach would typically be used for shared component The above workflow requires adherence to a hierarchy of channels, auto-discovery of channels, as well as processing of generic messages for broad interoperability by all components. -==== Message payloads - -For smaller payload workflow, implementations of OGC API Standards can additionally provide a channel for notification metadata in order to receive a smaller message payload, which a user can process to determine whether to further interact with the referenced data granule or resource. - -include::../recommendations/pubsub/REC_message-payloads.adoc[] - ==== AsyncAPI Based on research and testing, the Pub/Sub White Paper recommended the use of AsyncAPI. AsyncAPI provides an event-driven equivalent of what is provided by OpenAPI for OGC API Standards (description of protocols, channels, parameters, models, etc.). An implementation of the https://ogcapi.ogc.org/common/overview.html[OGC API landing page requirements class] can provide a link to an AsyncAPI document as follows: diff --git a/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc b/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc index c2776cc93..4694e7aca 100644 --- a/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc +++ b/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc @@ -19,7 +19,6 @@ an OGC API implementation ecosystem. _GeoJSON_ can provide a compact and machine readable encoding as a baseline for message notification. include::../requirements/pubsub-message-payload/REQ_rc-geojson.adoc[] -include::../recommendations/pubsub-message-payload/REC_links.adoc[] ==== Identifier