Merge pull request #539 from opengeospatial/part2-rfc-fixes2

Part 2 RFC comments update

extensions/pubsub/openapi/schemas/pubsub-message-payload-schema.yaml

@@ -21,6 +21,11 @@ properties:
     required:
       - pubtime
     properties:
+      resource_id:
+        type: string
+        description: |
+          Identifies a resource identifier that may have multiple message notifications on
+          its state or lifecycle over time.
       pubtime:
         type: string
         format: date-time

extensions/pubsub/standard/abstract_tests/ATS_class_pubsub_channels.adoc

@@ -3,5 +3,6 @@
 [%metadata]
 identifier:: http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0/conf/pubsub-message-channels
 target:: http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0/req/pubsub-message-channels
+dependency:: /conf/pubsub
 abstract-test:: /conf/pubsub-channels/channels
 ====

extensions/pubsub/standard/abstract_tests/ATS_class_pubsub_notification_message_payload.adoc

@@ -0,0 +1,10 @@
+[conformance_class]
+====
+[%metadata]
+identifier:: http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0/conf/pubsub-notification-message-payload
+target:: http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0/req/pubsub-notification-message-payload
+abstract-test:: /conf/pubsub-notification-message-payload/geojson
+abstract-test:: /conf/pubsub-notification-message-payload/id
+abstract-test:: /conf/pubsub-notification-message-payload/operation
+abstract-test:: /conf/pubsub-notification-message-payload/pubtime
+====

extensions/pubsub/standard/abstract_tests/pubsub-message-payload/ATS_test_geojson.adoc → extensions/pubsub/standard/abstract_tests/pubsub-notification-message-payload/ATS_test_geojson.adoc

@@ -1,8 +1,8 @@
 [abstract_test]
 ====
 [%metadata]
-identifier:: /conf/pubsub-message-payload/geojson
-target:: /req/pubsub-message-payload/geojson
+identifier:: /conf/pubsub-notification-message-payload/geojson
+target:: /req/pubsub-notification-message-payload/geojson
 test-purpose:: Validate that a notification message is a valid GeoJSON document.
 test-method::
 +

extensions/pubsub/standard/abstract_tests/pubsub-message-payload/ATS_test_id.adoc → extensions/pubsub/standard/abstract_tests/pubsub-notification-message-payload/ATS_test_id.adoc

@@ -1,8 +1,8 @@
 [abstract_test]
 ====
 [%metadata]
-identifier:: /conf/pubsub-message-payload/id
-target:: /req/pubsub-message-payload/id
+identifier:: /conf/pubsub-notification-message-payload/id
+target:: /req/pubsub-notification-message-payload/id
 test-purpose:: Validate that a notification message provides an `id` property that is a UUID.
 test-method::
 +

extensions/pubsub/standard/abstract_tests/pubsub-message-payload/ATS_test_operation.adoc → extensions/pubsub/standard/abstract_tests/pubsub-notification-message-payload/ATS_test_operation.adoc

@@ -1,8 +1,8 @@
 [abstract_test]
 ====
 [%metadata]
-identifier:: /conf/pubsub-message-payload/operation
-target:: /req/pubsub-message-payload/operation
+identifier:: /conf/pubsub-notification-message-payload/operation
+target:: /req/pubsub-notification-message-payload/operation
 test-purpose:: Validate that a notification message provides a `properties.operation` property.
 test-method::
 +

extensions/pubsub/standard/abstract_tests/pubsub-message-payload/ATS_test_pubtime.adoc → extensions/pubsub/standard/abstract_tests/pubsub-notification-message-payload/ATS_test_pubtime.adoc

@@ -1,8 +1,8 @@
 [abstract_test]
 ====
 [%metadata]
-identifier:: /conf/pubsub-message-payload/pubtime
-target:: /req/pubsub-message-payload/pubtime
+identifier:: /conf/pubsub-notification-message-payload/pubtime
+target:: /req/pubsub-notification-message-payload/pubtime
 test-purpose:: Validate that a notification message provides a `properties.pubtime` property.
 test-method::
 +

extensions/pubsub/standard/document.adoc

