Merge pull request #495 from opengeospatial/chris-little-patch-1

chris-little · web-flow · commit 9a9171ae8c41 · 2024-01-12T14:29:37.000Z
Chris little patch editorial consistency
diff --git a/extensions/pubsub/standard/document.adoc b/extensions/pubsub/standard/document.adoc
@@ -1,4 +1,4 @@
-= OGC API - Environmental Data Retrieval - Part 2: Publish-Subscribe workflow
+= OGC API - Environmental Data Retrieval - Part 2: Publish-Subscribe Workflow
 :doctype: standard
 :encoding: utf-8
 :lang: en
@@ -7,14 +7,15 @@
 :draft: 1.0
 :external-id: http://www.opengis.net/doc/IS/ogcapi-edr-2/1.0
 :docnumber: 23-057
-:received-date: 2023-08-28
-:issued-date: 2023-08-28
-:published-date: 2023-08-28
+:received-date: 2024-01-11
+:issued-date: 2024-01-11
+:published-date: 2024-01-11
 :fullname: Tom Kralidis
 :role: editor
-:fullname_2: Mark Burgoyne
-:fullname_3: Steve Olson
-:fullname_4: Shane Mill
+:fullname_2: Chris Little
+:fullname_3: Mark Burgoyne
+:fullname_4: Steve Olson
+:fullname_5: Shane Mill
 :docsubtype: Interface
 :keywords: OGC API, Pub/Sub, Publish, Subscribe, Publish-Subscribe, Event driven architecture, Asynchronous, OGC document, OGC
 :submitting-organizations: Meteorological Service of Canada; UK Met Office; US National Weather Service;
diff --git a/extensions/pubsub/standard/recommendations/pubsub-message-payload/PER_operation.adoc b/extensions/pubsub/standard/recommendations/pubsub-message-payload/PER_operation.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-An OGC API Pub/Sub Notification Message MAY provide the `+properties.operation+` property to indicate if a resource has been inserted.
+A Pub/Sub Notification Message MAY provide the `+properties.operation+` property to indicate if a resource has been inserted.
 
 ====
diff --git a/extensions/pubsub/standard/recommendations/pubsub-message-payload/REC_crs.adoc b/extensions/pubsub/standard/recommendations/pubsub-message-payload/REC_crs.adoc
@@ -4,6 +4,6 @@
 
 *A:*
 
-An OGC API Pub/Sub notification message encoding describing data in a CRS other than WGS84 SHOULD use OGC Features and Geometries JSON.
+A Pub/Sub notification message encoding describing data in a CRS other than WGS84 SHOULD use OGC Features and Geometries JSON.
 
 ====
diff --git a/extensions/pubsub/standard/recommendations/pubsub/PER_links.adoc b/extensions/pubsub/standard/recommendations/pubsub/PER_links.adoc
@@ -5,7 +5,7 @@
 
 *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.
+A collection endpoint 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 endpoint.
 
 *B:*
 
diff --git a/extensions/pubsub/standard/recommendations/pubsub/PER_protocols.adoc b/extensions/pubsub/standard/recommendations/pubsub/PER_protocols.adoc
@@ -4,7 +4,7 @@
 
 *A:*
 
-A Publish-Subscribe MAY use the message queueing protocol of their choice/requirements.
+A Publish-Subscribe MAY use the message queueing protocol of their choice and/or based on application requirements.
 
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub-channels/REQ_rc-channels.adoc b/extensions/pubsub/standard/requirements/pubsub-channels/REQ_rc-channels.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-Channels (topic/destination/node depending on protocol) which have equivalent OGC API functionality SHALL be expressed within an AsyncAPI channel with an ``x-ogc-api-link`` object.
+Channels (topic/destination/node depending on protocol) that have equivalent API endpoint functionality SHALL be expressed within an AsyncAPI channel with an ``x-ogc-api-link`` object.
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-geojson.adoc b/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-geojson.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-An OGC API Pub/Sub notification message encoding SHALL be compliant to IETF RFC7946 GeoJSON.
+A Pub/Sub notification message encoding SHALL be compliant to IETF RFC7946 GeoJSON.
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-id.adoc b/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-id.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-An OGC API Pub/Sub notification message SHALL provide an `+id+` property as a GUID.
+A Pub/Sub notification message SHALL provide an `+id+` property as a GUID.
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-operation.adoc b/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-operation.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-An OGC API Pub/Sub Notification Message SHALL provide the `+properties.operation+` property to indicate if a resource has been updated or deleted.
+A Pub/Sub Notification Message SHALL provide the `+properties.operation+` property to indicate if a resource has been updated or deleted.
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-pubtime.adoc b/extensions/pubsub/standard/requirements/pubsub-message-payload/REQ_rc-pubtime.adoc
@@ -5,6 +5,6 @@
 
 *A:*
 
