Merge pull request #521 from opengeospatial/chris-little-metanorma-ed…

…itorial

Update annex-a.adoc

extensions/pubsub/standard/document.adoc

@@ -7,9 +7,9 @@
 :draft: 1.0
 :external-id: http://www.opengis.net/doc/IS/ogcapi-edr-2/1.0
 :docnumber: 23-057
-:received-date: 2024-01-11
-:issued-date: 2024-01-11
-:published-date: 2024-01-11
+:received-date: 2024-02-16
+:issued-date: 2024-02-16
+:published-date: 2024-02-16
 :fullname: Tom Kralidis
 :role: editor
 :fullname_2: Chris Little

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

@@ -1,5 +1,5 @@
-[appendix]
-== Conformance Class Abstract Test Suite (Normative)
+[appendix,obligation="normative"]
+== Conformance Class Abstract Test Suite
 
 === Conformance Class Publish-Subscribe (Pub/Sub)
 
@@ -23,4 +23,4 @@ include::../abstract_tests/pubsub-message-payload/ATS_test_id.adoc[]
 
 include::../abstract_tests/pubsub-message-payload/ATS_test_operation.adoc[]
 
-include::../abstract_tests/pubsub-message-payload/ATS_test_pubtime.adoc[]
+include::../abstract_tests/pubsub-message-payload/ATS_test_pubtime.adoc[]

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

@@ -6,4 +6,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
+|2024-02-16 |0.3 |C. Little|all |workflow consistency
 |===

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

@@ -1,6 +1,6 @@
 [appendix,obligation="informative"]
 
-== Pub/Sub Message Payload Examples (Informative)
+== Pub/Sub Message Payload Examples
 
 [[message-payload-examples]]
 

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

@@ -1,6 +1,6 @@
-[appendix]
+[appendix,obligation="informative"]
 
-== Examples (Informative)
+== Examples
 
 [[async-examples]]
 === Pub/Sub API Description Example

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

@@ -1,15 +1,13 @@
-[appendix]
-== Use cases (Informative)
+[appendix,obligation="informative"]
+== Use cases 
 
 === Earth System Prediction model run and data granules notification
 
-A given numerical weather prediction system produces a weather forecast as part of a model run.  A model run typically has associated forecast hours.  Each forecast
-hour makes available one to many weather elements at different pressure levels.
+A given numerical weather prediction system produces a weather forecast as part of a model run.  A model run typically has associated forecast hours.  Each forecast hour makes available one or many weather elements at different pressure levels of the atmosphere.
 
-For example, Canada's Global Deterministic Prediction System (GDPS) produces two model runs per day, providing forecast of numerous weather elements for 33 pressure
-levels, at a resolution of 15 kilometres.footnote:[https://eccc-msc.github.io/open-data/msc-data/nwp_gdps/readme_gdps_en].
+For example, Canada's Global Deterministic Prediction System (GDPS) produces two model runs per day, providing forecast of numerous weather elements for 33 pressure levels, at a resolution of 15 kilometres.footnote:[https://eccc-msc.github.io/open-data/msc-data/nwp_gdps/readme_gdps_en].
 
-A Pub/Sub workflow can be applied for an NWP system where:
+A Pub/Sub workflow can be applied to an NWP system where:
 
 - notifications are sent as individual weather elements (data granules) become available
 - notifications are sent once the model run generation is complete, or "fully qualified"

extensions/pubsub/standard/sections/clause_0_front_material.adoc

@@ -1,12 +1,11 @@
-.Preface
-
+== Preface
 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.
+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 basis for Publish-Subscribe implementation patterns within the OGC API ecosystem.
 
 ////
 *OGC Declaration*
@@ -39,17 +38,6 @@ OGC APIs provide Web based capabilities which are typically based on polling for
 
 //Keywords inserted here by Metanorma
 
-
-== Preface
-
-====
-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.
-
-Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
-====
-
 == Security considerations
 
 //If no security considerations have been made for this Standard, use the following text.

extensions/pubsub/standard/sections/clause_3_references.adoc

@@ -5,30 +5,26 @@ The following normative documents contain provisions that, through reference in
 
 * [[[AMQP10,AMQP v1.0]]], _Advanced Message Queueing Protocol (AMQP) v1.0)_ https://www.oasis-open.org/standard/amqp
 
-* [[[MQTT311,MQTT v3.1.1]]], _MQTT Version 3.1.1 Plus Errata 01_ https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html
-
 * [[[MQTT50,MQTT v5.0]]], _MQTT Version 5.0_ https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html
 