@@ -49,7 +49,7 @@ include::sections/clause_7_pubsub.adoc[]
 
 include::sections/clause_8_pubsub-channels.adoc[]
 
-include::sections/clause_9_pubsub-message-payload.adoc[]
+include::sections/clause_9_pubsub-notification-message-payload.adoc[]
 
 
 ////
@@ -59,7 +59,7 @@ include::sections/annex-a.adoc[]
 
 include::sections/annex-pubsub.adoc[]
 
-include::sections/annex-pubsub-message-payload.adoc[]
+include::sections/annex-pubsub-notification-message-payload.adoc[]
 
 include::sections/annex-use-cases.adoc[]
 

extensions/pubsub/standard/recommendations/pubsub-message-payload/PER_rc-operation.adoc → extensions/pubsub/standard/recommendations/pubsub-notification-message-payload/PER_rc-operation.adoc

@@ -1,7 +1,7 @@
-[[per_pubsub-message-payload_operation]]
+[[per_pubsub-notification-message-payload_operation]]
 [permission]
 ====
 [%metadata]
-identifier:: /per/pubsub-message-payload/operation
-part:: *A:* A Pub/Sub Notification Message MAY provide the `+properties.operation+` property to indicate if a resource has been inserted.
+identifier:: /per/pubsub-notification-message-payload/operation
+part:: *A:* A Pub/Sub Notification Message MAY provide the `+properties.operation+` property to indicate if a resource has been created.
 ====

extensions/pubsub/standard/recommendations/pubsub-notification-message-payload/REC_id.adoc

@@ -0,0 +1,7 @@
+[[rec_pubsub-notification-message-payload-id]]
+[recommendation]
+====
+[%metadata]
+identifier:: /rec/pubsub-notification-message-payload/id
+part:: For messsage payloads that provide notification metadata about a resource publication, a Pub/Sub notification message `+id+` property SHOULD use a UUID.
+====

extensions/pubsub/standard/recommendations/pubsub-notification-message-payload/REC_resource_id.adoc

@@ -0,0 +1,7 @@
+[[rec_pubsub-notification-message-payload-resource_id]]
+[recommendation]
+====
+[%metadata]
+identifier:: /rec/pubsub-notification-message-payload/resource_id
+part:: A Pub/Sub notification message `+properties.resource_id+` property SHOULD be used to identify a resource that may have multiple message notifications on its state or lifecycle over time.
+====

extensions/pubsub/standard/requirements/pubsub-channels/REQ_rc-channels.adoc

@@ -3,5 +3,5 @@
 ====
 [%metadata]
 identifier:: /req/pubsub-channels/channels
-part:: Channels (topic/destination/node depending on protocol) that communicate changes to resources in an OGC Web API SHALL be expressed within an AsyncAPI channel with an ``x-ogc-api-link`` object.
+part:: Channels (topic/destination/node depending on protocol) that communicate changes of resources in an OGC Web API SHALL be expressed within an identified AsyncAPI channel.
 ====

extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-geojson.adoc → extensions/pubsub/standard/requirements/pubsub-notification-message-payload/REQ_rc-geojson.adoc

@@ -1,7 +1,7 @@
-[[req_pubsub-message-payload_geojson]]
+[[req_pubsub-notification-message-payload_geojson]]
 [requirement]
 ====
 [%metadata]
-identifier:: /req/pubsub-message-payload/geojson
+identifier:: /req/pubsub-notification-message-payload/geojson
 part:: A Pub/Sub notification message encoding SHALL be compliant to IETF RFC7946 GeoJSON.
 ====

extensions/pubsub/standard/requirements/pubsub-notification-message-payload/REQ_rc-id.adoc

@@ -0,0 +1,7 @@
+[[req_pubsub-notification-message-payload_id]]
+[requirement]
+====
+[%metadata]
+identifier:: /req/pubsub-notification-message-payload/id
+part:: A Pub/Sub notification message SHALL provide an `+id+` property as a globally unique identifier for the message.
+====

extensions/pubsub/standard/requirements/pubsub-notification-message-payload/REQ_rc-operation.adoc