-An OGC API Pub/Sub notification message SHALL provide a `+properties.pubtime+` property in RFC3339 format.
+A Pub/Sub notification message SHALL provide a `+properties.pubtime+` property in RFC3339 format.
 
 ====
diff --git a/extensions/pubsub/standard/requirements/pubsub/REQ_rc-api.adoc b/extensions/pubsub/standard/requirements/pubsub/REQ_rc-api.adoc
@@ -5,12 +5,12 @@
 
 *A:*
 
-An OGC API landing page SHALL provide a link reference to the description of its Publish-Subscribe capabilities using a link relation of `+service-desc+`.
+A landing page SHALL provide a link reference to the description of its Publish-Subscribe capabilities using a link relation of `+service-desc+`.
 
 ---
 
 *B:*
 
-An OGC API SHALL provide the description of its Publish-Subscribe capabilities using AsyncAPI to describe supported protocols, channels and message payload descriptions.
+An API SHALL provide the description of its Publish-Subscribe capabilities using AsyncAPI to describe supported protocols, channels, and message payload descriptions.
 
 ====
diff --git a/extensions/pubsub/standard/sections/annex-bibliography.adoc b/extensions/pubsub/standard/sections/annex-bibliography.adoc
@@ -2,21 +2,8 @@
 [[Bibliography]]
 == Bibliography
 
-[NOTE]
-.Example Bibliography (Delete this note).
-===============================================
-The TC has approved Springer LNCS as the official document citation type.
-
-Springer LNCS is widely used in technical and computer science journals and other publications
-
-* For citations in the text please use square brackets and consecutive numbers: [1], [2], [3]
-
-– Actual References:
-
 [n] Journal: Author Surname, A.: Title. Publication Title. Volume number, Issue number, Pages Used (Year Published)
 
 [n] Web: Author Surname, A.: Title, http://Website-Url
 
-===============================================
-
 * [[[OGC2015,OGCTB12]]], _OGC: OGC Testbed 12 Annex B: Architecture_ (2015).
diff --git a/extensions/pubsub/standard/sections/annex-history.adoc b/extensions/pubsub/standard/sections/annex-history.adoc
@@ -5,4 +5,5 @@
 |===
 |Date |Release |Editor | Primary clauses modified |Description
 |2023-08-28 |0.1 |T. Kralidis|all |bootstrap
+|2024-01-10 |0.2 |C. Little|all |editorial consistency
 |===
diff --git a/extensions/pubsub/standard/sections/annex-pubsub-message-payload.adoc b/extensions/pubsub/standard/sections/annex-pubsub-message-payload.adoc
@@ -6,9 +6,9 @@
 
 === Pub/Sub Message Payload Example
 
-The WMO WIS2 standard notification message format ensures that the WIS2 ecosystem (data publisher, data user, and global services) is a robust, effective, and unified exchange platform for weather, climate, and water data. The message provides notification metadata about the availability of a new data granule. The message is encoded using a GeoJSON baseline, and provides detailed information on the data notification (associated datetime of the granule, publishing datetime, integrity), as well as access to the data via a link object or inline content (useful for encoding small messages). Geometry is required (given GeoJSON requirements), however can be expressed with a null value when generating the geometry in the message is not possible, practical or timely for data publishers. To support extensibility, additional properties are also valid (given the default definition in JSON Schema).
+The WMO WIS2 standard notification message format ensures that the WIS2 ecosystem (data publisher, data user, and global services) is a robust, effective, and unified exchange platform for weather, climate, and water data. The message provides notification metadata about the availability of a new data granule. The message is encoded using a GeoJSON object, and provides detailed information on the data notification (associated datetime of the granule, publishing datetime, integrity), as well as access to the data via a link object or inline content (useful for encoding small messages). Geometry is required (given GeoJSON requirements), however geometry can be expressed with a null value when generating the geometry in the message is not possible, practical or timely for data publishers. To support extensibility, additional properties are also valid (given the default definition in JSON Schema).
 
