Merge pull request #547 from opengeospatial/tk-updates-2024-05-30

address Public Review comments

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

@@ -21,7 +21,7 @@ properties:
     required:
       - pubtime
     properties:
-      resource_id:
+      resourceId:
         type: string
         description: |
           Identifies a resource identifier that may have multiple message notifications on

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

@@ -1,7 +1,7 @@
-[[rec_pubsub-notification-message-payload-resource_id]]
+[[rec_pubsub-notification-message-payload-resourceid]]
 [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.
+identifier:: /rec/pubsub-notification-message-payload/resourceid
+part:: A Pub/Sub notification message `+properties.resourceId+` property SHOULD be used to identify a resource that may have multiple message notifications on its state or lifecycle over time.
 ====

extensions/pubsub/standard/recommendations/pubsub/PER_links.adoc

@@ -4,5 +4,5 @@
 [%metadata]
 identifier:: /per/pubsub/links
 part:: A `collection` resource MAY provide a link reference to a Publish-Subscribe server from an OGC API implementation endpoint when Publish-Subscribe capabilities exist related to the `collection` service endpoint.
-part:: A Publish-Subscribe collection link reference MAY provide the `+channel+` property to allow for granular subscription.
+part:: A Publish-Subscribe collection link reference MAY provide a `+channel+` property to allow for granular subscription.
 ====

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

@@ -7,12 +7,6 @@ include::../abstract_tests/ATS_class_pubsub.adoc[]
 
 include::../abstract_tests//pubsub/ATS_test_api.adoc[]
 
-=== Conformance Class Publish-Subscribe (Pub/Sub) Channels
-
-include::../abstract_tests/ATS_class_pubsub_channels.adoc[]
-
-include::../abstract_tests/pubsub-channels/ATS_test_channels.adoc[]
-
 === Conformance Class Publish-Subscribe (Pub/Sub) Message Payloads
 
 include::../abstract_tests/ATS_class_pubsub_notification_message_payload.adoc[]

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

@@ -31,7 +31,7 @@ Breaking down into the components:
 ----
 ====
 
-* The `asyncapi` field indicates you use the AsyncAPI version 3.0.0.
+* The `asyncapi` field indicates you use the AsyncAPI version 3.0.
 * The `info` field holds information about the API, such as its name, version, description, and license.
 
 ====
@@ -91,42 +91,22 @@ 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'
         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'
         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'
         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:
             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'  
 ----
@@ -142,8 +122,6 @@ 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_0_front_material.adoc

@@ -65,3 +65,7 @@ All questions regarding this submission should be directed to the editor or the
 |Shane Mill |NOAA/NWS
 
 |===
+
+== Acknowledgements
+
+Thanks to the members of the Meteorology and Oceanography Domain Working Group of the OGC as well as Clemens Portele and all contributors of change requests and comments.

extensions/pubsub/standard/sections/clause_5_conventions.adoc

@@ -9,3 +9,35 @@ The normative provisions in this standard are denoted by the URI:
 `+http://www.opengis.net/spec/ogcapi-environmental-data-retrieval-2/1.0+`
 
 All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.
+
+=== Use of HTTPS
+
+For simplicity, this document in general only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS and simply is a shorthand notation for "HTTP or HTTPS." In fact, most servers are expected to use https://www.rfc-editor.org/rfc/rfc2818.html[HTTPS], not https://www.rfc-editor.org/rfc/rfc7230.html[HTTP].
+
+[[link-relations]]
+=== Link relations
+
+To express relationships between resources, https://www.rfc-editor.org/rfc/rfc8288.html[RFC 8288 (Web Linking)] is used.
+
+The following https://www.iana.org/assignments/link-relations/link-relations.xhtml[registered link relation types \[IANA\]] are used in this document.
+
+* **collection**: The target IRI points to a resource which represents the collection resource for the context IRI.
+
+* **item**: Refers to a resource that is a member of the collection represented by this context.
+
+* **service-desc**: Identifies service description for this context that is primarily intended for consumption by machines.  API definitions are considered service descriptions.
+
+In addition, the following link relation types are used for which no applicable registered link relation type could be identified.
+
+* **items**: Refers to a resource that is comprised of members of the collection represented by this context.
+* **http://www.opengis.net/def/rel/ogc/1.0/pubsub**: Refers to a resource that is accessible via an event driven is comprised of members of the collection represented by the link's context.
+
+Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. For example, an enclosure link could reference a bulk download of a collection. Or a related link on a record could reference a related record.
+
+=== Examples
+
+Most of the examples provided in this Standard are encoded in JSON. JSON was chosen because it is widely understood by implementers and easy to include in a text document. This convention should NOT be interpreted as a requirement that JSON must be used. Implementers are free to use any format they desire as long as there is a Conformance Class for that format and the deployed API advertises its support for the associated Conformance Class.
+
+=== Schemas
+
+AsyncAPI 2.0 Schema objects are used throughout this Standard to define the structure of resources. These schema are typically represented using YAML encoding. This convention is for the ease of the user. It does not prohibit the use of another schema language or encoding. Nor does it indicate that AsyncAPI 2.0 Schema objects are required. Implementations should use a schema language and encoding appropriate for the format of the resource.  Note that for property values in JSON for which `null` is not explicitly supported/required, server implementations are recommended to drop the property (as opposed to specifying the property with a value of `null`).

extensions/pubsub/standard/sections/clause_7_pubsub.adoc

@@ -53,14 +53,13 @@ The links array could also provide references to the Pub/Sub capabilities availa
 
 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.
+Communicating event driven workflow from a link object is made via the `+http://www.opengis.net/def/rel/ogc/1.0/pubsub+` link relation.  This link relation communicates that the link represents a Publish-Subscribe workflow defined by a Pub/Sub protocol in the `href` property as well as a `channel` property.  The `channel` property provides the relevant addressable 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 `href` property.
 
-.OGC API Pub/Sub link example to new collection notifications
+.Example of OGC API Pub/Sub link to new collection notifications
 [source,json]
 ----
 {
-    "rel": "collection",
-    "type": "application/json",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
     "title": "Data notifications",
     "href": "mqtt://example.org:8883",
     "channel": "collections"
@@ -73,12 +72,11 @@ An *items* link could reference a data payload channel:
 
 An OGC API - Features example
 
-.OGC API - Features example linking to a data payload channel
+.Example of OGC API - Features linking to a data payload channel
 [source,json]
 ----
 {
-    "rel": "items",
-    "type": "application/json",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
     "title": "Data notifications",
     "href": "mqtt://example.org:8883",
     "channel": "collections/surface-weather-observations"
@@ -87,12 +85,11 @@ An OGC API - Features example
 
 An OGC API - EDR example
 
-.OGC API - EDR example linking to a data payload channel
+.Example of OGC API - EDR linking to a data payload channel
 [source,json]
 ----
 {
-    "rel": "items",
-    "type": "application/json",
+    "rel": "http://www.opengis.net/def/rel/ogc/1.0/pubsub",
     "title": "Data notifications",
     "href": "mqtt://example.org:8883",
     "channel": "collections/surface-weather-observations/items"

extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc

@@ -10,12 +10,9 @@ include::../requirements/requirements_class_pubsub_channels.adoc[]
 The OGC API service endpoint specified by a URL path of resources and sub-resources can be used in parallel as a channel description when the data publisher wishes to provide Pub/Sub capability for resources normally available via an OGC API implementations instance in the same way. Below are examples of service endpoints or resources normally available via HTTP, and how they can be re-used as topics for Pub/Sub workflow:
 
 - ``/collections``: Notifies Subscribers whenever there is a change to the ``/collections`` resource (for example, addition of a new collection). The message payload would be collection metadata as defined in the https://docs.ogc.org/DRAFTS/20-024.html#collection-description[OGC API - Common Standard], or a message referencing the collection metadata.
-- ``/collections/{collectionId}``: Notifies Subscribers whenever there is an update to a single `collection` resource (for example, spatial or temporal extents, new items, etc.). The message payload would be defined by the resource model of the given collection (items, etc.), or a message referencing the resource model of the collection.
+
+- ``/collections/{collectionId}``: Notifies Subscribers whenever there is an update to a single `collection` resource (for example, spatial or temporal extents, new items, etc.). The message payload would be defined by either the resource model of the given collection (items, etc.), or a notification message of metadata referencing the collection with the relevant change.
 
 For example, users could use a subscription to metadata records, which are usually small compared to the source data, and are therefore more transportable. This informs and notifies the user of changes prior to requesting the possibly large source data, especially when bandwidth is at a premium.
 
 Using the OGC API service endpoints of the URL path of resource and sub-resources provides the key benefit that developers implementing OGC API Standards do not need to learn a different, additional approach or resource path for Pub/Sub (same content, additional interface).
-
-While AsyncAPI does not have native OpenAPI integration, in order to cross-reference a given AsyncAPI channel against its associated OGC API resource, the `+x-ogc-api-link+` object can be used.  The structure of this object is defined in OGC API - Common clause 8.1.
-
-include::../requirements/pubsub-channels/REQ_rc-channels.adoc[]

extensions/pubsub/standard/sections/clause_9_pubsub-notification-message-payload.adoc

@@ -11,7 +11,7 @@ representation or encoding. Notification messages can be issued using any encodi
 suitable by a given publisher.
 
 While the Publish-Subscribe (Pub/Sub) Requirements Class recommends a machine-readable message payload,
-the Message Payload Requirements Class provides further requirements for interoperability of message payloads as part of
+the Notification Message Payload Requirements Class provides further requirements for interoperability of message payloads as part of
 an OGC API implementation ecosystem.
 
 ==== GeoJSON
@@ -34,7 +34,7 @@ It remains the same throughout the lifetime of the message.  The identifier is v
 
 include::../requirements/pubsub-notification-message-payload/REQ_rc-id.adoc[]
 include::../recommendations/pubsub-notification-message-payload/REC_id.adoc[]
-include::../recommendations/pubsub-notification-message-payload/REC_resource_id.adoc[]
+include::../recommendations/pubsub-notification-message-payload/REC_resourceid.adoc[]
 
 ===== pubtime
 
@@ -88,5 +88,3 @@ and can be used to notify users that a resource has been created, updated or del
 ----
 
 include::../requirements/pubsub-notification-message-payload/REQ_rc-operation.adoc[]
-
-include::../recommendations/pubsub-notification-message-payload/PER_rc-operation.adoc[]