Merge pull request #497 from opengeospatial/issue-488

Pub/Sub: fix doc refs and update to AsyncAPI 3

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:

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,15 +30,15 @@ Breaking down into the components:
             email: [email protected]
 ----
 ====
-* 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.
 
 ====
 [source,yaml]
 ----
     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]
 ----

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:

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