Merge pull request #464 from opengeospatial/pubsub-updates

refactor specification based on #451 and #452

.gitignore

@@ -4,3 +4,12 @@ candidate-standard/openapi/view_api.html
 19-086.html
 19-086.pdf
 ._19-086.pdf
+
+document.doc
+document.err
+document.err.html
+document.html
+document.presentation.xml
+document.xml
+iev/
+relaton/

extensions/pubsub/standard/document.adoc

@@ -46,7 +46,9 @@ include::sections/clause_6_informative_text.adoc[]
 
 include::sections/clause_7_pubsub.adoc[]
 
-include::sections/clause_8_pubsub-message-payload.adoc[]
+include::sections/clause_8_pubsub-channels.adoc[]
+
+include::sections/clause_9_pubsub-message-payload.adoc[]
 
 
 ////

extensions/pubsub/standard/recommendations/pubsub-channels/REC_message-payloads.adoc

@@ -0,0 +1,9 @@
+[[rec_pubsub-channels-message-payloads]]
+[recommendation,type="general",id="/rec/pubsub-channels/message-payloads", label="/rec/pubsub-channels/message-payloads"]
+====
+
+*A:*
+
+A Publish-Subscribe server's message payload SHOULD be machine readable to enable automated workflow.
+
+====

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

@@ -0,0 +1,14 @@
+[[per_pubsub_links]]
+
+[permission,type="general",id="/per/pubsub/links", label="/per/pubsub/links"]
+====
+
+*A:*
+
+An OGC API collection endpoint MAY provide a link reference to a Publish-Subscribe server from an OGC API endpoint when Publish-Subscribe capabilities exist related to the OGC API collection endpoint.
+
+*B:*
+
+A Publish-Subscribe collection link reference MAY provide the `+channel+` property to allow for granular subscription.
+
+====

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

@@ -1,6 +1,6 @@
-[[req_pubsub_channels]]
+[[req_pubsub-channels_channels]]
 
-[requirement,type="general",id="/req/pubsub/channels", label="/req/pubsub/channels"]
+[requirement,type="general",id="/req/pubsub-channels/channels", label="/req/pubsub-channels/channels"]
 ====
 
 *A:*

extensions/pubsub/standard/requirements/requirements_class_pubsub_channel.adoc

@@ -0,0 +1,8 @@
+[[rc_pubsub-channel]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.opengis.net/spec/ogcapi-edr-1/1.0/conf/pubsub-channel
+|Target type |Web API
+|Dependency |Core
+|===

extensions/pubsub/standard/sections/clause_7_pubsub.adoc

@@ -25,19 +25,11 @@ The OGC API building block approach is typically implemented for shared componen
 
 The above workflow requires adherence to a hierarchy of channels, autodiscovery of channels, as well as processing of generic messages for broad interoperabilty by all components.
 
-==== Channels, message payloads and OGC API endpoints
-
-The OGC API endpoint hierarchy can be used in parallel as a channel description when the data publisher wishes to provide Pub/Sub capability for OGC API resources normally available in the same way. Below are examples of OGC endpoints 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`` OGC API endpoint (for example, addition of a new collection). The message payload would be collection metadata as defined by OGC API - Common, or a message referencing same
-- ``/collections/{collectionId}``: notifies Subscribers whenever there is an update to a single collection (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 reference same
+==== Message payloads
 
 For smaller payload workflow, OGC APIs 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 reference data granule or resource.
 
-Using the OGC API endpoint hierarchy provides the key benefit that OGC API users do not need to learn a different, additional approach or hierarchy for Pub/Sub (same content, additional interface).
-
 include::../recommendations/pubsub/REC_message-payloads.adoc[]
-include::../requirements/pubsub/REQ_rc-channels.adoc[]
 
 ==== AsyncAPI
 
@@ -104,4 +96,4 @@ OGC API - EDR example
 }
 ----
 
-include::../requirements/pubsub/REQ_rc-links.adoc[]
+include::../recommendations/pubsub/PER_links.adoc[]

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

@@ -0,0 +1,18 @@
+[[pubsub-channels-section]]
+== Requirements Class Publish-Subscribe (Pub/Sub) Channels
+
+=== Overview
+
+include::../requirements/requirements_class_pubsub-channels.adoc[]
+
+==== Channels
+
+The OGC API endpoint hierarchy can be used in parallel as a channel description when the data publisher wishes to provide Pub/Sub capability for OGC API resources normally available in the same way. Below are examples of OGC endpoints 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`` OGC API endpoint (for example, addition of a new collection). The message payload would be collection metadata as defined by OGC API - Common, or a message referencing same
+- ``/collections/{collectionId}``: notifies Subscribers whenever there is an update to a single collection (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 reference same
+
+Using the OGC API endpoint hierarchy provides the key benefit that OGC API users do not need to learn a different, additional approach or hierarchy for Pub/Sub (same content, additional interface).
+
+include::../recommendations/pubsub-channels/REC_message-payloads.adoc[]
+include::../requirements/pubsub-channels/REQ_rc-channels.adoc[]