-Using a GeoJSON baseline as the message payload allows for broad interoperability given the large ecosystem of tooling (decoders, encoders) supporting the same approach. An example web application demonstrating the ease of integration can be found at https://kralidis.ca/tmp/wis2-data-notifications.html.
+Using a GeoJSON object as the message payload supports broad interoperability given the large ecosystem of tooling (decoders, encoders) supporting the same approach. An example web application demonstrating the ease of integration can be found at https://kralidis.ca/tmp/wis2-data-notifications.html.
 
 An example WIS2 Notification Message can be found below, extending the OGC API - Pub/Sub Notification Message Requirements with domain specific properties as required:
 
diff --git a/extensions/pubsub/standard/sections/clause_0_front_material.adoc b/extensions/pubsub/standard/sections/clause_0_front_material.adoc
@@ -1,8 +1,13 @@
 .Preface
 
-[NOTE]
 ====
-This specification provides an overview of Publish-Subscribe patterns specific to event driven data workflows, as well as options for realizing Publish-Subscribe workflow in OGC APIs. The document builds on the OGC Publish-Subscribe White Paper (OGC document 20-081), as well as the Discussion paper for Publish-Subscribe workflow in OGC APIs (OGC document 23-013), and provides a baseline for Pub/Sub within the OGC API ecosystem.
+The Environmental Data Retrieval - Part 2 Standard  provides:
+
+1. Requirements for Publish-Subscribe patterns specific to event driven data workflows and 
+
+2. Options for realizing Publish-Subscribe workflow in OGC APIs. 
+
+The Standard is based on the OGC Publish-Subscribe White Paper https://portal.ogc.org/files/?artifact_id=94904&version=1[OGC 20-081], as well as the Discussion paper for Publish-Subscribe workflow in OGC APIs https://docs.ogc.org/dp/23-013.html[OGC 23-013]. The goal of this Standard is to provide a baseline for Pub/Sub within the OGC API ecosystem.
 ====
 
 ////
@@ -30,7 +35,7 @@ Attention is drawn to the possibility that some of the elements of this document
 [abstract]
 == Abstract
 
-OGC APIs provide Web based capabilities which are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data updates. This specification provides recommendations on applying Publish-Subscribe architectural patterns to OGC APIs.
+OGC APIs provide Web based capabilities which are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data updates. The OGC API - Environmental Data Retrieval - Part 2: Publish-Subscribe Workflow provides recommendations on applying Publish-Subscribe architectural patterns to implementations of one or more OGC APIs.
 
 == Keywords
 
@@ -39,9 +44,8 @@ OGC APIs provide Web based capabilities which are typically based on polling for
 
 == Preface
 
-[NOTE]
 ====
-OGC APIs provide Web based capabilities which are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data updates. The following requirements and recommendations apply to Publish-Subscribe architectural patterns to OGC APIs.
+Implementations of OGC API Standards provide Web based capabilities that are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data updates. The following requirements and recommendations apply to Publish-Subscribe architectural patterns applicable to various OGC API Standards and their implementations.
 
 Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
 
@@ -73,9 +77,9 @@ All questions regarding this submission should be directed to the editor or the
 |*Name* |*Affiliation*
 
 |Tom Kralidis |Meteorological Service of Canada
-|Steve Olson |NOAA/NWS
 |Chris Little|UK Met Office
 |Mark Burgoyne|UK Met Office
+|Steve Olson |NOAA/NWS
 |Shane Mill |NOAA/NWS
 
 |===
diff --git a/extensions/pubsub/standard/sections/clause_1_scope.adoc b/extensions/pubsub/standard/sections/clause_1_scope.adoc
@@ -1,10 +1,10 @@
 == Scope
-[NOTE]
+
 ====
-This specification defines building blocks that can be assembled to implement Publish-Subscribe workflows (discovery, topic structure, encoding) as part of OGC API - Environmental Data Retrieval - Part 1: Core.
+The OGC API - Environmental Data Retrieval - Part 2: Publish-Subscribe Workflows Standard defines building blocks that can be assembled to implement Publish-Subscribe workflows (discovery, topic structure, encoding) as part of OGC API - Environmental Data Retrieval - Part 1: Core.
 
-This specification defines a discovery capability that contains a topic structure in support of binding to notifications for data access and retrieval.
+This Standard defines a discovery capability that contains a topic structure in support of binding to notifications for data access and retrieval.
 