@@ -0,0 +1,7 @@
+[[req_pubsub-notification-message-payload_operation]]
+[requirement]
+====
+[%metadata]
+identifier:: /req/pubsub-notification-message-payload/operation
+part:: A Pub/Sub Notification Message SHALL provide the `+properties.operation+` property to indicate if a resource has been created, updated or deleted.
+====

extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-pubtime.adoc → extensions/pubsub/standard/requirements/pubsub-notification-message-payload/REQ_rc-pubtime.adoc

@@ -1,7 +1,7 @@
-[[req_pubsub-message-payload_pubtime]]
+[[req_pubsub-notification-message-payload_pubtime]]
 [requirement]
 ====
 [%metadata]
-identifier:: /req/pubsub-message-payload/pubtime
+identifier:: /req/pubsub-notification-message-payload/pubtime
 part:: A Pub/Sub notification message SHALL provide a `+properties.pubtime+` property in RFC3339 format.
 ====

extensions/pubsub/standard/requirements/requirements_class_pubsub_notification_message_payload.adoc

@@ -0,0 +1,13 @@
+[[rc_pubsub-notification-message-payload]]
+[requirements_class]
+.Requirements Class 'Publish-Subscribe (Pub/Sub) Notification Message Payloads'
+====
+[%metadata]
+identifier:: http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0/req/pubsub-notification-message-payload
+subject:: Pub/Sub
+inherit:: /req/pubsub
+requirement:: /req/pubsub-notification-message-payload/geojson
+requirement:: /req/pubsub-notification-message-payload/id
+requirement:: /req/pubsub-notification-message-payload/operation
+requirement:: /req/pubsub-notification-message-payload/pubtime
+====

extensions/pubsub/standard/sections/annex-a.adoc

@@ -15,12 +15,12 @@ include::../abstract_tests/pubsub-channels/ATS_test_channels.adoc[]
 
 === Conformance Class Publish-Subscribe (Pub/Sub) Message Payloads
 
-include::../abstract_tests/ATS_class_pubsub_message_payload.adoc[]
+include::../abstract_tests/ATS_class_pubsub_notification_message_payload.adoc[]
 
-include::../abstract_tests/pubsub-message-payload/ATS_test_geojson.adoc[]
+include::../abstract_tests/pubsub-notification-message-payload/ATS_test_geojson.adoc[]
 
-include::../abstract_tests/pubsub-message-payload/ATS_test_id.adoc[]
+include::../abstract_tests/pubsub-notification-message-payload/ATS_test_id.adoc[]
 
-include::../abstract_tests/pubsub-message-payload/ATS_test_operation.adoc[]
+include::../abstract_tests/pubsub-notification-message-payload/ATS_test_operation.adoc[]
 
-include::../abstract_tests/pubsub-message-payload/ATS_test_pubtime.adoc[]
+include::../abstract_tests/pubsub-notification-message-payload/ATS_test_pubtime.adoc[]

extensions/pubsub/standard/sections/annex-pubsub.adoc

@@ -91,44 +91,44 @@ Different Pub/Sub protocols are supported as additional server objects, and can
     channels:
         notify-collections:
             address: collections
-                x-ogc-api-link:
-                    rel: data
-                    type: application/json
-                    href: https://example.org/collections
-                message:
-                    $ref: '#/components/messages/collection_msg'
+            x-ogc-api-link:
+                rel: data
+                type: application/json
+                href: https://example.org/collections
+            message:
+                $ref: '#/components/messages/collection_msg'
         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'
+            x-ogc-api-link:
+                rel: collection
+                type: application/json
+                href: https://example.org/collections/wthr_stn
+            messages:
+                $ref: '#/components/messages/collection_msg'
         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'
+            x-ogc-api-link:
+                rel: collection
+                type: application/json
+                href: https://example.org/collections/stream_gage
+            messages:
+                $ref: '#/components/messages/collection_msg'
         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'
+            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:
             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'  
+            x-ogc-api-link:
+                rel: items
+                type: application/json
+                href: https://example.org/collections/stream_gage/items
+            messages:
+                $ref: '#/components/messages/stream_gage_msg'  
 ----
 ====
 