-* [[[AsyncAPI250,AsyncAPI 2.5.0]]], _AsyncAPI Specification_ https://www.asyncapi.com/docs/reference/specification/v2.5.0
+* [[[AsyncAPI300,AsyncAPI 3.0.0]]], _AsyncAPI Specification_ https://www.asyncapi.com/docs/reference/specification/v3.0.0
 
-* [[[WIS2Guide,WMO WIS2 Guide]]], _Draft guidance on technical specifications of WIS 2.0_ https://wmo-im.github.io/wis2-guide
+* [[[WIS2Guide,WMO WIS2 Guide]]], _DRAFT WMO guidance on technical specifications of WIS 2.0_ https://wmo-im.github.io/wis2-guide
 
-* [[[WMO-WNM,WNM]]], _DRAFT WMO WIS2 Notification Message_ https://github.com/wmo-im/wis2-notification-message
+* [[[WMO-WNM,WMO WNM]]], _DRAFT WMO WIS2 Notification Message_ https://github.com/wmo-im/wis2-notification-message
 
-* [[[WMO-TOPICS,WMO-TOPICS]]], _DRAFT WMO WIS2 Topic Hierarchy_ https://github.com/wmo-im/wis2-topic-hierarchy
+* [[[WMO-TOPICS,WMO TOPICS]]], _DRAFT WMO WIS2 Topic Hierarchy_ https://github.com/wmo-im/wis2-topic-hierarchy
 
 * [[[WebSockets,WebSockets]]], _WebSockets_ https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
 
 * [[[IANALinkRelations,IANA Link Relations]]], _IANA Link Relations_ https://www.iana.org/assignments/link-relations/link-relations.xhtml
 
 * [[[OGC19-086r5,OGC 19-086r5]]], _OGC API - Environmental Data Retrieval Standard_ (2022)
 
-* [[[OGC06-121r9,OGC 06-121r9]]], _OGC Web Services Common Standard_ (2010)
-
 * [[[OGC17-069r4,OGC 17-069r4]]], _OGC API - Features - Part 1: Core corrigendum_ (2022)
 
 * [[[OGC20-004,OGC 20-004]]], _DRAFT OGC API - Records - Part 1: Core_ (2020)
 
-* [[[OGC21-045,OGC 21-045]]], _DRAFT OGC Feature and Geometriews JSON - Part 1: Core_ (2021)
+* [[[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_4_terms_and_definitions.adoc

@@ -1,28 +1,30 @@
-== Terms and definitions
+== Terms, definitions and abbreviated terms
+
+=== Terms and definitions
 
 This document uses the terms defined in Sub-clause 5.3 of <<OGC06-121r9>>, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "`shall`" (not "`must`") is the verb form used to indicate a requirement to be strictly followed to conform to this standard.
 
 For the purposes of this document, the following additional terms and definitions apply.
 
-=== Broker
+==== 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.
 
-=== Collection
+==== 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
+==== 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
+==== 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
+==== Subscriber
 An entity that creates a subscription to a Publisher.
 
-=== Message
+==== 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
+==== Channel
 A term (string) used to filter messages from a Broker.
 
 === Abbreviated terms

extensions/pubsub/standard/sections/clause_7_pubsub.adoc

@@ -28,6 +28,7 @@ The above workflow requires adherence to a structure of information channels, au
 
 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:
 
+.OGC API landing page example link to an AsyncAPI document
 [source,json]
 ----
 {
@@ -62,11 +63,13 @@ NOTE:  In the OGC API Suite of Standards, a https://docs.ogc.org/DRAFTS/20-024.h
 }
 ----
 
-An *items* link could reference a data payload channel:
+==== Providing Pub/Sub links to collection item notifications
 
-.OGC API Pub/Sub link examples to collection item notifications
+An *items* link could reference a data payload channel:
 
 An OGC API - Features example
+
+.OGC API - Features example linking to a data payload channel
 [source,json]
 ----
 {
@@ -79,6 +82,8 @@ An OGC API - Features example
 ----
 
 An OGC API - EDR example
+
+.OGC API - EDR example linking to a data payload channel
 [source,json]
 ----
 {

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

@@ -60,6 +60,7 @@ include::../requirements/pubsub-message-payload/REQ_rc-pubtime.adoc[]
 The ``operation`` property indicates the stage of the lifecycle for the resource described in the notification,
 and can be used to notify users that a resource has been updated or deleted. If not specified, the default value is ``create``.
 
+.Example operation property
 [source,json]
 ----
 "properties": {