-This specification defines a baseline message payload which can contain summary descriptive information in GeoJSON about a given notification for new data events (new granule, new model run, etc.).
+This Standard defines a baseline message payload which can contain summary descriptive information in GeoJSON about a given notification for new data events (new granule, new model run, etc.).
 
 ====
diff --git a/extensions/pubsub/standard/sections/clause_2_conformance.adoc b/extensions/pubsub/standard/sections/clause_2_conformance.adoc
@@ -1,15 +1,15 @@
 == Conformance
-This standard defines Publish-Subscribe patterns specific to event driven data workflows, as well as options for realizing Publish-Subscribe workflow in OGC APIs.
+This Standard defines Publish-Subscribe patterns specific to event driven data workflows, as well as options for realizing Publish-Subscribe workflows in implementations of OGC API Standards.
 
 Requirements for two standardization target types are considered:
 
 * API integration
-* Pubsub channels, and
+* Pub/Sub channels, and
 * Message payload
 
-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.
+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 OGC® interface standard, a software implementation shall choose to implement:
+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).
 * Any one of the Distributed Computing Platform profiles specified in Annexes TBD through TBD (normative).
diff --git a/extensions/pubsub/standard/sections/clause_3_references.adoc b/extensions/pubsub/standard/sections/clause_3_references.adoc
@@ -3,11 +3,6 @@
 
 The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.
 
-[NOTE]
-====
-Insert References here. If there are no references, leave this section empty.
-
-References are to follow the Springer LNCS style, with the exception that optional information may be appended to references: DOIs are added after the date and web resource references may include an access date at the end of the reference in parentheses. See examples from Springer and OGC below.
 ====
 
 * [[[AMQP10,AMQP v1.0]]], _Advanced Message Queueing Protocol (AMQP) v1.0)_ https://www.oasis-open.org/standard/amqp
diff --git a/extensions/pubsub/standard/sections/clause_4_terms_and_definitions.adoc b/extensions/pubsub/standard/sections/clause_4_terms_and_definitions.adoc
@@ -5,23 +5,27 @@ This document uses the terms defined in Sub-clause 5.3 of <<OGC06-121r9>>, which
 For the purposes of this document, the following additional terms and definitions apply.
 
 === Broker
-
 Intermediary between Subscribers and other Publishers which have been previously registered with the Broker. The Broker is not the original producer of Messages, but acts as an intermediary, (re-)publishing messages received from other Publishers and decoupling them from their Subscribers.
 
-=== Subscriber
+=== Collection
+A geospatial resource that may be available as one or more sub-resource distributions that conform to one or more OGC API standards. (OGC 20-024)
+
+=== Dataset
+A collection of data, published or curated by a single agent, and available for access or download in one or more representations. (DCAT)
+
+=== Distribution
+A specific representation of a dataset. A dataset might be available in multiple serializations that may differ in various ways, including natural language, media-type or format, schematic organization, temporal and spatial resolution, level of detail or profiles (which might specify any or all of the above). (DCAT)
 
+=== Subscriber
 An entity that creates a subscription to a Publisher.
 
 === Message
-
 A container within which data (such as JSON, XML, binary data, or other content) is transported. Messages may include additional information beyond data, including headers or other metadata used for routing or security purposes.
 
 === Channel
-
 A term (string) used to filter messages from a Broker.
 
 === Abbreviated terms
-
 AMQP::
   Advanced Message Queuing Protocol
 AMQPS::
diff --git a/extensions/pubsub/standard/sections/clause_6_informative_text.adoc b/extensions/pubsub/standard/sections/clause_6_informative_text.adoc
@@ -1,4 +1,4 @@
 [obligation=informative]
 == Overview
 
-OGC APIs provide Web based capabilities which are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data updates. The following requirements and recommendations apply to Publish-Subscribe architectural patterns to OGC APIs.
+Implementations of OGC API Standards provide Web based capabilities which are typically based on polling for collection resource updates (new features/records items, coverages, maps, etc.). Depending on a collection’s temporal resolution or frequency of updates, an event-driven / Publish-Subscribe architecture provides a time, efficient and low latency approach for delivery of data resource updates. The following requirements and recommendations apply to Publish-Subscribe architectural patterns for use with implementations of OGC API Standards.
diff --git a/extensions/pubsub/standard/sections/clause_7_pubsub.adoc b/extensions/pubsub/standard/sections/clause_7_pubsub.adoc
diff --git a/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc b/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc
diff --git a/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc b/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc
