diff --git a/extensions/pubsub/standard/document.adoc b/extensions/pubsub/standard/document.adoc index 0e9cf6ace..186980838 100644 --- 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 index df726ca4d..ca83e485b 100644 --- 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 index df13fd1b9..9b01f8710 100644 --- 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 index 65932dbc5..e3ab58b48 100644 --- 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 index 4ebb532fc..f011f8067 100644 --- 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 index 7fb911df5..f5e436e36 100644 --- 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 index 23a4f2294..374ec4fcd 100644 --- 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 index 086777fb2..b30bb1886 100644 --- 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 index dd4b94ebb..6428d5eb5 100644 --- 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 index e0b81ec6b..65d9189d2 100644 --- 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 index e810981ec..391cb90fd 100644 --- 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 index 50401467d..93a7f3ebb 100644 --- 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 index 991a86b99..24fdbe97e 100644 --- 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 index adce1e706..1709c4c17 100644 --- 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 index b7a591ae6..af9fdf90b 100644 --- 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 index 67fa13aa3..9c4edbd9a 100644 --- 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 index eb7f65ef7..691ff1131 100644 --- 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 index 871f47aa4..19c7a5c05 100644 --- 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 index fa7ed1284..a2b36e4d8 100644 --- 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 <>, 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 index 98c374942..7c28a39ed 100644 --- 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 index 4f75aeb34..beb8a0edc 100644 --- a/extensions/pubsub/standard/sections/clause_7_pubsub.adoc +++ b/extensions/pubsub/standard/sections/clause_7_pubsub.adoc @@ -1,41 +1,38 @@ [[pubsub-section]] == Requirements Class Publish-Subscribe (Pub/Sub) -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. - === Overview include::../requirements/requirements_class_pubsub.adoc[] -Event-driven workflows provide publish-subscribe based capabilities as part of information systems and architectures. The publish-subscribe model also provides efficiencies in providing data "as it happens", thereby alleviating potential clients from continuous polling to check on the availability of new data/resources. +Event-driven workflows provide Publish-Subscribe based capabilities as part of information systems and architectures. The Publish-Subscribe model also provides efficiencies in providing data "as it happens", thereby preventing potential clients from continuous polling to check on the availability of new data or resources. -The Open Geospatial Consortium (OGC) has conducted significant work on event-based models and architectures. The publish-subscribe model results in less network traffic and more timely responses to manage event-based models such as urgent, temporally unpredictable data (examples include, but are not limited to: weather or hazard warnings, sensor data). +The Open Geospatial Consortium (OGC) has conducted significant work on event-based models and architectures. The Publish-Subscribe model results in less network traffic and more timely responses to manage event-based models such as urgent, temporally unpredictable data (examples include, but are not limited to: traffic conditions, weather or hazard warnings, and real-time sensor data). -Building on the OGC Publish-Subscribe Interface Standard, as well as the recommendations put forward in the OGC Pub/Sub White Paper (OGC 20-046) produced as part of OGC Testbed 12, as well as the Discussion paper for Publish-Subscribe workflow in OGC APIs (OGC 23-013) this specification discusses approaches for integrating publish-subscribe architecture into the OGC API suite of standards. +Building on the OGC Publish-Subscribe Interface Standard https://docs.ogc.org/is/13-131r1/13-131r1.html[OGC 13-131r1], as well as the recommendations put forward in the OGC Pub/Sub White Paper [OGC 20-046] produced as part of OGC Testbed 12, as well as the Discussion paper for Publish-Subscribe workflow in OGC APIs [OGC 23-013], the EDR - Part 2: Publish-Subscribe Standard discusses approaches for integrating Publish-Subscribe architecture into the OGC API suite of Standards. include::../recommendations/pubsub/PER_protocols.adoc[] === OGC API Considerations -The OGC API building block approach is typically implemented for shared components of APIs in support of polling workflow. This means the client initiates and invokes requests and receives responses from the server, using HTTP. A key concept of the OGC API building blocks is the endpoint hierarchy, which can be applied for Pub/Sub workflow as follows: +The OGC API building block approach would typically be used for shared components in API implementations in support of a polling workflow. Using HTTP, this means that the client initiates and invokes requests and receives responses from the server. A key concept of the OGC API building blocks architecture is the endpoint hierarchy, which can be applied for Pub/Sub workflow as follows: -* data producers: messages are published to a broker, applied to a given channel (example: ``collections/mycollection``) -* broker provisioning: published messages are sent to subscribers -* subscribers and data consumers: messages are received by users subscribed to one or more channels (explicitly or using wildcards/filtering) +* Data producers: Messages are published to a broker, applied to a given channel (example: ``collections/mycollection``). +* Broker provisioning: Published messages are sent to subscribers. +* Subscribers and data consumers: Messages are received by users subscribed to one or more channels (explicitly or using wildcards or filtering). -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. +The above workflow requires adherence to a hierarchy of channels, auto-discovery of channels, as well as processing of generic messages for broad interoperability by all components. ==== 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. +For smaller payload workflow, implementations of OGC API Standards 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 referenced data granule or resource. include::../recommendations/pubsub/REC_message-payloads.adoc[] ==== AsyncAPI -Following the recommendations of the Pub/Sub White Paper, AsyncAPI provides an event-driven equivalent of what is provided by OpenAPI for OGC APIs (description of protocols, channels, parameters, models, etc.). An OGC API landing page can provide a link to an AsyncAPI document as follows: +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 AsyncAPI link example [source,json] ---- { @@ -50,11 +47,13 @@ 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 OGC API can, in parallel, easily provide GeoJSON-based notification messages via an OGC API - Features endpoint. Providing message payloads via an OGC API 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. ==== 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: +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] .OGC API Pub/Sub link example to new collection notifications [source,json] @@ -70,9 +69,9 @@ The links array could also provide references to the Pub/Sub capabilities availa An *items* link could reference a data payload channel: -.OGC API Pub/Sub link example to collection item notifications +.OGC API Pub/Sub link examples to collection item notifications -OGC API - Features example +An OGC API - Features example [source,json] ---- { @@ -84,7 +83,7 @@ OGC API - Features example } ---- -OGC API - EDR example +An OGC API - EDR example [source,json] ---- { diff --git a/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc b/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc index 063ef7af3..9e60fd13f 100644 --- a/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc +++ b/extensions/pubsub/standard/sections/clause_8_pubsub-channels.adoc @@ -7,12 +7,12 @@ 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: +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 resources normally available via an OGC API implementations instance in the same way. Below are examples of 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 +- ``/collections``: Notifies Subscribers whenever there is a change to the ``/collections`` endpoint (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 (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. -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). +Using the OGC API endpoint hierarchy provides the key benefit that developers implementing OGC API Standards do not need to learn a different, additional approach or hierarchy for Pub/Sub (same content, additional interface). include::../requirements/pubsub-channels/REQ_rc-channels.adoc[] include::../recommendations/pubsub-channels/REC_message-payloads.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 index 46f615f5f..c2776cc93 100644 --- a/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc +++ b/extensions/pubsub/standard/sections/clause_9_pubsub-message-payload.adoc @@ -5,18 +5,18 @@ include::../requirements/requirements_class_pubsub_message_payload.adoc[] -A key component of Pub/Sub workflows is message payload. Once a client subscribes to one or more -channels from a given Pub/Sub server, notifications messages are sent accordingly using a given -representation or encoding. Notification messages can be put forth using any encoding that is deemed +A key component of Pub/Sub workflows is the message payload. Once a client subscribes to one or more +channels from a given Pub/Sub server, notifications messages are sent using a given +representation or encoding. Notification messages can be issued using any encoding that is deemed suitable by a given publisher. -While the Publish-Subscribe (Pub/Sub) Requirements Class recommended a machine readable message payload, -this Requirements Class provides further requirements for interoperability of message payloads as part of -an OGC API ecosystem. +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 +an OGC API implementation ecosystem. ==== GeoJSON compliance -_GeoJSON_ provides a compact and machine readable encoding as a baseline for message notification. +_GeoJSON_ can provide a compact and machine readable encoding as a baseline for message notification. include::../requirements/pubsub-message-payload/REQ_rc-geojson.adoc[] include::../recommendations/pubsub-message-payload/REC_links.adoc[] @@ -36,9 +36,7 @@ include::../requirements/pubsub-message-payload/REQ_rc-id.adoc[] ===== pubtime -The ``pubtime`` property identifies the date/time of when the message was posted/published, in RFC3339 format, in -the UTC timezone (``Z``). The publication date/time is critical for subscribers to prevent message loss in -providing awareness of how far behind the publisher they may be). +The ``pubtime`` property identifies the date/time of when the message was posted/published. `datetime` is published as specified in RFC3339 Clause 5.6 in the UTC timezone (``Z``). The publication date/time is critical for subscribers to prevent message loss in providing awareness of how far behind the publisher they may be. .Example pubtime property [source,json] @@ -55,8 +53,7 @@ include::../requirements/pubsub-message-payload/REQ_rc-pubtime.adoc[] ===== operation 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. The default value if not specified -is ``create``. +and can be used to notify users that a resource has been updated or deleted. If not specified, the default value is ``create``. [source,json] ----