@@ -142,6 +142,8 @@ Different Pub/Sub protocols are supported as additional server objects, and can
 ** `collections/wthr_stn/items`
 ** `collections/stream_gage/items`
 
+The use of `x-ogc-api-link` demonstrates the capability to cross reference an AsyncAPI to an OGC API resource.
+
 ====
 [source,yaml]
 ----

extensions/pubsub/standard/sections/clause_2_conformance.adoc

@@ -5,12 +5,12 @@ Requirements for two standardization target types are considered:
 
 * API integration
 * Pub/Sub channels, and
-* Message payload
+* Notification message payloads
 
 Conformance with this Standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
 
 In order to conform to this Standard, a software implementation shall choose to implement:
 
 * Any one of the conformance levels specified in Annex A (normative).
 
-All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified.
+All requirements classes and conformance classes described in this document are owned by the standard(s) identified.

extensions/pubsub/standard/sections/clause_3_references.adoc

@@ -25,6 +25,4 @@ The following normative documents contain provisions that, through reference in
 
 * [[[OGC20-004,OGC 20-004]]], _DRAFT OGC API - Records - Part 1: Core_ (2020)
 
-* [[[OGC21-045,OGC 21-045]]], _DRAFT OGC Features and Geometries JSON - Part 1: Core_ (2021)
-
 * [[[RFC7946,RFC 7946]]], _GeoJSON_, https://www.rfc-editor.org/rfc/rfc7946

extensions/pubsub/standard/sections/clause_7_pubsub.adoc

@@ -39,18 +39,22 @@ Based on research and testing, the Pub/Sub White Paper recommended the use of As
 }
 ----
 
+NOTE: the media type for an AsyncAPI document may change in the future as decided by the AsyncAPI community.
+
 include::../requirements/pubsub/REQ_rc-api.adoc[]
 
 ==== Providing notification metadata as an OGC API endpoint
 
-For Brokers providing notification metadata (as opposed to actual data payloads), an implementation of OGC API Building Blocks can, in parallel, readily provide GeoJSON-based notification messages via an OGC API - Features endpoint. Providing message payloads via an implementation of OGC API Standard(s) provides the additional benefit of querying for past messages over time in case of a lost connection.
+For Brokers providing notification metadata (as opposed to actual data payloads), an implementation of OGC API Building Blocks can, in parallel, readily provide GeoJSON-based notification messages via an OGC API - Features endpoint. Providing message payloads via an implementation of OGC API Standard(s) provides the additional benefit of querying for past messages over time in case of a lost connection.  See <<pubsub-notification-message-payload-section>> for more information.
 
 ==== Providing Pub/Sub links to collection updates
 
 The links array could also provide references to the Pub/Sub capabilities available on the service. A *collection* link could reference a collection update notification channel.
 
 NOTE:  In the OGC API Suite of Standards, a https://docs.ogc.org/DRAFTS/20-024.html#collection-description[collection] is a geospatial https://docs.ogc.org/DRAFTS/20-024.html#resource-definition[resource] (such as a dataset) that may be available as one or more sub-resource https://docs.ogc.org/DRAFTS/20-024.html#distribution-definition[distributions] that conform to one or more OGC API standards. See https://docs.ogc.org/DRAFTS/20-024.html#rc-collections-section[OGC API-Common: Part 2]
 
+A link object can contain a `channel` property which provides the relevant channel or topic that a client can subscribe to after connecting to a Pub/Sub endpoint.  The value and syntax of the `channel` property is bound to the Pub/Sub protocol identified in the `type` property.
+
 .OGC API Pub/Sub link example to new collection notifications
 [source,json]
 ----
@@ -77,7 +81,7 @@ An OGC API - Features example
     "type": "application/json",
     "title": "Data notifications",
     "href": "mqtt://example.org:8883",
-    "channel": "collections/{collectionId}"
+    "channel": "collections/surface-weather-observations"
 }
 ----
 
@@ -91,7 +95,7 @@ An OGC API - EDR example
     "type": "application/json",
     "title": "Data notifications",
     "href": "mqtt://example.org:8883",
-    "channel": "collections/{collectionId}/items"
+    "channel": "collections/surface-weather-observations/items"
 }
 ----